Added migration page overview #1061

kwennB · 2024-10-24T10:46:14Z

What kind of change does this PR introduce?

Documentation

Issue Number:

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 · 2024-10-24T10:48:51Z

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	`9bbb1c2`

codecov · 2024-10-24T10:49:53Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (5c0ef1b) to head (9bbb1c2).
Report is 210 commits behind head on main.

Additional details and impacted files

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

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pages/specification/migration/_index.md

Co-authored-by: Juan Cruz Viotti <[email protected]>

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.

pages/specification/migration/_index.md

Co-authored-by: Jason Desrosiers <[email protected]>

jdesrosiers · 2025-04-09T23:00:59Z

pages/specification/migration/_index.md

+| `maxContains`           | Validation    | 2019-09            | No      | No                                                                             |
+| `maxDecimals`           | Validation    | 01                 | Yes     | Replaced by `divisibleBy`                                                      |
+| `maxProperties`         | Validation    | 04                 | No      | No                                                                             |


I noticed maxItems and minItems are missing entirely in this PR. They've always existed since draft-01 and have never changed.

jviotti · 2025-07-23T14:35:27Z

pages/draft-06/migration-notes.md

+
+| Keyword (Draft-04)                               | Keyword (Draft-06)                              | Specification | Keyword Type       | Behavior Details                                                                            |
+| ------------------------------------------------ | ----------------------------------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `id`                                             | `$id`                                           | Core          | Identifier         | Replaces `id` with `$id` to align with JSON-LD and emphasize its identifier role.           |


I don't think the JSON-LD reference here is valid. We don't care about JSON-LD at all and that was not the reason for the $ prefix. This was before me (so might be worth checking with other TSC members), but I believe it was done to more clearly group fundamental keywords together (like $schema)

I can confirm that this change had nothing to do with JSON-LD. That doesn't even make sense because JSON-LD uses @id, not $id.

This was done to make it consistent with the naming of the other core keywords $schema and $ref. Unfortunately, there was no good reason for this change. It was purely cosmetic.

jviotti · 2025-07-23T14:36:42Z

pages/draft-06/migration-notes.md

+| ------------------------------------------------ | ----------------------------------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `id`                                             | `$id`                                           | Core          | Identifier         | Replaces `id` with `$id` to align with JSON-LD and emphasize its identifier role.           |
+| `exclusiveMinimum`, `exclusiveMaximum` (boolean) | `exclusiveMinimum`, `exclusiveMaximum` (number) | Validation    | Numeric Boundaries | Previously booleans tied to `minimum`/`maximum`; now standalone numeric values.             |
+| `definitions`                                    | `definitions`                                   | Core          | Schema Reuse       | Still available but less emphasized in later drafts in favor of `$defs` (introduced later). |


I'm not sure about this one. $defs was introduced in 2019-09. Not sure we want to mention it at all here

I'm sure. This 100% doesn't belong here.

jviotti · 2025-07-23T14:37:55Z

pages/draft/2019-09/migration-notes.md

+| *not present*            | `$vocabulary`            | Core          | Identifier       | Declares which vocabularies a schema uses. Enables modular extensibility.            |
+| *not present*            | `$recursiveRef`          | Core          | Identifier       | Replaces `$ref` in recursive contexts.                                               |
+| *not present*            | `$recursiveAnchor`       | Core          | Identifier       | Used in base schemas to define recursive entry points.                               |
+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |


I don't think the spec mentions definitions at all. We should suggest $defs. Also $defs was introduced in 2019-09 and not 2020-12 as this page says

Saying it's still supported isn't technically correct. It will accidentally work in most cases, but we should definitely not be telling people it's supported. Just tell people the change the name to $defs.

jviotti · 2025-07-23T14:38:09Z

pages/draft/2019-09/migration-notes.md

+| *not present*            | `$recursiveRef`          | Core          | Identifier       | Replaces `$ref` in recursive contexts.                                               |
+| *not present*            | `$recursiveAnchor`       | Core          | Identifier       | Used in base schemas to define recursive entry points.                               |
+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |
+| `id`                     | `$id`                    | Core          | Identifier       | Already introduced in Draft 6, still used in Draft 2019-09.                          |


I don't think this is correct. Starting on Draft 6, only $id is supported

It's wrong that the name changed, but there was a change to $id in 2019-09 that should be described in this entry. The change was splitting out schema identification and anchor identification.

And id existed before draft 6.

jviotti · 2025-07-23T14:38:52Z

pages/draft/2019-09/migration-notes.md

+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |
+| `id`                     | `$id`                    | Core          | Identifier       | Already introduced in Draft 6, still used in Draft 2019-09.                          |
+| `examples`               | `examples`               | Annotation    | Informational    | Remains unchanged.                                                                   |
+| `readOnly` / `writeOnly` | `readOnly` / `writeOnly` | Annotation    | Informational    | Remains unchanged.                                                                   |


Here we mention two keywords in one row, whereas I think before we always broke things in multiple rows (like for if/then/else). Let's be consistent across pages?

