jsonschema upgrade <schema.json|.yaml>
[--to/-t draft4|draft6|draft7|2019-09|2020-12|openapi3.1|openapi3.2]
[--http/-h] [--verbose/-v] [--debug/-g] [--json/-j]
[--header/-H "<name>: <value>"]
[--resolve/-r <schemas-or-directories> ...]
[--default-dialect/-d <uri>] [--configuration/-C <path>]
[--indentation/-n <spaces>] [--color auto|always|never]Note
See Resolving External References for every way of making referenced schemas available, including how to handle a reference whose URI differs from the identifier the target schema declares.
JSON Schema dialects are not always backwards compatible. The upgrade command
rewrites a schema to conform to a newer dialect, taking every subtletly across
specifications into account, including re-writing references that point at
locations whose path has changed. By default, schemas are upgraded to the
latest JSON Schema dialect, 2020-12, and the result is printed to standard
output.
The dialects it walks through are the official JSON Schema ones up to 2020-12, and then the OpenAPI Schema Object dialects, each of which is 2020-12 plus a vocabulary of its own. Those sit past the default, so a schema lands on one of them only when it is asked for. Note this upgrades a schema onto an OpenAPI dialect, and is a separate matter from reading an OpenAPI description, which this command does not do.
The result is printed in the format the input was written in: a YAML schema
upgrades into YAML and a JSON schema into JSON. A YAML result keeps the width
each level of nesting was written with, while a JSON result is laid out with
two spaces. Use --indentation/-n to set the width in either case.
For example, consider the following Draft 3 schema:
{
"$schema": "http://json-schema.org/draft-03/schema#",
"id": "https://example.com",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1, "required": true },
"born": { "$ref": "#/definitions/year" }
},
"definitions": {
"year": { "type": "integer", "minimum": 1900, "divisibleBy": 1 }
}
}You can upgrade it to JSON Schema 2020-12 as follows:
jsonschema upgrade path/to/schema.json --to 2020-12The result will be something like this:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com",
"type": "object",
"required": [ "name" ],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"born": {
"$ref": "#/$defs/year"
}
},
"$defs": {
"year": {
"type": "integer",
"minimum": 1900,
"multipleOf": 1
}
}
}Warning
We don't support upgrading meta-schemas, nor schemas that declare a custom
meta-schema. A meta-schema describes a dialect by naming that dialect's
keywords as ordinary data. Upgrading renames the keywords, but nothing
renames the data that was talking about them, so a meta-schema requiring
definitions still requires it after its schemas moved to $defs. Upgrade
both by hand instead.
Note
The --to/-t option means "upgrade to at least this dialect". If your
schema is already at or beyond the target dialect, the command leaves
the schema unchanged. For example, asking the CLI to upgrade a 2020-12
schema to Draft 7 will do nothing, and neither will asking it to upgrade
an OpenAPI 3.2 schema to 2020-12.
Note
A meta-schema is only recognised as one if the document describes itself, or if it travels in the same document as a schema that declares it. Otherwise it is indistinguishable from an ordinary schema, and gets upgraded like one.
Note
Every resource in the document must sit on Draft 3 or newer, and not on a hyper-schema dialect, as we don't support upgrading from those yet.
jsonschema upgrade path/to/schema.jsonjsonschema upgrade path/to/schema.json --to draft7jsonschema upgrade path/to/schema.json --to openapi3.1cat path/to/schema.json | jsonschema upgrade -jsonschema upgrade path/to/schema.json \
--default-dialect http://json-schema.org/draft-04/schema#jsonschema upgrade path/to/schema.json \
--resolve path/to/imported.jsonjsonschema upgrade path/to/schema.yaml