Added migration page overview #1061
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,5 +3,85 @@ title: Migrating from older drafts | |
| section: docs | ||
| --- | ||
|
|
||
| ### Introduction | ||
|
|
||
| Just as your schemas evolve over time, the JSON Schema specification does as well. This guide provides useful information to make upgrading your schemas across versions of the specification a breeze. | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Learn how to use our migration guides and tooling ([AlterSchema](https://alterschema.sourcemeta.com/)) to bring your work with you. | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Keywords Overview | ||
|
|
||
| Here is a comprehensive overview to get you started. | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| | All Keywords | Specification | Draft introduction | Removed | Changed | | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | --------------------------- | ------------- | ------------------ | ------- | -------------------------------------------------------------------------------------------- | | ||
| | `$anchor` | Core | 2019-09 | No | Partially replaced `$id` | | ||
|
There was a problem hiding this comment. I think we should improve on the description of the change. Instead of just saying it partially replaces There was a problem hiding this comment. My assumption is that this needs to be very brief to not explode the table. I'm not sure we have the space to explain the change properly. My understanding was that this kind of thing was going to be covered in detail elsewhere. |
||
| | `$comment` | Core | 07 | No | | | ||
| | `$id` | Core | 06 | No | Replaced `id` | | ||
| | `$defs` | Core | 2019-09 | No | Replaced `definitions` | | ||
| | `$dynamicAnchor` | Core | 2020-12 | No | Replaced `$recursiveAnchor` | | ||
| | `$dynamicRef` | Core | 2020-12 | No | Replaced `$recursiveRef` | | ||
|
|
||
| | `$recursiveAnchor` | Core | 2019-09 | 2020-12 | Replaced by `$dynamicAnchor` | | ||
| | `$recursiveRef` | Core | 2019-09 | 2020-12 | Replaced by `$dynamicRef` | | ||
| | `$ref` (legacy) | Core | 03 | 2019-09 | Replaced by `$ref` | | ||
|
There was a problem hiding this comment. This entry feels weird. We are saying that |
||
| | `$ref` | Core | 2019-09 | No | Replaced `$ref` (legacy) | | ||
|
There was a problem hiding this comment. Do we need a description here? I feel we would be just repeating the description of the entry above? There was a problem hiding this comment. If describing the change in more detail is an option, we wouldn't need two entries. |
||
| | `$schema` | Core | 03 | No | No | | ||
| | `$vocabulary` | Core | 2019-09 | No | No | | ||
| | `additionalItems` | Core | 03 | 2020-12 | Replaced by `items` | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword was modified to produce annotations There was a problem hiding this comment. I don't think we need to note that things started producing annotations in 2019-09. Nothing produced annotations before 2019-09. I think it's given or at least can be generally stated once at the top of the table that annotations only became a thing in 2019-09. |
||
| | `allOf` | Core | 04 | No | No | | ||
| | `anyOf` | Core | 04 | No | No | | ||
| | `const` | Validation | 06 | No | No | | ||
| | `contains` | Core | 06 | No | No | | ||
|
There was a problem hiding this comment. The |
||
| | `contentEncoding` (legacy) | Core | 01 | 04 | Replaced by `media`.`binaryEncoding` | | ||
|
There was a problem hiding this comment. I don't think these There was a problem hiding this comment. @jviotti, see #1061 (comment). This keyword has a really complicated history. It does exist today, but there was a period when it didn't because it was moved into the |
||
| | `media` | Hyper-Schema | 04 | 07 | Replaced `contentEncoding` (legacy) and replaced by `contentEncoding` and `contentMediaType` | | ||
|
There was a problem hiding this comment. The keywords in this table are order alphabetically, so There was a problem hiding this comment. Also, I don't think we should document Hyper-Schema stuff here. The overall Hyper-Schema specification is on pause, so I suggest ignoring it for now There was a problem hiding this comment. I only suggested including |
||
| | `contentEncoding` | Validation | 07 | No | Replaced `media`.`binaryEncoding` | | ||
|
There was a problem hiding this comment. I don't think the notes make sense. |
||
| | `contentMediaType` | Validation | 07 | No | Replaced `media`.`type` | | ||
|
There was a problem hiding this comment. Same here. I don't think we should bother with Hyper-Schema, and this keyword also became an annotation in 2019-09 There was a problem hiding this comment. By understanding, the specification covers - Core and Validation. cc: @jdesrosiers There was a problem hiding this comment. @jdesrosiers I am still waiting to hear from you. Thank you There was a problem hiding this comment. Sorry for the slow response. I've been away almost all of last week and I'm catching up now.
There are three specifications: Core, Validation, and Hyper-Schema. Each spec defines one or more vocabularies.
So, Hyper-Schema is a specification that defines the hyper-schema vocabulary. I was referring to "Hyper-Schema" the spec.
I addressed that in a previous comment. I suggested including it because it was previously moved from Hyper-Schema to Validation and it didn't make sense to say it replaced the old Hyper-Schema keyword without also listing the keyword it replaced. The comment I linked suggests an alternative. |
||
| | `contentSchema` | Validation | 2019-09 | No | No | | ||
| | `definitions` | Validation | 04 | 2019-09 | Replaced by` $defs` | | ||
| | `default` | Validation | 01 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword became an annotation |
||
| | `dependencies` | Validation | 03 | 2019-09 | Replaced `requires` and replaced by `dependentSchemas` and `dependentRequired` | | ||
| | `dependentRequired` | Validation | 2019-09 | No | Partially replaced `dependencies` | | ||
| | `dependentSchemas` | Core | 2019-09 | No | Partially replaced `dependencies` | | ||
| | `deprecated` | Validation | 2019-09 | No | No | | ||
| | `disallow` | Core | 01 | 04 | Replaced by `not` | | ||
| | `divisibleBy` | Validation | 02 | No | Replaced by `multipleOf` | | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `else` | Core | 07 | No | No | | ||
| | `enum` | Validation | 01 | No | No | | ||
| | `examples` | Validation | 06 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword now produces an annotation |
||
| | `exclusiveMaximum` (legacy) | Validation | 03 | 06 | Replaced `maximumCanEqual` | | ||
| | `exclusiveMaximum` | Validation | 06 | No | Replaced `exclusiveMaximum` (legacy) | | ||
| | `exclusiveMinimum` (legacy) | Validation | 03 | 06 | Replaced `minimumCanEqual` | | ||
| | `exclusiveMinimum` | Validation | 06 | No | Replaced `exclusiveMinimum` (legacy) | | ||
| | `extends` | Core | 01 | 04 | Replaced by `allOf` | | ||
| | `format` | Validation | 01 | No | - | | ||
|
There was a problem hiding this comment. This keyword was turned into an annotation keyword in 2019-09. Also there were many changes in the set of permitted values this keyword could take over varios versions of the specifications. Not sure if we want to document those here |
||
| | `id` | Core | 03 | 06 | Replaced by `$id` | | ||
| | `if` | Core | 07 | No | No | | ||
| | `items` (legacy) | Core | 01 | 2020-12 | Replaced by `prefixItems` | | ||
|
There was a problem hiding this comment. Also, it started producing annotations in 2019-09 There was a problem hiding this comment.
There was a problem hiding this comment. Technically, the object form of
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `items` | Core | 2020-12 | No | Replaced `additionalItems` and `items` (legacy) | | ||
| | `maxContains` | Validation | 2019-09 | No | No | | ||
| | `maxProperties` | Validation | 04 | No | No | | ||
| | `maximumCanEqual` | Validation | 01 | 03 | Replaced by `exclusiveMaximum` | | ||
| | `minimumCanEqual` | Validation | 01 | 03 | Replaced by `exclusiveMinimum` | | ||
| | `minContains` | Validation | 2019-09 | No | No | | ||
| | `minProperties` | Validation | 04 | No | No | | ||
| | `multipleOf` | Validation | 04 | No | Replaced `divisibleBy` | | ||
| | `not` | Core | 04 | No | No | | ||
| | `oneOf` | Core | 04 | No | No | | ||
| | `optional` | Core | 02 | No | Replaced by `required` | | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `pattern` | Core | 01 | No | No | | ||
| | `patternProperties` | Core | 03 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword started emitting annotations |
||
| | `prefixItems` | Core | 2020-12 | No | Replaced `items` | | ||
| | `propertyNames` | Core | 06 | No | No | | ||
| | `readOnly` | Validation | 01 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword started emitting annotations |
||
| | `required` | Validation | 03 | No | No | | ||
| | `requires` | Core | 01 | 03 | Replaced by `dependencies` | | ||
| | `title` | Validation | 01 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword started emitting annotations |
||
| | `then` | Core | 07 | No | No | | ||
| | `type` (legacy) | Core | 01 | 04 | Replaced by `type` | | ||
|
There was a problem hiding this comment. This is also weird. I think it's confusing to say There was a problem hiding this comment. The There was a problem hiding this comment. @jviotti How best would you say to represent There was a problem hiding this comment. To be honest, I'm not sure. Maybe this is OK, and we can just clarify that There was a problem hiding this comment. I think this depends on how much we can put in the "Changed" column. If a brief description of the change can fit in that column, we don't need two entries. The reason I suggested two entries was because I didn't think that was an option. So, I recommend either a description of the changes in "Changes" or two entries, but not both. |
||
| | `type` | Validation | 04 | No | Replaced `type` (legacy) | | ||
| | `unevaluatedItems` | Core | 2019-09 | No | No | | ||
| | `unevaluatedProperties` | Core | 2019-09 | No | No | | ||
| | `uniqueItems` | Validation | 02 | Yes | No | | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `writeOnly` | Validation | 07 | No | No | | ||
|
There was a problem hiding this comment. In 2019-09, this keyword started emitting annotations |
||
|
|
||
| For a detailed read-through about all the changes see each Draft migration guide. | ||
kwennB marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Uh oh!
There was an error while loading. Please reload this page.