Better yet, remove it and examples because this is a change log and nothing about those three keywords has changed.

jviotti · 2025-07-23T14:40:53Z

pages/draft/2019-09/migration-notes.md

+
+
+
+#### Step 3: Use `$recursiveAnchor` and `$recursiveRef` for recursive structures


I'm not sure the example here really exemplifies dynamic referencing. It is not just about recursive structures but about generic/templated schemas. That said, it's a bit hard to exemplify that well here. I remember Greg wrote a blog post about this. Maybe worth just linking to that?

jviotti · 2025-07-23T14:41:14Z

pages/draft/2019-09/migration-notes.md

+
+#### Step 4: Continue using supported keywords like `readOnly`, `writeOnly`, `examples`
+
+These keywords remain valid and unchanged:


With the exception that they now emit annotations, which was not the case before

jdesrosiers

Here's a partial review. It covers the overview and the 2020-12 migration, plus some responses to Juan's comments. I'll review the rest later.

In addition to the inline comments, please note that the following keywords are missing from the main overview: minimum, maximum, minLength, and maxLength.

pages/specification/migration/_index.md

jdesrosiers · 2025-07-25T20:54:55Z

pages/draft-06/migration-notes.md

+
+| Keyword (Draft-04)                               | Keyword (Draft-06)                              | Specification | Keyword Type       | Behavior Details                                                                            |
+| ------------------------------------------------ | ----------------------------------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `id`                                             | `$id`                                           | Core          | Identifier         | Replaces `id` with `$id` to align with JSON-LD and emphasize its identifier role.           |


I can confirm that this change had nothing to do with JSON-LD. That doesn't even make sense because JSON-LD uses @id, not $id.

This was done to make it consistent with the naming of the other core keywords $schema and $ref. Unfortunately, there was no good reason for this change. It was purely cosmetic.

jdesrosiers · 2025-07-25T20:58:56Z

pages/draft-06/migration-notes.md

+| ------------------------------------------------ | ----------------------------------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `id`                                             | `$id`                                           | Core          | Identifier         | Replaces `id` with `$id` to align with JSON-LD and emphasize its identifier role.           |
+| `exclusiveMinimum`, `exclusiveMaximum` (boolean) | `exclusiveMinimum`, `exclusiveMaximum` (number) | Validation    | Numeric Boundaries | Previously booleans tied to `minimum`/`maximum`; now standalone numeric values.             |
+| `definitions`                                    | `definitions`                                   | Core          | Schema Reuse       | Still available but less emphasized in later drafts in favor of `$defs` (introduced later). |


I'm sure. This 100% doesn't belong here.

jdesrosiers · 2025-07-25T21:02:41Z

pages/draft/2019-09/migration-notes.md

+| *not present*            | `$vocabulary`            | Core          | Identifier       | Declares which vocabularies a schema uses. Enables modular extensibility.            |
+| *not present*            | `$recursiveRef`          | Core          | Identifier       | Replaces `$ref` in recursive contexts.                                               |
+| *not present*            | `$recursiveAnchor`       | Core          | Identifier       | Used in base schemas to define recursive entry points.                               |
+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |


Saying it's still supported isn't technically correct. It will accidentally work in most cases, but we should definitely not be telling people it's supported. Just tell people the change the name to $defs.

jdesrosiers · 2025-07-25T21:06:34Z

pages/draft/2019-09/migration-notes.md

+| *not present*            | `$recursiveRef`          | Core          | Identifier       | Replaces `$ref` in recursive contexts.                                               |
+| *not present*            | `$recursiveAnchor`       | Core          | Identifier       | Used in base schemas to define recursive entry points.                               |
+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |
+| `id`                     | `$id`                    | Core          | Identifier       | Already introduced in Draft 6, still used in Draft 2019-09.                          |


It's wrong that the name changed, but there was a change to $id in 2019-09 that should be described in this entry. The change was splitting out schema identification and anchor identification.

jdesrosiers · 2025-07-25T21:08:15Z

pages/draft/2019-09/migration-notes.md

+| `definitions`            | `definitions`            | Validation    | Object Container | Still supported but now superseded by `$defs` in 2020-12+.                           |
+| `id`                     | `$id`                    | Core          | Identifier       | Already introduced in Draft 6, still used in Draft 2019-09.                          |
+| `examples`               | `examples`               | Annotation    | Informational    | Remains unchanged.                                                                   |
+| `readOnly` / `writeOnly` | `readOnly` / `writeOnly` | Annotation    | Informational    | Remains unchanged.                                                                   |


Better yet, remove it and examples because this is a change log and nothing about those three keywords has changed.

jdesrosiers

I don't think the migration notes for each release are working out. They still need a lot of work to fix errors and include enough detail to be useful. They're nowhere near ready to replace the release notes.

I suggest narrowing the scope of this PR. Let's just do the overview for now with links to the existing release notes. Then we can figure out what to do for the individual migration guides separately.

