Support OpenAPI

[DavidBiesack]

99% of the JSON Schema I work with are embedded in an OpenAPI document (several documents with $ref etc.). This GitHub repo does not mention OpenAPI - can the CLI be used with JSON Schema embedded OpenAPI documents? If so, how?

[jviotti]

Hi @DavidBiesack , thanks a lot for reaching out! This is indeed a very good point I was thinking about lately.

One approach is to extend commands like lint to automatically recognise an OpenAPI specification and i.e. apply themselves to the schemas in such specification. However, this approach might not work very well with other commands like bundle or test, unless we come up with a way to say "I want to bundle/test this specific schema part of the OpenAPI specification".

What do you think? Any ideas would be more than welcome. Was there a specific command you were interested in using in the context of OpenAPI?

[DavidBiesack]

@jviotti initially, I would like to use lint (with --fix).
Some OpenAPI context sensitive linting(with fix) would be nice - i.e. add unevaluatedProperties: false to schemas, but only where "safe" to do so (i.e. not schemas that are $referenced elsewhere for composition, but OK for those used in request or response bodies in the OpenAPI, would be good targets for such context-specific linting.)
Longer term, if refactoring is added to the CLI, that would be awesome ... notably, "extract these properties into a reusable schema, replacing with an allOf", rename schemas (automatically locate references and update them, Building schema cross-reference tracking and impact analysis would be nice.) Other types of refactoring tasks that are error prone when done manually would be great.
Other refactoring, like after adding a property, propagate updated example to other schemas, would be awesome.
(Ideally, the CLI would work with YAML source as well as JSON source)

[jviotti]

Thanks a lot for the feedback and ideas. Makes sense. I'll aim to get linting support for OpenAPI + YAML some time soon.

[jviotti]

General YAML support shipped in v5.0.0 (https://github.com/sourcemeta/jsonschema/releases/tag/v5.0.0). OpenAPI interoperability would be the next step!

[jeremyfiel]

here is some inspiration from a post I made about using ajv to validate OAS schemas. It's mainly for OAS 3.0.x, which is the superset/subset of draft-04. It would work with OAS3.1.x+ but Ajv uses a different import for later drafts. I don't have any logic to detect the $schema or the OAS version in this answer.

https://stackoverflow.com/questions/77519664/use-ajv-to-validate-openapi-component-schemas/77520493#77520493

[jviotti]

@jeremyfiel Awesome! From the JSON Schema CLI, these are the two things I'm thinking of:

• As a quick fix, support a --path option to validate a specific embedded schema as part of something bigger (like an OpenAPI spec). We should also support a --default-dialect option to manually set the desired dialect (also useful for standalone schemas that don't set $schema for whatever reason)

• Long term, I want the CLI to properly understand that something is an OpenAPI spec and parse it properly, inferring the dialect, etc. So you can just pass an openapi.yaml to the lint command and get it to lint the entire thing out of the box