JSONSchemaType with TypeScript is broken

[jpilgrim]

What version of Ajv are you using? Does the issue happen if you use the latest version?

8.17.1

TypeScript version

5.8.3

Ajv options object

// none

JSON Schema

For the bug report, I used the JSON from the documentation https://ajv.js.org/guide/typescript.html#utility-types-for-schemas

{
    "type": "object",
    "properties": {
        "foo": { "type": "integer" },
        "bar": { "type": "string", "nullable": true }
    },
    "required": ["foo"],
    "additionalProperties": false
}

Sample data

It's only about typing.

Your code

It's similar to the code in the documentation https://ajv.js.org/guide/typescript.html#utility-types-for-schemas, except that the JSON string is not written as string literal as part of the initialization, but separately

const schemaFromObject = {
        "type": "object",
        "properties": {
            "foo": { "type": "integer" },
            "bar": { "type": "string", "nullable": true }
        },
        "required": ["foo"],
        "additionalProperties": false
    }
const schema: JSONSchemaType<MyData> = schemaFromObject;

I also have variants reading the JSON from other files etc., which are also not working. But this is the smallest change compared to the documentation.

Expected Result

This code should work similar to https://ajv.js.org/guide/typescript.html#utility-types-for-schemas

Actual Result

A type error is emitted (by tsc):

Type '{ type: string; properties: { foo: { type: string; }; bar: { type: string; nullable: boolean; }; }; required: string[]; additionalProperties: boolean; }' is not assignable to type 'JSONSchemaType<MyData>'.
  Type '{ type: string; properties: { foo: { type: string; }; bar: { type: string; nullable: boolean; }; }; required: string[]; additionalProperties: boolean; }' is not assignable to type '({ anyOf: readonly UncheckedJSONSchemaType<MyData, false>[]; } & { [keyword: string]: any; $id?: string | undefined; $ref?: string | undefined; $defs?: Record<string, UncheckedJSONSchemaType<...>> | undefined; definitions?: Record<...> | undefined; }) | ({ ...; } & { ...; })'.
    Type '{ type: string; properties: { foo: { type: string; }; bar: { type: string; nullable: boolean; }; }; required: string[]; additionalProperties: boolean; }' is not assignable to type '{ oneOf: readonly UncheckedJSONSchemaType<MyData, false>[]; } & { [keyword: string]: any; $id?: string | undefined; $ref?: string | undefined; $defs?: Record<string, UncheckedJSONSchemaType<...>> | undefined; definitions?: Record<...> | undefined; }'.
      Property 'oneOf' is missing in type '{ type: string; properties: { foo: { type: string; }; bar: { type: string; nullable: boolean; }; }; required: string[]; additionalProperties: boolean; }' but required in type '{ oneOf: readonly UncheckedJSONSchemaType<MyData, false>[]; }'.ts(2322)
json-schema.d.ts(25, 5): 'oneOf' is declared here.
---
const schema: JSONSchemaType<MyData>

Remarks

There are a lot of related reports, here is only a list of some of them:

• A schema for a TypeScript interface with a Date property falsely expects oneOf in the schema #2521
• UncheckedJSONSchemaType ['type'] field does not support 'array', 'object', and 'null' in an array #2518
• JSONSchemaType fails wiht type when a field is declared nullable #2283
• JSONSchema with allOf throws unexpected typescript compiler error #2227
• typescript JSONSchemaType #2043
• Typescript undefined type is not supported by schema type utilities #2040
• SomeJSONSchema does not accept correct JSONSchemaType object #1988
• The type definition of $ref not correctly resolve #1845
• JSONSchemaType incorrectly requires optional properties to be nullable #1664
• JSONSchemaType requires "required" and "additionalProperties", unless it is oneOf schema #1521

While one can argue in some cases that the schema has to be defined differently, I would say due to the large number of reports and even the example in the documentation failing, there is a fundamental problem in the type definition somewhere.

Fortunately there is a simple workaround:

const schema = schemaFromObject  as JSONSchemaType<MyData>;

Of course, this does not check the schema at all.

[ldrick]

You could use as const like this, to keep Typechecks in place:

interface MyData {
    bar?: string;
    foo: number;
}

const schemaFromObject = {
    additionalProperties: false,
    properties: {
        bar: { nullable: true, type: "string" },
        foo: { type: "integer" },
    },
    required: ["foo"],
    type: "object",
} as const; // <-- here
const schema: JSONSchemaType<MyData> = schemaFromObject;

[jpilgrim]

@ldrick Thank you! Of course, const assertions! Alas that's not working in my real example, which I would consider a typical, if not even THE typical use case:

import { type MyData } from "./my.schema"; // Root of my model
import schemaJson from "./my.schema.json"; // Real schema, also used by other tools (e.g., VS Code editor)
...
const schema: JSONSchemaType<MyData> = schemaJson as const; // not working:
  // "A 'const' assertions can only be applied to references to enum members, or string, number, boolean, array, or object literals."

The npm ts-json-as-const may be used as a workaround, though.

[ldrick]

@jpilgrim This is exactly what I would also love to see, too. Requires Typescript to allow const import - having additional lib to workaround is not suitable for my team microsoft/TypeScript#32063 or have the Types here working without const - you're right.

[jpilgrim]

@ldrick Just as a follow up: Instead of using a library to prepare the json file, a single script in the package.json file would do the trick as well (not tested on windows, so instead of a (*nix) bash script you may want to use a javascript script):

"scripts": {
   // ...
   "genjsonconst": "JSON=src/folder/my.schema.json; echo \"/* Generated, do not modify */\nexport default \" >$JSON.const.ts && cat $JSON >> $JSON.const.ts && echo \" as const;\" >> $JSON.const.ts",
   // ...
}

And you have to change the import:

- import schemaJson from "./my.schema.json";
+ import schemaJson from "./my.schema.json.const";

While this solves the const assertions problem, it does not solve all the other type related problems I mentioned above.