json-schema-org · kwennB · Oct 24, 2024 · Oct 25, 2024 · Oct 25, 2024 · Oct 28, 2024
@@ -58,6 +58,22 @@ export function DocsHelp({
   const [error, setError] = useState('');
   const feedbackFormRef = useRef<HTMLFormElement>(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'}`;
+  }
+
   // Generate GitHub redirect URL
   const getGitRedirect = () => {
     if (
@@ -348,6 +364,31 @@ export function DocsHelp({
             </p>
           </div>
 
+          {showEditOption && (
+            <div className='my-4 text-[14px]'>
+              <a
+                target='_blank'
+                rel='noreferrer'
+                className='px-[16px] py-[8px] cursor-pointer border-solid border-[#aaaaaa] border rounded-md hover:bg-gray-200 dark:hover:bg-gray-600'
+                href={gitredirect} // Ensure gitredirect is defined
+                data-test='edit-on-github-link'
+              >
+                <svg
+                  className='inline-block select-none align-text-bottom mr-1'
+                  aria-hidden='true'
+                  role='img'
+                  viewBox='0 0 16 16'
+                  width='16'
+                  height='16'
+                  fill='currentColor'
+                >
+                  <path d='M1.5 3.25a2.25 2.25 0 1 1 3 2.122v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.25 2.25 0 0 1 1.5 3.25Zm5.677-.177L9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM3.75 2.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm0 9.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm8.25.75a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Z' />
+                </svg>
+                Edit this page on Github
+              </a>
+            </div>
+          )}
+
           {showEditOption && (
             <div className='my-4 text-[14px]'>
               <Button

@@ -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-02');
+}
+export async function getStaticProps(args: any) {
+  return getStaticMarkdownProps(args, 'pages/draft-02');
+}
+
+export default function StaticMarkdownPage({
+  frontmatter,
+  content,
+}: {
+  frontmatter: any;
+  content: any;
+}) {
+  const fileRenderType = '_md';
+  const newTitle = 'JSON Schema - ' + frontmatter.title;
+
+  return (
+    <SectionContext.Provider value={frontmatter.section || null}>
+      <Head>
+        <title>{newTitle}</title>
+      </Head>
+      <Headline1>{frontmatter.title}</Headline1>
+      <StyledMarkdown markdown={content} />
+      <DocsHelp fileRenderType={fileRenderType} />
+    </SectionContext.Provider>
+  );
+}
+StaticMarkdownPage.getLayout = getLayout;
@@ -0,0 +1,4 @@
+---
+title: Draft 01 to Draft 02
+section: docs
+---
@@ -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 (
+    <SectionContext.Provider value={frontmatter.section || null}>
+      <Head>
+        <title>{newTitle}</title>
+      </Head>
+      <Headline1>{frontmatter.title}</Headline1>
+      <StyledMarkdown markdown={content} />
+      <DocsHelp fileRenderType={fileRenderType} />
+    </SectionContext.Provider>
+  );
+}
+StaticMarkdownPage.getLayout = getLayout;
@@ -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)
@@ -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 (
+    <SectionContext.Provider value={frontmatter.section || null}>
+      <Head>
+        <title>{newTitle}</title>
+      </Head>
+      <Headline1>{frontmatter.title}</Headline1>
+      <StyledMarkdown markdown={content} />
+      <DocsHelp fileRenderType={fileRenderType} />
+    </SectionContext.Provider>
+  );
+}
+StaticMarkdownPage.getLayout = getLayout;
@@ -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.
+
+<Infobox label="Note"> 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.
+</Infobox>
+
+
+### 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)