Openapi-specification: Allow JSON schema id and $schema in OpenAPI schema definitions

Created on 3 Apr 2018 · 6Comments · Source: OAI/OpenAPI-Specification

JSON Schema files can contain top-level fields id and $schema. When using $ref in an OpenAPI document to reference an external schema, the OpenAPI tooling rejects JSON schema files that contain one or both of these fields because 1) the spec does not allow additional fields and thus 2) the published JSON Schema document for OpenAPI does not allow additional fields.
See https://github.com/whitlockjc/swagger-lint/issues/11 for some specific examples.

I propose changing the spec and the corresponding OpenAPI 3.0 schema to allow id and $ref so that one can publish OpenAPI model definition as JSON schema documents. This will allow more tools to consume them more fully.

Note: I am not requesting OpenAPI change the allowed subset of JSON Schema features.

Source

DavidBiesack

👍5

Most helpful comment

This issue will be addressed if we can make headway on the alternate schema proposal. Whitelisting certain properties I fear will just open the door to whitelisting "just one more property" and the end result will be confusion as to what tooling supports, ignores and doesn't support.

darrelmiller on 3 Apr 2018

👍2

All 6 comments

darrelmiller on 3 Apr 2018

👍2

@DavidBiesack in the meantime you may be interested in https://github.com/wework/json-schema-to-openapi-schema to help bridge the gap (or something else similar)

handrews on 17 Apr 2018

Thanks, @handrews but I don't need to go that direction. I'm designing the schema as part of our OpenAPI. I just want to publish them as full JSON Schema that contains id & $schema (in fact, right now I define the schemas as components in the OpenAPI spec, and then extract them to JSON Schema files as part of our build/deploy toolchain. The output schema are available to both OpenAPI and to other tools such as form builders. My workaround is to generate a model.json without id and $schema ($refable from the OpenAPI docuemnt) and a sibling schema.json with id and $schema, usable by tools consuming JSON Schema. I'm emitting both from the same openapi.yaml. I'm hoping to eliminate the need for managing/deploying both files or other run-time filter shenanigans.