Co-authored-by: Jason Desrosiers <[email protected]>

kwennB · 2025-09-14T18:44:12Z

I don't think the migration notes for each release are working out. They still need a lot of work to fix errors and include enough detail to be useful. They're nowhere near ready to replace the release notes.

I suggest narrowing the scope of this PR. Let's just do the overview for now with links to the existing release notes. Then we can figure out what to do for the individual migration guides separately.

Hello @jdesrosiers do you think the current overview is not accurate as well?

I do agree that the migration for specific pages can be better on review now. But if we want to de-scope this to the overview only, are we not there?

jdesrosiers · 2025-09-15T03:00:48Z

I think the overview is mostly fine except you still haven't addressed #1061 (review) ...

please note that the following keywords are missing from the main overview: minimum, maximum, minLength, and maxLength.

Added migration page overview

859a6f1

kwennB added 📝 Documentation Indicates improvements or additions to documentation. GSoD Google Season of Docs labels Oct 24, 2024

kwennB requested review from benjagm and valeriahhdez October 24, 2024 10:46

kwennB self-assigned this Oct 24, 2024

kwennB requested a review from a team as a code owner October 24, 2024 10:46

github-actions bot deployed to Preview October 24, 2024 10:48 View deployment

kwennB marked this pull request as draft October 24, 2024 10:50

jviotti suggested changes Oct 24, 2024

View reviewed changes

kwennB and others added 2 commits October 25, 2024 11:56

Update pages/specification/migration/_index.md

93bcaba

Co-authored-by: Juan Cruz Viotti <[email protected]>

Update pages/specification/migration/_index.md

d4c8b24

Co-authored-by: Juan Cruz Viotti <[email protected]>

github-actions bot deployed to Preview October 25, 2024 10:59 View deployment

Updated migration overview

8eb9721

github-actions bot deployed to Preview October 28, 2024 20:28 View deployment

jdesrosiers requested changes Oct 29, 2024

View reviewed changes

Update pages/specification/migration/_index.md

75ee2a1

Co-authored-by: Jason Desrosiers <[email protected]>

github-actions bot deployed to Preview October 29, 2024 08:05 View deployment

kwennB and others added 2 commits October 29, 2024 09:05

Update pages/specification/migration/_index.md

a967f66

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

b22b2ff

Co-authored-by: Jason Desrosiers <[email protected]>

github-actions bot deployed to Preview October 29, 2024 08:08 View deployment

kwennB added this to the Docs Release 3 milestone Oct 29, 2024

kwennB and others added 5 commits October 29, 2024 09:41

Update pages/specification/migration/_index.md

c5d352e

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

136ee2e

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

fa6391b

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

83536f1

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

dd364ba

Co-authored-by: Jason Desrosiers <[email protected]>

github-actions bot deployed to Preview October 29, 2024 08:46 View deployment

Updated migration guides based on feedback

8800dc0

jdesrosiers reviewed Apr 9, 2025

View reviewed changes

Update index.page.tsx

9bbb1c2

github-actions bot deployed to Preview May 11, 2025 19:23 View deployment

Utkarsh-123github moved this to Unclear in PR - Triage Group Jun 2, 2025

Utkarsh-123github added this to PR - Triage Group Jun 2, 2025

kwennB mentioned this pull request Jun 16, 2025

updates to Hyperschema page #1039

Draft

benjagm added the Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically. label Jun 20, 2025

kwennB and others added 5 commits July 18, 2025 00:51

Added drafts

14b40d0

Merge branch 'main' into migrationPage

d2395dd

Update DocsHelp.tsx

f4e333b

resolving build

f057db4

modify draft 2019-09

0fea2a3

jviotti reviewed Jul 23, 2025

View reviewed changes

jdesrosiers requested changes Jul 25, 2025

View reviewed changes

github-project-automation bot moved this from Unclear to Changes requested in PR - Triage Group Jul 25, 2025

jdesrosiers requested changes Jul 29, 2025

View reviewed changes

kwennB and others added 5 commits September 14, 2025 19:33

Update pages/specification/migration/_index.md

94a92a8

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

2dd6e2d

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

f0a188b

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

10c3aa4

Co-authored-by: Jason Desrosiers <[email protected]>

Update pages/specification/migration/_index.md

d6e5dcf

Co-authored-by: Jason Desrosiers <[email protected]>




		#### Step 3: Use `$recursiveAnchor` and `$recursiveRef` for recursive structures


		#### Step 4: Continue using supported keywords like `readOnly`, `writeOnly`, `examples`

		These keywords remain valid and unchanged:

Uh oh!

Added migration page overview #1061

Are you sure you want to change the base?

Added migration page overview #1061

Uh oh!

Conversation

kwennB commented Oct 24, 2024 • edited by benjagm Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Uh oh!

codecov bot commented Oct 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

kwennB commented Oct 24, 2024 •

edited by benjagm

Loading

github-actions bot commented Oct 24, 2024 •

edited

Loading

codecov bot commented Oct 24, 2024 •

edited

Loading