Using jsonschema version other than 2020-12 with 3.1.0

[gk12277]

Hi,
Is it possible to use jsonschema version other than 2020-12 with 3.1.0.

[MikeRalphson]

It is. You need to do one or more of the following:

• include (by use of $ref) JSON Schema resources which contain $schema keywords indicating the version used
• use the $schema keyword in your OAS schemaObjects
• use the top-level field jsonSchemaDialect to indicate a default value for $schema

Please note that using a JSON Schema dialect other than the default base OAS 3.1 one with standard JSON Schema tooling will (probably) result in the keywords discriminator, xml, externalDocs and example being ignored.

Not all tools will support every version of JSON Schema.

We plan to publish a dialect $id to use when you want to continue using Draft 5 JSON Schemas with OAS 3.0.x extensions in the near future.

[jdesrosiers]

Since $schema is new to OpenAPI 3.1, there are some things users and tooling vendors should keep in mind about how it works.

$schema is only allowed at the top of a document. Because schemas are always embedded in an OpenAPI document, that means that any time you want to declare an alternate schema dialect for a schema, you must also include an $id. The $id declares that schema to be a standalone document that is embedded in the OpenAPI document. You can think about it like an iframe in an HTML document. The important consequence of that is that any $refs in that schema will resolve against the root of the schema rather than the root of the OpenAPI document like you might be used to.

That means that you can't $ref something from /components/schemas using a local JSON Pointer. The way around this is to make sure that your /components/schemas schemas have an $id. You can then $ref that identifier instead.

If you want to use the same schema version for all of your schemas, you can just set jsonSchemaDialect. In that case, you don't need $schema or $id and you can make the same local JSON Pointer references to /components/schemas like you could before.

[handrews]

As noted, yes, but it depends on tooling support. The OpenAPI Specification does not mandate support for specific other versions. Since it seems like this answer was acceptable, I'll close this.