[📝 Docs]: Create a Migration page for the Specification docs

[kwennB]

What Docs changes are you proposing?

Create a single Migration page dedicated to upgrading and history for the drafts. It is hard for implementers of the migrate between drafts and would be better helpful if it had;

• It is challenging to identify which keywords have changed between dialects.
• Some keywords have retained their names but evolved across Schema versions. However, documentation must explain when these keywords were introduced or why they changed.
• Some keywords have changed their behavior while maintaining their syntax across schemas, causing confusion among users and highlighting the need for clear communication.
• Implementers would benefit from more guidance on upgrading implementations with changing keywords.

To facilitate smoother migration between drafts, this issue aims to add the following changes:

• Creating a detailed changelog of keyword modifications between versions
• Providing historical timelines for keyword introductions and changes
• Highlighting behavioral changes, especially when syntax remains unchanged
• Developing a robust set of migration examples and best practices

This is also in the efforts to #791.

Thank you @jviotti, for your help listing these issues.

Migration Pages Outline.

Overview page outline.

Introduction

Keywords Overview (In a table)

All Keywords	Specification	Date/draft introduction	Removed	Changed
-----	-------	------	------	-----

Pages outline

Page 1

Title: Migrating from Draft 2 to Draft 3

Introduction

Keyword changelog (In a table)

Keyword (Draft 2)	Keyword (Draft 3)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 2 - 3)

Page 2

Title: Migrating from Draft 3 to Draft 4

Introduction

Keyword changelog (In a table)

Keyword (Draft 3)	Keyword (Draft 4)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 3 - 4)

Page 3

Title: Migrating from Draft 4 to Draft 6

Introduction

Keyword changelog (In a table)

Keyword (Draft 4)	Keyword (Draft 6)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 4 - 6)

Page 4

Title: Migrating from Draft 6 to Draft 7

Introduction

Keyword changelog (In a table)

Keyword (Draft 6)	Keyword (Draft 7)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 6 - 7)

Page 5

Title: Migrating from Draft 7 to Draft 2019-09

Introduction

Keyword changelog (In a table)

Keyword (Draft 7)	Keyword (Draft 2019-09)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 7 - 2019-09)

Page 6

Title: Migrating from Draft 2019-09 to Draft 2020-12

Introduction

Keyword changelog (In a table)

Keyword (Draft 2019-09)	Keyword (Draft 2020-12)	Specification	Behavior Details
-----	-------	------	------

Migration tutorial (specific to migration from Draft 2019-09 - 2020-12)

Code of Conduct

• I agree to follow this project's Code of Conduct

[gregsdennis]

@jviotti I'd be interested in promoting your projects here instead of rehashing all the work you've done for this site.

[jviotti]

Makes sense. Let's discuss @kwennB. Some of these things are easy to add to learnjsonschema.com (or are already there), but some I'm not sure. For example:

• Creating a detailed changelog of keyword modifications between versions
• Providing historical timelines for keyword introductions and changes

These 2 might be trivial to add to learnjsonschema.com. We have some of the data already as YAML content, so it might just be about some clever Hugo rendering.

• Highlighting behavioral changes, especially when syntax remains unchanged
• Developing a robust set of migration examples and best practices

For these ones there are migration pages on the official site that we tap into, as they are already there.