Added migration page overview

[kwennB]

What kind of change does this PR introduce?

Documentation

Issue Number:

• Closes #___ [📝 Docs]: Create a Migration page for the Specification docs #897
• Related to #___ [📝 Docs]: Implement the Spec page restructuring (Docs Website) #791

This is the overview page for Migration, which is part of the effort to create an easy transition between dialect upgrades.

Does this PR introduce a breaking change?

No

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	f0fd4c2

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (5c0ef1b) to head (f0fd4c2).
Report is 26 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1061   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          373       373           
  Branches        94        94           
=========================================
  Hits           373       373           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jdesrosiers]

I found a few errors in the table. But, also there are several cases that are quite complicated. Hopefully my suggestions fill in some of that history. Feel free to express any of the complicated cases however you see best. My suggestions are just suggestions. If you want to ignore some of the chaos in name of simplifying things a bit, I'm ok with that.

[jdesrosiers]

This isn't correct. There was originally only one spec that included everything. Everything that we now consider Core, Validation, and Hyper-Schema was included in that one spec. In draft-04, the one spec was split into the three parts we're familiar with today. So, the spec didn't expand in draft-04 to include validation. Validation was always there. It just split that content into a different document.

This may be too much detail, but what has gone in each document has changed over time as well. The Content vocabulary and a few Meta-Data keywords moved from Hyper-Schema to Validation (draft-07) and the Applicator vocabulary moved from Validation to Core (2019-09).

[kwennB]

Everything that we now consider Core, Validation, and Hyper-Schema was included in that one spec

What was the one spec?

If you also stated that there was originally only one specification, at what point did the Validation become necessary?

In draft-04, the one spec was split into the three parts we're familiar with today. So, the spec didn't expand in draft-04 to include validation. Validation was always there. It just split that content into a different document.

Thank you. I will phrase this better.

The Content vocabulary and a few Meta-Data keywords moved from Hyper-Schema to Validation (draft-07) and the Applicator vocabulary moved from Validation to Core (2019-09).

Are there any more data for scenarios like this?

To better represent this Spec note, what would be the most nearly accurate detail?

[jdesrosiers]

What was the one spec?

I'm not sure what you mean. Draft-01, draft-02, and draft-03 were all just one spec that included what is now Core, Validation, and Hyper-Schema. It didn't really have another name like the three do now. It was just the JSON Schema spec.

If you also stated that there was originally only one specification, at what point did the Validation become necessary?

Validation was always part of the spec. It was included from the first draft. It was always necessary.

Are there any more data for scenarios like this?

I think this kind of information is in the release notes for each draft. The older drafts don't have release notes, but those didn't have these kinds of changes.

To better represent this Spec note, what would be the most nearly accurate detail?

Honestly, I'm not sure what this spec note is trying to communicate. Is it just that there are now three specs instead of one?¹ That was just a change in the way the spec was maintained. It has little affect on what people can and can't do with JSON Schema. However, splitting off Hyper-Schema meant draft-04 was the first draft where you could implement JSON Schema without including Hyper-Schema support. Implementers could implement Core and Validation and treat Hyper-Schema as an extension that they don't support.

Footnotes

1. Actually, it was broken into four specs: Core, Validation, Hyper-Schema, and JSON Reference. But, JSON Reference wasn't maintained by us. JSON Reference was merged back into Core in draft-06. ↩

[kwennB]

Thank you for clarifying about the initial "JSON Schema Spec".

[jdesrosiers]

The ability to specify types or schemas that an instance must not match wasn't eliminated, it's just done using not now.

[kwennB]

Can you confirm that disallow had that functionality before? That way, I can add that the not keyword replaced it in functionality.

[jdesrosiers]

I can confirm that not can do everything disallow could do, just with a little different syntax.

• { "disallow": "string" } => { "not": { "type": "string" } }
• { "disallow": { "type": "number", "minimum": 0 } } => { "not": { "type": "number", "minimum": 0 } }

[jdesrosiers]

Should id be included in the table?

[kwennB]

No, it was only used as a reference example.

[jdesrosiers]

Sorry, I didn't understand your response. The infobox is describing a change to how id behaves from draft-03 to draft-04. The table above lists all keyword changes that occurred between draft-03 and draft-04. So, I don't see why id wouldn't be included.

[kwennB]

This is what I was trying to communicate with the infobox.

