diff --git a/components/DocsHelp.tsx b/components/DocsHelp.tsx index 544189b77..8fa21d48b 100644 --- a/components/DocsHelp.tsx +++ b/components/DocsHelp.tsx @@ -3,18 +3,34 @@ import React, { FormEvent, useRef, useState } from 'react'; import extractPathWithoutFragment from '~/lib/extractPathWithoutFragment'; interface DocsHelpProps { - markdownFile?: string; + fileRenderType?: '_indexmd' | 'indexmd' | 'tsx' | '_md' | string; + showEditOption?: boolean; } - -export function DocsHelp({ markdownFile }: DocsHelpProps) { +export function DocsHelp({ + fileRenderType, + showEditOption = true, +}: DocsHelpProps) { const router = useRouter(); - const path = encodeURIComponent(router.pathname); const [isFormOpen, setIsFormOpen] = useState(false); const [feedbackStatus, setFeedbackStatus] = useState(''); const [isSubmitting, setIsSubmitting] = useState(false); const [error, setError] = useState(''); const feedbackFormRef = useRef(null); - + let gitredirect = ''; + if ( + typeof fileRenderType === 'string' && + fileRenderType.startsWith('https://') + ) { + gitredirect = fileRenderType; + } else if (fileRenderType === 'tsx') { + gitredirect = `https://github.com/json-schema-org/website/blob/main/pages${extractPathWithoutFragment(router.asPath) + '/index.page.tsx'}`; + } else if (fileRenderType === '_indexmd') { + gitredirect = `https://github.com/json-schema-org/website/blob/main/pages${extractPathWithoutFragment(router.asPath) + '/_index.md'}`; + } else if (fileRenderType === 'indexmd') { + gitredirect = `https://github.com/json-schema-org/website/blob/main/pages${extractPathWithoutFragment(router.asPath) + '/index.md'}`; + } else { + gitredirect = `https://github.com/json-schema-org/website/blob/main/pages${extractPathWithoutFragment(router.asPath) + '.md'}`; + } async function createFeedbackHandler(event: FormEvent) { event.preventDefault(); const formData = new FormData(feedbackFormRef.current!); @@ -296,28 +312,30 @@ export function DocsHelp({ markdownFile }: DocsHelpProps) { type of contribution!

-
- - - Edit this page on Github - -
+ + Edit this page on Github + + + )}
+ + {newTitle} + + {frontmatter.title} + + + + ); +} +StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-02/migration-notes.md b/pages/draft-02/migration-notes.md new file mode 100644 index 000000000..3086b975c --- /dev/null +++ b/pages/draft-02/migration-notes.md @@ -0,0 +1,4 @@ +--- +title: Draft 01 to Draft 02 +section: docs +--- \ No newline at end of file diff --git a/pages/draft-03/[slug].page.tsx b/pages/draft-03/[slug].page.tsx new file mode 100644 index 000000000..9dfd19eac --- /dev/null +++ b/pages/draft-03/[slug].page.tsx @@ -0,0 +1,39 @@ +import React from 'react'; +import Head from 'next/head'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { getLayout } from '~/components/Sidebar'; +import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; +import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; +import { Headline1 } from '~/components/Headlines'; +import { SectionContext } from '~/context'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticPaths() { + return getStaticMarkdownPaths('pages/draft-03'); +} +export async function getStaticProps(args: any) { + return getStaticMarkdownProps(args, 'pages/draft-03'); +} + +export default function StaticMarkdownPage({ + frontmatter, + content, +}: { + frontmatter: any; + content: any; +}) { + const fileRenderType = '_md'; + const newTitle = 'JSON Schema - ' + frontmatter.title; + + return ( + + + {newTitle} + + {frontmatter.title} + + + + ); +} +StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-03/migration-notes.md b/pages/draft-03/migration-notes.md new file mode 100644 index 000000000..afe552176 --- /dev/null +++ b/pages/draft-03/migration-notes.md @@ -0,0 +1,49 @@ +--- +title: Draft 02 to Draft 03 +section: docs +--- + +### Introduction + +The migration from Draft 2 to Draft 3 of JSON Schema introduced significant updates in schema definition and validation behaviors. Draft 3 refined existing keywords, added new ones, and adjusted validation rules to improve schema precision and consistency. This guide will assist you in updating your JSON Schemas to meet Draft 3 requirements, detailing keyword replacements, vocabulary changes, and modifications in validation behaviors. + +### Keyword changelog + +| Keyword(Draft 2) | Keyword(Draft 3) | Specification | Keyword type | Behavior Details | +| ----------------- | ------------------- | ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| not present | `$schema` | `Core` | Identifier | The `$schema` keyword specifies the URI of the JSON Schema that defines the schema of the current document. Validators use this URI to resolve links and determine the JSON Schema version, enabling appropriate validation features. Including the `$schema` keyword is recommended to ensure compatibility with future JSON Schema changes. | +| not present | `$ref` | `Core` | Applicator | `$ref` key references an external schema URI for validation. | +| not present | `id` | `Core` | Identifier | This keyword defines the schema's current URI (a "self" link). The URI can be relative or absolute and is resolved against the parent schema's URI. If there is no parent schema, it is resolved against the URI used to retrieve the schema. | +| `optional` | `required` | `Core` | Assertion | In **draft-02**, object properties defined within the `properties` keyword were required by default, and the `optional` keyword was used to explicitly make a property optional. In **draft-03**, this behavior changed: properties defined under `properties` are now optional by default. As a result, the `optional` keyword became redundant and was replaced by the `required` keyword to reflect the new default behavior, where properties are optional unless explicitly marked as required. | +| `minimumCanEqual` | `exclusiveMinimum` | `Core` | Assertion | Specifies that instance values must be strictly greater than the minimum when `exclusiveMinimum` is `true`. | +| `maximumCanEqual` | `exclusiveMaximum` | `Core` | Assertion | This ensures that instance values fall below the maximum when `exclusiveMaximum` is `true`. | +| `format` | `format` | `Core` | Annotation | This update refined format handling by adding and removing specific types, offering clearer guidance for expected data formats. | +| not present | `patternProperties` | `Core` | Applicator | Enforces schema validation on properties with names matching specified regex patterns. Each property matching a pattern must conform to the schema defined for that pattern in `patternProperties`. | +| `requires` | `dependencies` | `Core` | Assertion | Defines property dependencies - if an instance includes a property named in this attribute, that property must meet additional validation requirements defined by its dependency value. | +| not present | `additionalItems` | `Core` | Applicator | Defines rules for extra items in an array - can be set to false to disallow extra items beyond specified tuples, or to a schema that additional items must follow. | +| `properties` | remained `properties` | `Core` | Applicator | The `properties` takes two values, either `optional` or `required`; where `optional `, is the default value. | +| `alternate` | removed | `Core` | | - | + +### Tutorial + +#### Step 1: Review Core Changes + +Start by understanding the key differences between Draft 2 and Draft 3, especially regarding core changes in $schema, $ref, and validation keywords. + +- `$schema`: Draft 3 introduces the `$schema` keyword, it handles the schema dialect and the version of the specification being used. +- `$ref`: Draft 3 introduces the `$ref` keyword, which allows referencing external schemas for validation and schemas within the same schema document. This will enable more modular and reusable schema definitions. + +#### Step 2: Update Validation Keywords + +Draft 3 introduces new validation keywords that improve flexibility in schema definitions. Notable changes include: + +- `optional` to `required`: Draft 3 removes the `optional` keyword and introduces `required`, which specifies the required properties for an object. +- `minimumCanEqual` to `exclusiveMinimum`: For numerical validation, `exclusiveMinimum` enforces that the value must be strictly greater than the given minimum value. +- `maximumCanEqual` to `exclusiveMaximum`: Similarly, `exclusiveMaximum` ensures the value is strictly less than the maximum allowed value. +- `patternProperties`: Draft 3 introduces `patternProperties`, which allows you to define schema rules for properties whose names match a regular expression. + +#### Step 3: Refactor $ref Usage + +Draft 3 introduces `$ref`, which allows you to reference external schemas using **URIs**. This improves schema modularity and enables better reuse of schema definitions. + +Validate and test your updated schemas manually, or with your preferred [tool.](https://json-schema.org/tools) diff --git a/pages/draft-04/[slug].page.tsx b/pages/draft-04/[slug].page.tsx new file mode 100644 index 000000000..1f2c4f1ee --- /dev/null +++ b/pages/draft-04/[slug].page.tsx @@ -0,0 +1,39 @@ +import React from 'react'; +import Head from 'next/head'; +import StyledMarkdown from '~/components/StyledMarkdown'; +import { getLayout } from '~/components/Sidebar'; +import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; +import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; +import { Headline1 } from '~/components/Headlines'; +import { SectionContext } from '~/context'; +import { DocsHelp } from '~/components/DocsHelp'; + +export async function getStaticPaths() { + return getStaticMarkdownPaths('pages/draft-04'); +} +export async function getStaticProps(args: any) { + return getStaticMarkdownProps(args, 'pages/draft-04'); +} + +export default function StaticMarkdownPage({ + frontmatter, + content, +}: { + frontmatter: any; + content: any; +}) { + const fileRenderType = '_md'; + const newTitle = 'JSON Schema - ' + frontmatter.title; + + return ( + + + {newTitle} + + {frontmatter.title} + + + + ); +} +StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/draft-04/migration-notes.md b/pages/draft-04/migration-notes.md new file mode 100644 index 000000000..30f8667cd --- /dev/null +++ b/pages/draft-04/migration-notes.md @@ -0,0 +1,84 @@ +--- +title: Migrating from Draft 03 to Draft 04 +section: docs +--- + +### Introduction + +The migration from Draft 3 to Draft 4 of JSON Schema introduces changes in how schemas are defined and validated. Draft 4, published on January 31, 2013, introduced new keywords and revised the behaviours of existing ones. + +This guide will help you adapt your JSON Schemas to align with Draft 4 requirements, covering keyword changes, updates, and behavioural modifications. + +### Keyword changelog + +Below is a summary table highlighting keyword changes between Draft 3 and Draft 4. + +| Keyword (Draft 3) | Keyword (Draft 4) | Specification | Keyword type | Behavior Details | +| ----------------- | ----------------- | ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `$schema` | `$schema` | Core | Identifier | Change in the dialect (Uses the latest Draft4 dialect) | +| `type` | `type` | Validation | Assertion | This change no longer accepts the `any` type, restricting instances to the seven core primitive types only. | +| `disallow` | removed | Validation | Applicator | The `disallow` keyword specifies types or schemas that an instance must not match, although removed; this functionality has been replaced by the `not` keyword. | +| `required` | `required` | Validation | Assertion | The `required` keyword shifted from being a boolean within each property to a standalone keyword that takes an array of required property names outside of properties. | +| `divisibleBy` | `multipleOf` | Validation | Assertion | `divisibleBy` was renamed to `multipleOf` with a stricter requirement that its value must be greater than 0. | +| `extends` | removed | Validation | Applicator | The `extends` keyword was removed; allOf was added as a new keyword to achieve similar functionality. | +| `format` | `format` | Validation | Annotation | The attributes `phone`, `style`, and `color` have been removed and ip-address has been renamed to `ipv4`. | +| `dependencies` | `dependencies` | Core | Assertion | The `dependencies` member values were changed to require an array of strings or a schema, eliminating the use of single strings. | +| `id` | `id` | Core | Identifier | - | +| Not present | `allOf` | Core | Applicator | - | +| Not present | `anyOf` | Core | Applicator | - | +| Not present | `definitions` | Validation | Reserved Location | - | +| Not present | `maxProperties` | Validation | Assertion | - | +| Not present | `minProperties` | Validation | Assertion | - | +| Not present | `not` | Core | Applicator | - | +| Not present | `oneOf` | Core | Applicator | - | + +#### Helpful notes for Keyword changelog + +1. `type` + +In Draft-03, the `type` keyword could hold a simple value like "string" or "number" and an entire schema as its value. + +For example: + +```json +{ + "type": { + "type": "array", + "items": { "type": "string" } + } +} +``` + +This feature was in Draft-03 but changed in later versions of JSON Schema, where `type` is limited to simpler values like strings or arrays of strings. + +The `allOf` keyword has now replaced the previous type schema functionality. + + Starting with Draft 4, schema identifiers that use an empty URI "" or a fragment-only URI "#" are no longer allowed. + +In Draft 3, these identifiers were considered valid: + +```json +"id": "" +"id": "#" +``` + +However, this format is now prohibited from Draft 4 onwards. + + + +### Tutorial + +This tutorial walks you through key steps and considerations to help you successfully migrate your JSON schemas from Draft 3 to Draft 4. + +#### Step 1: Review Core Changes + +Start by familiarizing yourself with the updates in the [Draft 4 Core schema specification](https://json-schema.org/draft-04/draft-zyp-json-schema-04.html). Note the revised `type`, `required`, and `dependencies` keywords, which might affect your schemas if you rely on polymorphic types or cross-schema references. + +#### Step 2: Update Validation Keywords + +Draft 4 has introduced new keywords such as `oneOf`, `not`, `anyOf`, and `allOf`. Review each of these additions, and update your schemas to use these keywords if relevant. For instance: + +- If you have properties that must always be present, use `required` to define these properties explicitly. +- For schemas that contain nested dependencies, consider restructuring them using `dependencies` to improve schema maintainability. + +Validate and test your updated schemas manually, or with your preferred [tool.](https://json-schema.org/tools) diff --git a/pages/draft-05/migration-notes.md b/pages/draft-05/migration-notes.md new file mode 100644 index 000000000..bd0f4be61 --- /dev/null +++ b/pages/draft-05/migration-notes.md @@ -0,0 +1,6 @@ +--- +title: Draft 04 to Draft 05 +section: docs +--- + +4-5 diff --git a/pages/draft-06/[slug].page.tsx b/pages/draft-06/[slug].page.tsx index fc447db63..9c9a7b991 100644 --- a/pages/draft-06/[slug].page.tsx +++ b/pages/draft-06/[slug].page.tsx @@ -1,7 +1,7 @@ import React from 'react'; import Head from 'next/head'; -import { getLayout } from '~/components/Sidebar'; import StyledMarkdown from '~/components/StyledMarkdown'; +import { getLayout } from '~/components/Sidebar'; import getStaticMarkdownPaths from '~/lib/getStaticMarkdownPaths'; import getStaticMarkdownProps from '~/lib/getStaticMarkdownProps'; import { Headline1 } from '~/components/Headlines'; @@ -22,7 +22,7 @@ export default function StaticMarkdownPage({ frontmatter: any; content: any; }) { - const markdownFile = '_index'; + const fileRenderType = '_md'; const newTitle = 'JSON Schema - ' + frontmatter.title; return ( @@ -32,7 +32,7 @@ export default function StaticMarkdownPage({ {frontmatter.title} - + ); } diff --git a/pages/draft-06/migration-notes.md b/pages/draft-06/migration-notes.md new file mode 100644 index 000000000..c9a498eac --- /dev/null +++ b/pages/draft-06/migration-notes.md @@ -0,0 +1,4 @@ +--- +title: Draft 04 to Draft 06 +section: docs +--- diff --git a/pages/draft-07/[slug].page.tsx b/pages/draft-07/[slug].page.tsx index be10dfdba..f4ef2b082 100644 --- a/pages/draft-07/[slug].page.tsx +++ b/pages/draft-07/[slug].page.tsx @@ -22,7 +22,7 @@ export default function StaticMarkdownPage({ frontmatter: any; content: any; }) { - const markdownFile = '_index'; + const fileRenderType = '_md'; const newTitle = 'JSON Schema - ' + frontmatter.title; return ( @@ -32,7 +32,7 @@ export default function StaticMarkdownPage({ {frontmatter.title} - + ); } diff --git a/pages/draft-07/migration-notes.md b/pages/draft-07/migration-notes.md new file mode 100644 index 000000000..97dec98eb --- /dev/null +++ b/pages/draft-07/migration-notes.md @@ -0,0 +1,135 @@ +--- +title: Draft 06 to Draft 07 +section: docs +--- + + +### Introduction + +JSON Schema Draft 7 builds upon Draft 6 by introducing new validation and annotation keywords, refining conditional validation capabilities, and clarifying core behaviors. These changes improve schema expressiveness and usability while maintaining backward compatibility with Draft 6. + +This guide will help you understand the new keywords and behaviors introduced in Draft 7 for better transition. + +### Keyword changelog + +| Keyword(Draft 6) | Keyword(Draft 7) | Specification | Keyword type | Behavior Details | +| ---------------- | ---------------- | ----------------| --------------- | --------------- | +|`$schema` |`$schema` | Core | Identifier | Change in the dialect (Uses the latest Draft7 dialect). | +|not present | `$comment`| Core | Reserved location | The `$comment` keyword was introduced for internal comments, requiring a string that must not be shown to end users and has no impact on validation. Worked as annotation in Draft 6 but now works as a keyword in Draft 7. | +| not present | `if`| `validation` | Applicator | The `if` keyword was introduced, requiring a valid JSON Schema; instances must validate against `then` if `if` succeeds, and against `else` if `if` fails, with `if` validation always succeeding on its own. | +| not present | `then`| `validation`| Applicator | The `then` keyword was introduced, requiring a valid JSON Schema; it succeeds if the instance validates against both `if` and `then`, and always succeeds if `if` is absent or fails. | +| not present | `else` | `validation` | Applicator | The `else` keyword was introduced, requiring a valid JSON Schema; it succeeds if the instance fails `if` and validates against `else`, and always succeeds if `if` is absent or succeeds | +| not present | `contentEncoding` | `validation` | Annotation | The `contentEncoding` keyword was introduced to specify that a string instance should be treated as binary data, requiring a valid string value for encoding. | +| not present | `contentMediaType`| `validation` | Annotation | The `contentMediaType` keyword specifies the media type of instances defined by the schema and must be a string; it is ignored if the instance is not a string. | +| not present | `readOnly` | `validation`| Annotation | The `readOnly` keyword, set to true, indicates that the instance value is managed by the owning authority, and modifications by applications will be ignored. | +| not present | `writeOnly`| `validation` | Annotation | The `writeOnly` keyword, set to true, means the value is not retrieved from the authority but can be sent for updates or creation. | + +### Tutorial + +#### Migration Steps + +##### 1. Update the `$schema` Declaration + +Replace your Draft 6 schema declaration with the Draft 7 identifier: + + **Before (Draft 6):** + +``` +{ + "$schema": "http://json-schema.org/draft-06/schema#" +} +``` + +**After (Draft 7):** + +``` +{ + "$schema": "http://json-schema.org/draft-07/schema#" +} +``` + +##### 2. Incorporate the `$comment` Keyword (Optional) + +If you want to include inline comments for documentation purposes, use the `$comment` keyword: + +``` +{ + "$comment": "This field is deprecated and will be removed in the next version." +} +``` + +##### 3. Implement Conditional Validation with `if`, `then`, and `else` + +Draft 7 introduces conditional validation, which allows schemas to specify different validation rules depending on whether a condition is met. + + **Example:** + +``` +{ + "type": "object", + "properties": { + "age": { "type": "integer" } + }, + "if": { + "properties": { "age": { "minimum": 18 } }, + "required": ["age"] + }, + "then": { "properties": { "canVote": { "const": true } } }, + "else": { "properties": { "canVote": { "const": false } } } +} +``` + +*Explanation:* If `age` is 18 or higher, `canVote` must be `true`; otherwise, it must be `false`. + +##### 4. Utilize `contentEncoding` and `contentMediaType` for String Data Interpretation + +These keywords help define how string instances should be treated: + + **Example:** + +``` +{ + "type": "string", + "contentEncoding": "base64", + "contentMediaType": "image/png" +} +``` + +*Explanation:* The string must be base64-encoded and represent a PNG image. + +##### 5. Define `readOnly` and `writeOnly` Fields + +These annotations help define whether a field should be modifiable or retrievable. + + **Example:** + +``` +{ + "type": "object", + "properties": { + "username": { + "type": "string", + "readOnly": true + }, + "password": { + "type": "string", + "writeOnly": true + } + } +} +``` + +*Explanation:* `username` is read-only (cannot be changed by clients), while `password` is write-only (cannot be retrieved once set). + +### Conclusion + +Migrating from JSON Schema Draft 6 to Draft 7 is mostly seamless. The key updates include: + +- The introduction of `$comment` for internal documentation. +- New conditional validation keywords (`if`, `then`, `else`). +- Enhanced support for string-based data with `contentEncoding` and `contentMediaType`. +- Read/write permissions via `readOnly` and `writeOnly`. + +These adjustments helps you take full advantage of the improvements introduced in Draft 7 while ensuring compatibility with existing schemas. + + diff --git a/pages/draft/2019-09/migration-notes.md b/pages/draft/2019-09/migration-notes.md new file mode 100644 index 000000000..2abf23558 --- /dev/null +++ b/pages/draft/2019-09/migration-notes.md @@ -0,0 +1,6 @@ +--- +title: Draft 07 to Draft 2019-09 +section: docs +--- + +Testing to see if this page is visible. diff --git a/pages/draft/2020-12/migration-notes.md b/pages/draft/2020-12/migration-notes.md new file mode 100644 index 000000000..7e67c33b4 --- /dev/null +++ b/pages/draft/2020-12/migration-notes.md @@ -0,0 +1,212 @@ +--- +title: Draft 2019-09 to Draft 2020-12 +section: docs +--- + +### Introduction + +JSON Schema Draft 2020-12 introduces key improvements over Draft 2019-09, focusing on improved modularity and cross-referencing capabilities. This means improvements for schema resuse, being able to define features a schema supports, etc. This guide covers all major changes and how to migrate from Draft 2019-09 to Draft 2020-12. + +### Keyword changelog + +| Keyword (Draft 2019-09) | Keyword (Draft 2020-12) | Specification | Keyword Type | Behavior Details | +| --- | --- | --- | --- | --- | +|` $anchor` | remained `$anchor` | Core | | In 2019-09, $anchor could use a colon and not start with an underscore, but in 2020-12, the upgrade in syntax rule can't use a colon. | +| `$schema` | remained` $schema` | Core | | The behavior was updated to use dialect 2020-12 | +| `$recursiveAnchor` | `$dynamicAnchor` | Core | Identifier | Similar to `$anchor`, but supports `$dynamicRef` for flexible schema resolution. | +|` $recursiveRef` | `$dynamicRef` | Core | Applicator | Works with `$dynamicAnchor` to allow referencing dynamically resolved schemas at runtime. | +| `$vocabulary` | `$vocabulary` | Core | | Specifies which vocabularies a schema uses in 2019-09, but the update now uses format-annotation aiding compatibility and extensibility. | +| `items` (used for both lists and tuples) | `prefixItems` | Core | Applicator | Separates tuple validation (`prefixItems`) from list validation (`items`). Now, `items` applies only to additional elements beyond `prefixItems`. | + +### Tutorial + + +#### Migration Steps + +##### 1. Updating `$schema` Declaration + +Reference the correct Draft 2020-12 meta-schema to ensure compatibility: + +**Before (Draft 2019-09):** + +``` +{ + "$schema": "https://json-schema.org/draft/2019-09/schema" +} +``` + +**After (Draft 2020-12):** + +``` +{ + "$schema": "https://json-schema.org/draft/2020-12/schema" +} +``` + +##### 2. Using `$dynamicAnchor` and `$dynamicRef` + +Switch to `$dynamicAnchor` when defining recursive schemas: + +**Before (Draft 2019-09):** + +``` +{ + "$recursiveAnchor": true +} +``` + +**After (Draft 2020-12):** + +``` +{ + "$dynamicAnchor": "mySchema" +} +``` + +Use `$dynamicRef` instead of `$recursiveRef` for dynamic references: + +**Example:** + +``` +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$dynamicAnchor": "baseSchema" +} +``` + +To reference dynamically: + +``` +{ + "$dynamicRef": "#baseSchema" +} +``` + +##### 3. Declaring Supported Vocabularies with `$vocabulary` + +For your custom dialects, you'll need to update a couple of vocabulary declarations. + +If you're using `format` as annotations (the default), you'll make the following change. + +**Before (Draft 2019-09):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2019-09/vocab/format": false + } +} +``` + +**After (Draft 2020-12):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/format-annotation": true + } +} +``` + +If you're using `format` as annotations, do this instead, + +**Before (Draft 2019-09):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2019-09/vocab/format": true + } +} +``` + +**After (Draft 2020-12):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/format-assertion": true + } +} +``` + +Next, update your Applicator vocabulary declaration to include Unevaluated. + +**Before (Draft 2019-09):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2019-09/vocab/applicator": true + } +} +``` + +**After (Draft 2020-12):** + +```json +{ + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/applicator": true, + "https://json-schema.org/draft/2020-12/vocab/unevaluated": true + } +} +``` + +##### 4. Replacing `items` with `prefixItems` for Tuple Validation + +For fixed-length arrays (tuples), replace `items` with `prefixItems`: + +**Before (Draft 2019-09):** + +``` +{ + "type": "array", + "items": [ + { "type": "string" }, + { "type": "number" } + ] +} +``` + +**After (Draft 2020-12):** + +``` +{ + "type": "array", + "prefixItems": [ + { "type": "string" }, + { "type": "number" } + ] +} +``` + +To validate additional items beyond `prefixItems`, `items` can still be used: + +**Before (Draft 2019-09):** + +```json +{ + "type": "array", + "items": [ + { "type": "string" }, + { "type": "number" } + ], + "additionalItems": { "type": "boolean" } +} +``` + +**After (Draft 2020-12):** + +```json +{ + "type": "array", + "prefixItems": [ + { "type": "string" }, + { "type": "number" } + ], + "items": { "type": "boolean" } +} +``` + +These improvements ensure compliance with the latest JSON Schema standards while improving maintainability and extensibility of your schemas. \ No newline at end of file diff --git a/pages/specification/migration/_index.md b/pages/specification/migration/_index.md index 734bd0b33..c27e56180 100644 --- a/pages/specification/migration/_index.md +++ b/pages/specification/migration/_index.md @@ -3,5 +3,85 @@ title: Migrating from older drafts section: docs --- -The release notes discuss the changes impacting users and implementers: +### Introduction +As your schemas evolve over time, so does JSON Schema specification. This guide provides useful information help you smoothly upgrade your schemas across different specification versions + +Learn how to use our migration guides and tooling ([AlterSchema](https://alterschema.sourcemeta.com/)) to bring your work with you. + +Alterschema is a tool designed to facilitate the automatic migration and transformation of JSON schemas as specifications evolve. It helps simplify schema maintenance, supports backward compatibility, and streamlines schema adjustment across versions. [Read more about using AlterSchema](https://github.com/sourcemeta/alterschema?tab=readme-ov-file). + +### Keywords Overview + +This table provides an overview of keyword changes and removals in JSON Schema specifications from Draft 01 to the latest draft. + +| All Keywords | Specification | Draft introduction | Removed | Changed | +| ----------------------- | ------------- | ------------------ | ------- | ------------------------------------------------------------------------------ | +| `$anchor` | Core | 2019-09 | No | Partially replaced `$id` | +| `$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` | Core | 03 | No | Modified in 2019-09 | +| `$schema` | Core | 03 | No | No | +| `$vocabulary` | Core | 2019-09 | No | No | +| `additionalItems` | Core | 03 | 2020-12 | Replaced by `items` | +| `additionalProperties` | Core | 01 | No | No | +| `allOf` | Core | 04 | No | No | +| `anyOf` | Core | 04 | No | No | +| `const` | Validation | 06 | No | No | +| `contains` | Core | 06 | No | No | +| `contentEncoding` | Validation | 07 | No | Replaced `media`.`binaryEncoding` | +| `contentMediaType` | Validation | 07 | No | Replaced `media`.`type` | +| `contentSchema` | Validation | 2019-09 | No | No | +| `definitions` | Validation | 04 | 2019-09 | Replaced by` $defs` | +| `default` | Validation | 01 | No | No | +| `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 | +| `description` | Validation | 01 | No | No | +| `disallow` | Core | 01 | 04 | Replaced by `not` | +| `divisibleBy` | Validation | 02 | Yes | Replaced by `multipleOf` | +| `else` | Core | 07 | No | No | +| `enum` | Validation | 01 | No | No | +| `examples` | Validation | 06 | No | No | +| `exclusiveMaximum` | Validation | 03 | No | Modified in 04 | +| `exclusiveMinimum` | Validation | 03 | No | Modified in 04 | +| `extends` | Core | 01 | 04 | Replaced by `allOf` | +| `format` | Validation | 01 | No | Modified in 04, 06, 07, 2019-09, and 2020-12 | +| `id` | Core | 03 | 06 | Replaced by `$id` | +| `if` | Core | 07 | No | No | +| `items` | Core | 01 | No | Changed in 2020-12 | +| `maxContains` | Validation | 2019-09 | No | No | +| `maxDecimals` | Validation | 01 | Yes | Replaced by `divisibleBy` | +| `maxProperties` | Validation | 04 | No | No | +| `maximumCanEqual` | Validation | 01 | 03 | Replaced by `exclusiveMaximum` | +| `media` | Hyper-Schema | 04 | 07 | Replaced by `contentEncoding` and `contentMediaType` | +| `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 | 03 | Replaced by `required` | +| `pattern` | Core | 01 | No | No | +| `patternProperties` | Core | 03 | No | No | +| `prefixItems` | Core | 2020-12 | No | Replaced `items` | +| `properties` | Core | 01 | No | No | +| `propertyNames` | Core | 06 | No | No | +| `readOnly` | Validation | 01 | No | No | +| `required` | Validation | 03 | No | No | +| `requires` | Core | 01 | 03 | Replaced by `dependencies` | +| `title` | Validation | 01 | No | No | +| `then` | Core | 07 | No | No | +| `type` | Validation | 01 | No | Modified in 04 | +| `unevaluatedItems` | Core | 2019-09 | No | No | +| `unevaluatedProperties` | Core | 2019-09 | No | No | +| `uniqueItems` | Validation | 02 | No | No | +| `writeOnly` | Validation | 07 | No | No | + +For a detailed read-through about all the changes see each Draft migration guide. diff --git a/pages/specification/migration/index.page.tsx b/pages/specification/migration/index.page.tsx index fbba9bd33..6c4908285 100644 --- a/pages/specification/migration/index.page.tsx +++ b/pages/specification/migration/index.page.tsx @@ -48,28 +48,42 @@ export default function ImplementationsPages({ body='Details for migrations from Draft 2019-09 to 2020-12.' headerSize='small' bodyTextSize='small' - link='/draft/2020-12/release-notes' + link='/draft/2020-12/migration-notes' /> + +