search

sourcemeta / jsonschema

The CLI for working with JSON Schema. Covers formatting, linting, testing, bundling, and more for both local development and CI/CD pipelines
GNU Affero General Public License v3.0
68 stars 7 forks source link

Support OpenAPI #80

Open DavidBiesack opened 5 months ago

DavidBiesack commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

@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 commented 5 months ago

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