On Draft 3, it was defined as :
This attribute defines a URI of a schema that contains the full
representation of this schema. When a validator encounters this
attribute, it SHOULD replace the current schema with the schema
referenced by the value's URI (if known and available) and re-validate
the instance. This URI MAY be relative or absolute, and relative URIs
SHOULD be resolved against the URI of the current schema.

And on Draft 4:
The value for this keyword MUST be a string, and MUST be a valid URI. This URI MUST be normalized, and SHOULD NOT be an empty fragment (#) or the empty URI.

--
So it was not only about id.

But thank you for pointing out id; I checked and noticed I skipped adding it here because it didn't change to $id until draft 6. So I will include it here.

[jdesrosiers]

So it was not only about id.

Maybe I'm missing something, but I don't think that's true. You've quoted the definition of $ref for draft-03, not id. Maybe that's a source of confusion? Both definitions describe the behavior of id and nothing more. The draft-03 definition is pretty vague and the draft-04 definition isn't great either, but the only clear difference is that empty URIs and empty fragments are discouraged.

Actually, the spec says "SHOULD", not "MUST". So, technically those empty values aren't disallowed, it's just recommended that schema authors don't use them. I think that's a good argument for not considering this not a change and leaving it out of the migration page altogether. Implementations in both drafts should consider those values to effectively be a no-op. The only difference is that draft-04 tells schema authors not to use that particular nonsense value. I'd argue that nothing actually changed in the behavior of id from draft-03 to draft-04.

[jdesrosiers]

There were no changes to $ref in draft-04. It was moved into its own spec, but nothing changed about the way it worked.

[kwennB]

Then there's no need to keep this as Step 3.

[jdesrosiers]

These last two steps effectively just tell people to test the changes to their schemas. That's general and obvious software development practice that I don't think needs to be said explicitly.

In any case, don't suggest using AJV. It has poor spec compliance and isn't actively maintained.

[kwennB]

Could you suggest any tool?

We can also say, "validate and test your updated schemas with your preferred tool".

[jdesrosiers]

I like suggesting they use their preferred tool. We could link to the tooling page to help them find a tool if they don't have a preferred tool yet.

[kwennB]

I see you chose to remove the (legacy) keyword entries. That's a perfectly fine choice, but if you remove them, it doesn't make sense to keep referencing them in the "Changed" column. Without the (legacy) keyword entries, "Replaced by"/"Replaced" doesn't make sense.

I think it would make sense to use the draft identifier of the release where the change was introduced similar to how we are using the "Removed" column. Depending on how much information you want to put in that column, you could also include a short sentence describing the change or a link to a resource describing the change in detail.

Are you suggesting removing the entire 'Changed' column or to put dashes in places that carry 'Replace, or Replaced by'.

[jdesrosiers]

Are you suggesting removing the entire 'Changed' column or to put dashes in places that carry 'Replace, or Replaced by'.

No, not at all. The only entries I was suggesting you change are the ones that reference a (legacy) keyword such as Replaced $ref (legacy). You can't say it replaced $ref (legacy) because you removed the listing for $ref (legacy). Here's an example of what my suggestion was. It uses the draft identifier for when the keyword changed in the "Changed" column.

| All Keywords | Specification | Draft introduction | Removed | Changed                                                    |
| ------------ | ------------- | ------------------ | ------- | ---------------------------------------------------------- |
| `$ref`       | Core          | 03                 | No      | 2019-09 (???)                                              |
| `type`       | Validation    | 01                 | No      | 03 (???)                                                   |
| `format`     | Validation    | 01                 | No      | 04 (???), 06 (???), 07 (???), 2019-09 (???), 2020-12 (???) |

This communicates the draft the keyword was introduced, the draft(s) the keyword changed, and the draft the keyword was removed (if it was removed). (???) is a placeholder if you want to put a short description of what changed. If not, you can just list the draft identifiers.

[jdesrosiers]

Thanks for your hard work on this PR. The history of JSON Schema is complicated, so this is a hard one to get right.

[jdesrosiers]

$schema didn't exist in draft-02. It was introduced in draft-03.

[jdesrosiers]

I think this description needs work. In draft-02, object properties defined with properties were considered to be required by default. The optional keyword existed to make a property optional. In draft-03, it changed so that object properties defined with properties were optional by default. So, required was replaced with optional to reflect the change to the default behavior. Since properties are optional by default, we no longer needed an optional keyword, we need a required keyword.

Hopefully, you can rewrite that in a more concise way for this description.

[Ritesh2351235]

Thank you for the feedback Jason!,
I would be more descriptive and rephrase this part.