feat(linting): introduce jsonschema cli for linting and autofixing linting issues in schemas

[Karan-Palan]

Fixes #623

Introduced linting schemas and auto-fixing linting issues in the schemas by integrating the @sourcemeta/jsonschema cli

Changes made:

1. New commands added:

$ node bin/typescript-json-schema --help
Usage: typescript-json-schema <path-to-typescript-files-or-tsconfig> <type>

Options:
      --help                    Show help                         [boolean]
      {Other commands}
      --lint                    Lint generated schemas for JSON Schema best
                                practices and report issues
                                                 [boolean] [default: false]
      --fix                     Automatically fix linting issues in
                                generated schemas[boolean] [default: false]
      --lintStrict              Enable strict linting rules (use with --fix
                                to apply strict fixes)
                                                 [boolean] [default: false]

2. Lint Generated Schemas

$ node bin/typescript-json-schema test/programs/enums-string/main.ts MyObject --lint
JSON Schema linting issues found:
../../../../../../../tmp/jsonschema-lint-IZFqAX/schema.json:5:21:
  Setting `type` alongside `enum` is considered an anti-pattern, as the enumeration choices already imply their respective types (enum_with_type)
    at schema location "/definitions/Enum/enum"

Run with --fix to automatically fix these issues.
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "Enum": {
            "enum": [
                "x",
                "y",
                "123"
            ],
            "type": "string"
        }
    },
    "properties": {
        "foo": {
            "$ref": "#/definitions/Enum"
        }
    },
    "type": "object"
}

3. Autofix linting issues

$ node bin/typescript-json-schema test/programs/enums-string/main.ts MyObject --fix
JSON Schema auto-fix completed successfully.
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "Enum": {
      "enum": [ "x", "y", "123" ]
    }
  },
  "properties": {
    "foo": {
      "$ref": "#/definitions/Enum"
    }
  },
  "type": "object"
}

4. Enable strict/opinionated rules and autofix linting rules

$ node bin/typescript-json-schema test/programs/interface-single/main.ts MyObject --fix --lintStrict
JSON Schema auto-fix completed successfully.
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "propA": {
            "type": "number"
        },
        "propB": {
            "type": "number"
        }
    },
    "type": "object"
}

Checklist

• Tests pass
• No errors when linting
• Code Formatted

Note:

For context, I, along with Juan (JSON Schema TSC member) defined linting rules for JSON Schema as a Part of a GSoC (Google Summer of code) project here - https://github.com/Karan-Palan/JSON-Schema-Linting, and implementing their auto-fixes here - https://github.com/sourcemeta/jsonschema/blob/main/docs/lint.markdown. This is what we have accomplished so far - https://github.com/Karan-Palan/GSoC-2025/blob/main/Final-report.md. We have recently added many rules prefixing unknown keywords with x- which will be introduced in the newer JSON Schema drafts. We tested the linter on real world schemas and it was adopted by various projects like Vaccum, Manfred and many others. Many projects like ModelContextProtocol use this package for schema generation. One of their maintainers suggested to have the cli integrated in this package itself.

Please:

• Make your pull request atomic, fixing one issue at a time unless there are many relevant issues that cannot be decoupled.
• Provide a test case & update the documentation in the Readme.md

[domoritz]

Thanks for the pull request. I'm inclined not to merge this as one can easily call your cli afterwards. I don't yet see the benefit of integrating linting into this tool. By separating the tools, people can lint with the version they prefer.

I do like the idea of lining all generates examples in the tests, though. Can you change the pull request to only do that?

[Karan-Palan]

@domoritz

Apologies for the delay. I have updated the PR with fixed generated schemas. As of now, I have committed all the schemas that could be auto-fixed:

Screencast.from.2025-10-13.10-01-25.mp4

We are working on adding re-referencing functionality to the linter which would help autofix these rules. Once we have those features added, I will create a PR fixing other schemas