From 190a273f74d5dda16ce39257b107d88679040b7b Mon Sep 17 00:00:00 2001 From: Valeria Hernandez Luzardo Date: Sat, 15 Feb 2025 13:30:27 +0100 Subject: [PATCH 1/4] Add updated information architecture changes --- components/Sidebar.tsx | 386 +++++++++++------- pages/docs/index.page.tsx | 26 +- pages/implementers/_index.md | 5 +- pages/implementers/index.page.tsx | 14 +- pages/implementers/interfaces.md | 8 +- pages/learn/guides/index.page.tsx | 44 ++ pages/learn/index.page.tsx | 45 +- pages/specification.md | 6 +- pages/understanding-json-schema/about.md | 6 +- pages/understanding-json-schema/basics.md | 6 +- .../keywords/index.page.tsx | 22 +- .../reference/annotations.md | 6 +- .../reference/array.md | 6 +- .../reference/combining.md | 33 +- .../reference/composition.md | 18 + .../reference/conditionals.md | 12 +- .../reference/const.md | 6 +- .../reference/enum.md | 6 +- .../reference/generic.md | 26 +- .../reference/index.page.tsx | 130 ++++-- .../reference/metadata.md | 32 ++ .../reference/non_json_data.md | 10 +- .../reference/null.md | 6 +- .../reference/numeric.md | 6 +- .../reference/object.md | 6 +- .../reference/regular_expressions.md | 10 +- .../reference/schema.md | 12 +- .../reference/string.md | 8 +- .../reference/type.md | 92 +++-- .../understanding-json-schema/structuring.md | 30 +- public/icons/grad-cap-dark.svg | 23 ++ public/icons/grad-cap.svg | 23 ++ 32 files changed, 717 insertions(+), 352 deletions(-) create mode 100644 pages/learn/guides/index.page.tsx create mode 100644 pages/understanding-json-schema/reference/composition.md create mode 100644 pages/understanding-json-schema/reference/metadata.md create mode 100644 public/icons/grad-cap-dark.svg create mode 100644 public/icons/grad-cap.svg diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index 0118e2033..36680277b 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -102,6 +102,7 @@ const SegmentSubtitle = ({ label }: { label: string }) => { ); }; const getDocsPath = [ + '/docs', '/overview/what-is-jsonschema', '/overview/sponsors', '/overview/case-studies', @@ -117,13 +118,19 @@ const getStartedPath = [ '/learn/file-system', '/learn/miscellaneous-examples', '/learn/getting-started-step-by-step', + '/understanding-json-schema/about', + '/understanding-json-schema/basics', + '/learn/glossary', +]; +const getGuidesPath = [ + '/learn/guides', + '/implementers', + '/implementers/interfaces', ]; const getReferencePath = [ '/understanding-json-schema', '/understanding-json-schema/keywords', - '/understanding-json-schema/basics', '/understanding-json-schema/conventions', - '/understanding-json-schema/about', '/understanding-json-schema/credits', '/understanding-json-schema/structuring', '/understanding-json-schema/reference/annotations', @@ -134,6 +141,8 @@ const getReferencePath = [ '/understanding-json-schema/reference/conditionals', '/understanding-json-schema/reference/const', '/understanding-json-schema/reference/enum', + '/understanding-json-schema/reference/composition', + '/understanding-json-schema/reference/metadata', '/understanding-json-schema/reference/non_json_data', '/understanding-json-schema/reference/null', '/understanding-json-schema/reference/numeric', @@ -144,9 +153,6 @@ const getReferencePath = [ '/understanding-json-schema/reference/type', '/understanding-json-schema/reference/generic', '/understanding-json-schema/reference', - '/learn/glossary', - '/implementers', - '/implementers/interfaces', ]; const getSpecificationPath = [ '/draft/2020-12', @@ -192,10 +198,13 @@ export const SidebarLayout = ({ children }: { children: React.ReactNode }) => { }} > {getDocsPath.includes(pathWtihoutFragment) && ( -

Overview

+

Introduction

)} {getStartedPath.includes(pathWtihoutFragment) && ( -

Getting Started

+

Get started

+ )} + {getGuidesPath.includes(pathWtihoutFragment) && ( +

Guides

)} {getReferencePath.includes(pathWtihoutFragment) && (

Reference

@@ -264,6 +273,7 @@ export const DocsNav = ({ const [active, setActive] = useState({ getDocs: false, getStarted: false, + getGuides: false, getReference: false, getSpecification: false, }); @@ -272,6 +282,7 @@ export const DocsNav = ({ const newActive = { getDocs: false, getStarted: false, + getGuides: false, getReference: false, getSpecification: false, }; @@ -279,10 +290,13 @@ export const DocsNav = ({ newActive.getDocs = true; } else if (getStartedPath.includes(pathWtihoutFragment)) { newActive.getStarted = true; + setActive({ ...active, getStarted: true }); } else if (getReferencePath.includes(pathWtihoutFragment)) { newActive.getReference = true; } else if (getSpecificationPath.includes(pathWtihoutFragment)) { newActive.getSpecification = true; + } else if (getGuidesPath.includes(pathWtihoutFragment)) { + newActive.getGuides = true; } setActive(newActive); @@ -294,6 +308,7 @@ export const DocsNav = ({ getStarted: false, getReference: false, getSpecification: false, + getGuides: false, }); }; @@ -303,6 +318,7 @@ export const DocsNav = ({ getStarted: !active.getStarted, getReference: false, getSpecification: false, + getGuides: false, }); }; @@ -312,6 +328,17 @@ export const DocsNav = ({ getStarted: false, getReference: !active.getReference, getSpecification: false, + getGuides: false, + }); + }; + + const handleClickGuides = () => { + setActive({ + getDocs: false, + getStarted: false, + getGuides: !active.getGuides, + getReference: false, + getSpecification: false, }); }; @@ -319,6 +346,7 @@ export const DocsNav = ({ setActive({ getDocs: false, getStarted: false, + getGuides: false, getReference: false, getSpecification: !active.getSpecification, }); @@ -335,22 +363,26 @@ export const DocsNav = ({ const [reference_icon, setReference_icon] = useState(''); const [spec_icon, setSpec_icon] = useState(''); const [overview_icon, setOverview_icon] = useState(''); + const [guides_icon, setGuides_icon] = useState(''); useEffect(() => { if (resolvedTheme === 'dark') { setOverview_icon('/icons/eye-dark.svg'); setLearn_icon('/icons/compass-dark.svg'); setReference_icon('/icons/book-dark.svg'); setSpec_icon('/icons/clipboard-dark.svg'); + setGuides_icon('/icons/grad-cap-dark.svg'); } else { setOverview_icon('/icons/eye.svg'); setLearn_icon('/icons/compass.svg'); setReference_icon('/icons/book.svg'); setSpec_icon('/icons/clipboard.svg'); + setGuides_icon('/icons/grad-cap.svg'); } }, [resolvedTheme]); return ( - {/* Get Started */} - + {' '} + {/*Closing div: Introduction*/} + {/* Get started */}
- +
+ + +
- + {' '} + {/* Closing div: Get started */} + {/* Guides */} +
+
+
+ grad cap icon + +
+ + + +
+
+ + +
+ +
+ {/*Closing div tag: for implementers*/} +
+
{' '} + {/* Closing div: Guides */} {/* Reference */} -
+ {/*Opening div: inner reference div */}
- */} + {/*
*/} + {/**/} + {/* +
Opening div tag: understanding JSON*/}
+ {' '} + {/*Opening div: JSON data types*/} -
- -
- - - - - - - -
- -
- - - - -
- - - - -
-
+ + +
{' '} + {/*Closing div: JSON data types*/} +
+ {' '} + {/*Opening div: Schema constraints*/} -
+ +
{' '} + {/*Closing div: Schema constraints*/} + +
+ {/*Opening div: Schema metadata*/} + + +
{' '} + {/*Closing div: Schema metadata*/} + + +
+ {' '} + {/*Opening div: Schema composition*/} + + +
{' '} + {/*Closing div: Schema composition*/} + +
-
+ {' '} + {/*Closing div: inner reference div */} {/* Specification */} -
@@ -798,7 +906,7 @@ export const DocsNav = ({ /> @@ -814,4 +922,4 @@ export const DocsNav = ({ }; export const getLayout = (page: React.ReactNode) => - getSiteLayout({page}); + getSiteLayout({page}); \ No newline at end of file diff --git a/pages/docs/index.page.tsx b/pages/docs/index.page.tsx index f77c33782..c7c4800fd 100644 --- a/pages/docs/index.page.tsx +++ b/pages/docs/index.page.tsx @@ -17,33 +17,43 @@ export default function Welcome() { {newTitle}

JSON Schema is a declarative language for annotating and validating JSON - documents' structure, constraints, and data types. It provides a way to + documents' structure, constraints, and data types. It helps you standardize and define expectations for JSON data.
+ Our documentation will guide you through the basics and beyond of + defining and validating JSON data.
Explore the docs

+ ); } -Welcome.getLayout = getLayout; +Welcome.getLayout = getLayout; \ No newline at end of file diff --git a/pages/implementers/_index.md b/pages/implementers/_index.md index 0258345f0..6c1ab12dd 100644 --- a/pages/implementers/_index.md +++ b/pages/implementers/_index.md @@ -9,7 +9,8 @@ next: url: /implementers/interfaces --- -For Implementers +Implement JSON Schema ========================= -Welcome to the **Implementers** section! The place for implementation maintainers' Docs. +Dive into the technical details of implementing JSON Schema. +This section is for developers building tools and libraries that work with JSON Schema. diff --git a/pages/implementers/index.page.tsx b/pages/implementers/index.page.tsx index 6b056bd06..f62aace0e 100644 --- a/pages/implementers/index.page.tsx +++ b/pages/implementers/index.page.tsx @@ -33,8 +33,8 @@ export default function ContentExample({ diff --git a/pages/implementers/interfaces.md b/pages/implementers/interfaces.md index 193d5500b..3b7dccb57 100644 --- a/pages/implementers/interfaces.md +++ b/pages/implementers/interfaces.md @@ -1,12 +1,12 @@ --- -title: Common Interfaces across JSON Schema Implementations +title: Common interfaces across JSON Schema implementations section: implementers prev: label: For Implementers url: /implementers next: - label: Specification - url: /specification + label: Reference + url: /understanding-json-schema/reference --- JSON Schema is extremely widely used and nearly equally widely implemented. @@ -234,4 +234,4 @@ An API which facilitates the creation of new JSON Schema dialects, typically reg ## Failure Details -An API which allows for programmatic introspection of the causes of a particular validation failure, at minimum containing the failing keyword(s), value(s) and individual message(s) which led to the failure. +An API which allows for programmatic introspection of the causes of a particular validation failure, at minimum containing the failing keyword(s), value(s) and individual message(s) which led to the failure. \ No newline at end of file diff --git a/pages/learn/guides/index.page.tsx b/pages/learn/guides/index.page.tsx new file mode 100644 index 000000000..20c01045f --- /dev/null +++ b/pages/learn/guides/index.page.tsx @@ -0,0 +1,44 @@ +import React from 'react'; +import { getLayout } from '~/components/Sidebar'; +import Head from 'next/head'; +import { Headline1 } from '~/components/Headlines'; +import { SectionContext } from '~/context'; +import { DocsHelp } from '~/components/DocsHelp'; +import NextPrevButton from '~/components/NavigationButtons'; +import Card from '~/components/Card'; + +export default function Welcome() { + const fileRenderType = 'tsx'; + + const newTitle = 'Guides'; + return ( + + + {newTitle} + + {newTitle} +

+ Welcome to our new Guides section! +
+

+
+ +
+ + + + ); +} +Welcome.getLayout = getLayout; \ No newline at end of file diff --git a/pages/learn/index.page.tsx b/pages/learn/index.page.tsx index d1e98701b..cfbfd4703 100644 --- a/pages/learn/index.page.tsx +++ b/pages/learn/index.page.tsx @@ -10,7 +10,7 @@ import NextPrevButton from '~/components/NavigationButtons'; export default function Welcome() { const fileRenderType = 'tsx'; - const newTitle = 'Getting Started'; + const newTitle = 'Get Started'; return ( @@ -18,14 +18,31 @@ export default function Welcome() { {newTitle}

- New to JSON Schema and don't know where to start? + New to JSON Schema and don't know where to start? Explore our learning + resources and get started with JSON Schema.

+ + + +
In Draft 4, `$id` is just `id` (without the dollar-sign). - + \ No newline at end of file diff --git a/pages/understanding-json-schema/keywords/index.page.tsx b/pages/understanding-json-schema/keywords/index.page.tsx index 29c077862..d22e9ca60 100644 --- a/pages/understanding-json-schema/keywords/index.page.tsx +++ b/pages/understanding-json-schema/keywords/index.page.tsx @@ -43,16 +43,16 @@ export default function StaticMarkdownPage({ datas }: { datas: DataObject[] }) { return ( - JSON Schema - Keywords + JSON Schema - keywords - JSON Schema Keywords + JSON Schema keywords

- JSON Schema keywords are the building blocks of JSON Schema and they are - used to define the structure of a JSON document. + Keywords are the building blocks of JSON Schema and they are used to + define the structure of a JSON document.

- Find below the list of JSON Schema Keywords and their links to the JSON - Schema docs: + Below is a list of JSON Schema keywords with links to their respective + documentation.

{datas @@ -88,13 +88,13 @@ export default function StaticMarkdownPage({ datas }: { datas: DataObject[] }) { )}
); } -StaticMarkdownPage.getLayout = getLayout; +StaticMarkdownPage.getLayout = getLayout; \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/annotations.md b/pages/understanding-json-schema/reference/annotations.md index d72f906a2..c2a44d027 100644 --- a/pages/understanding-json-schema/reference/annotations.md +++ b/pages/understanding-json-schema/reference/annotations.md @@ -2,8 +2,8 @@ title: "Annotations" section: docs prev: - label: Generic keywords - url: /understanding-json-schema/reference/generic + label: Schema annotations and comments + url: /understanding-json-schema/reference/metadata next: label: Comments url: /understanding-json-schema/reference/comments @@ -67,4 +67,4 @@ the future. "readOnly": true, "writeOnly": false } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/array.md b/pages/understanding-json-schema/reference/array.md index 1a217f76c..c5cd7392c 100644 --- a/pages/understanding-json-schema/reference/array.md +++ b/pages/understanding-json-schema/reference/array.md @@ -2,8 +2,8 @@ title: "array" section: docs prev: - label: Object - url: /understanding-json-schema/reference/object + label: Type-specific keywords + url: /understanding-json-schema/reference/type next: label: Boolean url: /understanding-json-schema/reference/boolean @@ -538,4 +538,4 @@ The empty array always passes: ```json // props { "indent": true, "valid": true } [] -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/combining.md b/pages/understanding-json-schema/reference/combining.md index afe883a6c..45a8d7998 100644 --- a/pages/understanding-json-schema/reference/combining.md +++ b/pages/understanding-json-schema/reference/combining.md @@ -1,41 +1,36 @@ --- -title: "Schema Composition" +title: "Boolean JSON Schema combination" section: docs prev: - label: 'Media: string-encoding non-JSON data' - url: /understanding-json-schema/reference/non_json_data + label: Schema composition + url: /understanding-json-schema/reference/composition next: - label: Applying Subschemas Conditionally - url: /understanding-json-schema/reference/conditionals + label: Modular JSON Schema combination + url: /understanding-json-schema/structuring --- +## Introduction JSON Schema includes a few [keywords](../../learn/glossary#keyword) for combining schemas together. Note that this doesn\'t necessarily mean combining schemas from multiple -files or JSON trees, though these facilities help to enable that and are -described in [Structuring a complex schema](../../understanding-json-schema/structuring). Combining schemas may be as -simple as allowing a value to be validated against multiple criteria at -the same time. +files or JSON trees. To learn how to combine reusable JSON Schemas, see [Modular JSON Schema combination](../../understanding-json-schema/structuring). -These keywords correspond to well known boolean algebra concepts like -AND, OR, XOR, and NOT. You can often use these keywords to express -complex constraints that can\'t otherwise be expressed with standard -JSON Schema keywords. - -The keywords used to combine schemas are: +Here you will learn to combine schemas by allowing a value to be validated against multiple criteria at the same time. This task requires using keywords that correspond to well known boolean algebra concepts like +AND, OR, XOR, and NOT. The keywords used to combine schemas are the following: - `allOf`: (AND) Must be valid against *all* of the [subschemas](../../learn/glossary#subschema) - `anyOf`: (OR) Must be valid against *any* of the subschemas - `oneOf`: (XOR) Must be valid against *exactly one* of the subschemas +- `not`: (NOT) Must *not* be valid against the given schema All of these keywords must be set to an array, where each item is a schema. Be careful with recursive schemas as they can exponentially increase processing times. -In addition, there is: - -- `not`: (NOT) Must *not* be valid against the given schema +In the following sections you will learn to use these keywords to express +complex constraints that can\'t otherwise be expressed with standard +JSON Schema keywords. @@ -222,4 +217,4 @@ subschemas. The following two schemas are equivalent. { "multipleOf": 3 } ] } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/composition.md b/pages/understanding-json-schema/reference/composition.md new file mode 100644 index 000000000..fe7a23fe5 --- /dev/null +++ b/pages/understanding-json-schema/reference/composition.md @@ -0,0 +1,18 @@ +--- +title: "Schema composition" +section: docs +prev: + label: Conditional schema validation + url: /understanding-json-schema/reference/conditionals +next: + label: Boolean JSON Schema combination + url: /understanding-json-schema/reference/combining +--- + +JSON Schema offers powerful features for constructing complex and flexible schema structures. The main approaches to combining JSON schemas are the following: + +- **Modular combination**. This approach allows you to break down your data model into reusable components, fostering modularity, and maintainability. In [Modular JSON Schema combination](../../understanding-json-schema/structuring) you will learn about creating and utilizing reusable schemas, subschemas, and even self-referential (recursive) schemas. + +- **Boolean combination**. This approach allows you to validate a single data value against multiple criteria at the same time. JSON Schema provides a set of keywords that act like boolean operators (AND, OR, NOT) to achieve this. To enhance your understanding of these keywords and learn how to leverage them for complex validations, see [Boolean JSON Schema combination](../../understanding-json-schema/reference/combining). + +By mastering these techniques you will make your JSON schemas more scalable, flexible, and easy to maintain. \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/conditionals.md b/pages/understanding-json-schema/reference/conditionals.md index e02f259d0..a3b059572 100644 --- a/pages/understanding-json-schema/reference/conditionals.md +++ b/pages/understanding-json-schema/reference/conditionals.md @@ -1,12 +1,12 @@ --- -title: "Applying Subschemas Conditionally" +title: "Conditional schema validation" section: docs prev: - label: Schema Composition - url: /understanding-json-schema/reference/combining + label: Comments + url: /understanding-json-schema/reference/comments next: - label: Declaring a Dialect - url: /understanding-json-schema/reference/schema + label: Schema composition + url: /understanding-json-schema/reference/composition --- @@ -494,4 +494,4 @@ expressed as `A -> B`, `if`/`else` can be expressed as `!A -> B`, and > Since this pattern is not very intuitive, it\'s recommended to put your conditionals in `$defs` with a descriptive name and `$ref` it into your schema with -`"allOf": [{ "$ref": "#/$defs/sit-down-restaurant-implies-tip-is-required" }]`. +`"allOf": [{ "$ref": "#/$defs/sit-down-restaurant-implies-tip-is-required" }]`. \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/const.md b/pages/understanding-json-schema/reference/const.md index 7e0fe134e..939d498ac 100644 --- a/pages/understanding-json-schema/reference/const.md +++ b/pages/understanding-json-schema/reference/const.md @@ -5,8 +5,8 @@ prev: label: Enumerated values url: /understanding-json-schema/reference/enum next: - label: 'Media: string-encoding non-JSON data' - url: /understanding-json-schema/reference/non_json_data + label: Schema annotations and comments + url: /understanding-json-schema/reference/metadata --- @@ -33,4 +33,4 @@ export reasons: ```json // props { "indent": true, "valid": false } { "country": "Canada" } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/enum.md b/pages/understanding-json-schema/reference/enum.md index 2883bbad7..9cbfab50e 100644 --- a/pages/understanding-json-schema/reference/enum.md +++ b/pages/understanding-json-schema/reference/enum.md @@ -2,8 +2,8 @@ title: "Enumerated values" section: docs prev: - label: Comments - url: /understanding-json-schema/reference/comments + label: Enumerated and Constant Values + url: /understanding-json-schema/reference/generic next: label: Constant values url: /understanding-json-schema/reference/const @@ -55,4 +55,4 @@ null ```json // props { "indent": true, "valid": false } 0 -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/generic.md b/pages/understanding-json-schema/reference/generic.md index e8145c429..56e5ce12e 100644 --- a/pages/understanding-json-schema/reference/generic.md +++ b/pages/understanding-json-schema/reference/generic.md @@ -1,15 +1,23 @@ --- -title: "Generic keywords" +title: "Enumerated and constant values" section: docs prev: - label: Type Specific Keywords - url: /understanding-json-schema/reference/type + label: Dialect and vocabulary declaration + url: /understanding-json-schema/reference/schema next: - label: 'Media : string-encoding non-JSON data' - url: /understanding-json-schema/reference/non_json_data + label: Enumerated values + url: /understanding-json-schema/reference/enum --- -* [Annotations](../../understanding-json-schema/reference/annotations) -* [Comments](../../understanding-json-schema/reference/comments) -* [Enumerated values](../../understanding-json-schema/reference/enum) -* [Constant values](../../understanding-json-schema/reference/const) \ No newline at end of file +The `enum` and `const` keywords contribute to data validation by defining limits on the values a property can hold. + +- **Define a set of values**. Use the `enum` keyword to specify a finite set of acceptable values for a property. This ensures that only predefined options are valid. + +- **Define a fixed, single value**. Use the `const` keyword to force a property to have a single, fixed value. This keyword is more restrictive than `enum`. + +Learn more about how to use these keywords with the following resources: + +- [Enumerated values](../../understanding-json-schema/reference/enum) +- [Constant values](../../understanding-json-schema/reference/const) + +By effectively utilizing these keywords, you can significantly enhance the reliability and accuracy of your JSON data. \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/index.page.tsx b/pages/understanding-json-schema/reference/index.page.tsx index d1083acc6..88528bd40 100644 --- a/pages/understanding-json-schema/reference/index.page.tsx +++ b/pages/understanding-json-schema/reference/index.page.tsx @@ -1,44 +1,114 @@ import React from 'react'; import { getLayout } from '~/components/Sidebar'; -import fs from 'fs'; -import matter from 'gray-matter'; -import StyledMarkdown from '~/components/StyledMarkdown'; +import Head from 'next/head'; +import { Headline1 } from '~/components/Headlines'; import { SectionContext } from '~/context'; +import Card from '~/components/Card'; import { DocsHelp } from '~/components/DocsHelp'; import NextPrevButton from '~/components/NavigationButtons'; -export async function getStaticProps() { - const block1 = fs.readFileSync( - 'pages/understanding-json-schema/reference/_index.md', - 'utf-8', - ); - const { content: block1Content } = matter(block1); - return { - props: { - blocks: [block1Content], - }, - }; -} +export default function Welcome() { + const fileRenderType = 'tsx'; -export default function ContentExample({ - blocks, -}: { - blocks: any[]; - frontmatter: any; - content: any; -}) { - const fileRenderType = '_indexmd'; + const newTitle = 'JSON Schema reference'; return ( - - + + + {newTitle} + + {newTitle} +

+ Master the full power of JSON Schema with our reference documentation. +
+ From basic data types to advanced techniques like conditional validation + and schema composition, you will learn everything about JSON Schema + keywords through clear explanations and examples. By learning best + practices for building clear, scalable, and easy-to-maintain schemas, + you will ensure that your JSON data is both robust and flexible. +
+

+
+ + + + + + + + + +
); } -ContentExample.getLayout = getLayout; +Welcome.getLayout = getLayout; \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/metadata.md b/pages/understanding-json-schema/reference/metadata.md new file mode 100644 index 000000000..55edd9aa7 --- /dev/null +++ b/pages/understanding-json-schema/reference/metadata.md @@ -0,0 +1,32 @@ +--- +title: "Schema annotations and comments" +section: docs +prev: + label: Constant values + url: /understanding-json-schema/reference/const +next: + label: Annotations + url: http://localhost:3000/understanding-json-schema/reference/annotations +--- + +Annotations and comments are not directly related to the core structure and constraints of the JSON Schema itself. As such, keywords for annotations and comments are not required, however, using them can improve the maintainability of your schemas. + +Annotations are optional pieces of information that provide additional context or meaning to a JSON Schema. They are not used for data validation but can serve various purposes, such as: + +- **Descriptions**. Adding human-readable descriptions to properties or the entire schema. +- **Defaults**. Specifying default values for properties. +- **Examples**. Providing example JSON objects that validate against the schema. +- **ReadOnly/WriteOnly**. Indicating read-only or write-only properties (often used in API contexts). +- **Deprecated**. Marking properties or features that are discouraged from use and might be removed in the future. + + +While annotations don't enforce data validation, they play a valuable role in enhancing the clarity, usability, and maintainability of JSON Schemas. + +Unlike some programming languages, JSON Schema itself doesn't natively support comments. However, it provides the keyword `$comment`, which allows schema authors to add comments within their schema. These comments enhance the clarity and maintainability of your schemas; they're intended for schema maintainers and are invisible to applications using the schema for validation. + +By incorporating annotations and comments into your schemas you can improve their clarity, maintainability, and overall quality. This will ensure your schemas are easier to understand and managed over time. + +To get started, explore the following resources: + +- [Annotations](../../understanding-json-schema/reference/annotations) +- [Comments](../../understanding-json-schema/reference/comments) \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/non_json_data.md b/pages/understanding-json-schema/reference/non_json_data.md index 8726b055f..a52ffd01b 100644 --- a/pages/understanding-json-schema/reference/non_json_data.md +++ b/pages/understanding-json-schema/reference/non_json_data.md @@ -2,11 +2,11 @@ title: "Media: string-encoding non-JSON data" section: docs prev: - label: Generic Keywords - url: /understanding-json-schema/reference/generic + label: Modular JSON Schema combination¶ + url: /understanding-json-schema/structuring next: - label: Schema Composition - url: /understanding-json-schema/reference/combining + label: Specification + url: /specification --- @@ -152,4 +152,4 @@ The following schema indicates that a string contains a JSON object encoded usin "name": "John Doe", "age": 25 } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/null.md b/pages/understanding-json-schema/reference/null.md index 5a234a80b..7df5bdfca 100644 --- a/pages/understanding-json-schema/reference/null.md +++ b/pages/understanding-json-schema/reference/null.md @@ -5,8 +5,8 @@ prev: label: boolean url: /understanding-json-schema/reference/boolean next: - label: Generic Keywords - url: /understanding-json-schema/reference/generic + label: Numeric Types + url: /understanding-json-schema/reference/numeric --- When a [schema](../../learn/glossary#schema) specifies a `type` of `null`, it has only one acceptable value: `null`. @@ -52,4 +52,4 @@ false ```json // props { "indent": true, "valid": false } ⠀ -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/numeric.md b/pages/understanding-json-schema/reference/numeric.md index 993120191..60a8dbb74 100644 --- a/pages/understanding-json-schema/reference/numeric.md +++ b/pages/understanding-json-schema/reference/numeric.md @@ -2,8 +2,8 @@ title: "Numeric types" section: docs prev: - label: Regular Expressions - url: /understanding-json-schema/reference/regular_expressions + label: 'null' + url: /understanding-json-schema/reference/null next: label: Object url: /understanding-json-schema/reference/object @@ -284,4 +284,4 @@ Greater than `maximum`: 101 ``` -[tabs-end] +[tabs-end] \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/object.md b/pages/understanding-json-schema/reference/object.md index 3efff3364..b9e337386 100644 --- a/pages/understanding-json-schema/reference/object.md +++ b/pages/understanding-json-schema/reference/object.md @@ -5,8 +5,8 @@ prev: label: Numeric Types url: /understanding-json-schema/reference/numeric next: - label: Array - url: /understanding-json-schema/reference/array + label: Regular expressions + url: /understanding-json-schema/reference/regular_expressions --- @@ -692,4 +692,4 @@ non-negative integer. ```json // props { "indent": true, "valid": false } { "a": 0, "b": 1, "c": 2, "d": 3 } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/regular_expressions.md b/pages/understanding-json-schema/reference/regular_expressions.md index b04d452b2..121623080 100644 --- a/pages/understanding-json-schema/reference/regular_expressions.md +++ b/pages/understanding-json-schema/reference/regular_expressions.md @@ -2,11 +2,11 @@ title: "Regular Expressions" section: docs prev: - label: String - url: /understanding-json-schema/reference/string + label: 'object' + url: /understanding-json-schema/reference/object next: - label: Numeric types - url: /understanding-json-schema/reference/numeric + label: string + url: /understanding-json-schema/reference/string --- @@ -104,4 +104,4 @@ and that it also allows multiline strings. ```json // props { "indent": true, "valid": false } "{ foo }" -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/schema.md b/pages/understanding-json-schema/reference/schema.md index d428a1337..e4b9b63ba 100644 --- a/pages/understanding-json-schema/reference/schema.md +++ b/pages/understanding-json-schema/reference/schema.md @@ -1,12 +1,12 @@ --- -title: "Declaring a Dialect" +title: "Dialect and vocabulary declaration" section: docs prev: - label: Applying Subschemas Conditionally - url: /understanding-json-schema/reference/conditionals + label: string + url: /understanding-json-schema/reference/string next: - label: Structuring a complex schema - url: /understanding-json-schema/structuring + label: Value restrictions + url: /understanding-json-schema/reference/generic --- A version of JSON Schema is called a [dialect](../../learn/glossary#dialect). A dialect represents the @@ -192,4 +192,4 @@ This passes because ``requiredProperties`` is not understood ```json // props { "indent": true, "valid": true } { "foo": 42 } -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/string.md b/pages/understanding-json-schema/reference/string.md index dde680a68..1b5f59c79 100644 --- a/pages/understanding-json-schema/reference/string.md +++ b/pages/understanding-json-schema/reference/string.md @@ -2,11 +2,11 @@ title: string section: docs prev: - label: Type-specific keywords - url: /understanding-json-schema/reference/type -next: label: Regular expressions url: /understanding-json-schema/reference/regular_expressions +next: + label: Dialect and vocabulary declaration + url: /understanding-json-schema/reference/schema --- The `string` type is used for strings of text. It may contain Unicode characters. @@ -120,4 +120,4 @@ with an optional area code: ```json // props { "indent": true, "valid": false } "(800)FLOWERS" -``` +``` \ No newline at end of file diff --git a/pages/understanding-json-schema/reference/type.md b/pages/understanding-json-schema/reference/type.md index dd3698476..b6f899313 100644 --- a/pages/understanding-json-schema/reference/type.md +++ b/pages/understanding-json-schema/reference/type.md @@ -1,26 +1,26 @@ --- -title: "Type-specific keywords" +title: "Type-specific Keywords" section: docs prev: - label: JSON Schema Reference - url: /understanding-json-schema/reference + label: JSON Schema Keywords + url: /understanding-json-schema/keywords next: - label: Generic Keywords - url: /understanding-json-schema/reference/generic + label: Array + url: /understanding-json-schema/reference/array --- -The `type` [keyword](../../learn/glossary#keyword) is fundamental to JSON Schema. It specifies the data -type for a schema. +The `type` [keyword](../../learn/glossary#keyword) is fundamental to JSON Schema because it specifies the data type that a schema should expect. At its core, JSON Schema defines the following basic types: -* [string](../../understanding-json-schema/reference/string) -* [number](../../understanding-json-schema/reference/numeric#number) -* [integer](../../understanding-json-schema/reference/numeric#integer) -* [object](../../understanding-json-schema/reference/object) -* [array](../../understanding-json-schema/reference/array) -* [boolean](../../understanding-json-schema/reference/boolean) -* [null](../../understanding-json-schema/reference/null) +- [array](../../understanding-json-schema/reference/array) +- [boolean](../../understanding-json-schema/reference/boolean) +- [null](../../understanding-json-schema/reference/null) +- [numeric types](../../understanding-json-schema/reference/numeric) +- [object](../../understanding-json-schema/reference/object) +- [regular expressions](../../understanding-json-schema/reference/regular_expressions.md) +- [string](../../understanding-json-schema/reference/string) + These types have analogs in most programming languages, though they may go by different names. @@ -34,8 +34,8 @@ analogous types in Python: | JSON | Python | |---------|--------------| -| string | string *1 | -| number | int/float *2 | +| string | string [1] | +| number | int/float [2]| | object | dict | | array | list | | boolean | bool | @@ -43,11 +43,11 @@ analogous types in Python: #### Footnotes -[#1] Since JSON strings always support unicode, they are +[1] Since JSON strings always support unicode, they are analogous to `unicode` on Python 2.x and `str` on Python 3.x. -[#2] JSON does not have separate types for integer and +[2] JSON does not have separate types for integer and floating-point. [tab "Ruby"] @@ -58,7 +58,7 @@ analogous types in Ruby: | JSON | Ruby | |---------|----------------------| | string | String | -| number | Integer/Float *3 | +| number | Integer/Float [3] | | object | Hash | | array | Array | | boolean | TrueClass/FalseClass | @@ -66,7 +66,7 @@ analogous types in Ruby: #### Footnotes -[#3] JSON does not have separate types for integer and +[3] JSON does not have separate types for integer and floating-point. [tab "Perl"] @@ -94,13 +94,12 @@ their analogous types in Objective-C: | number | NSNumber | | object | NSDictionary | | array | NSArray | -| boolean | NSNumber | -| | [#4]_ | +| boolean | NSNumber [4]| | null | NSNull | #### Footnotes -[#4] `NSJSONSerialization` represents JavaScript numbers and booleans +[4] `NSJSONSerialization` represents JavaScript numbers and booleans as `NSNumber`. To distinguish them, we need to check an `NSNumber` value for identity (pointer equality) to `@YES` and `@NO` constants. @@ -112,8 +111,7 @@ their analogous types in Swift: | JSON | Swift | |---------|------------| | string | String | -| number | Int/Double | -| | [#5]_ | +| number | Int/Double [5]| | object | Dictionary | | array | Array | | boolean | Bool | @@ -121,21 +119,17 @@ their analogous types in Swift: #### Footnotes -[#5] While JavaScript does not have separate types for integer and +[5] While JavaScript does not have separate types for integer and floating-point, Swift ``JSONDecoder`` throws an error on attempt to decode ``Int`` from a non-integer number in JSON. [tabs-end] -The `type` keyword may either be a string or an array: +The `type` keyword can take two forms: -- If it\'s a string, it is the name of one of the basic types above. -- If it is an array, it must be an array of strings, where each string - is the name of one of the basic types, and each element is unique. - In this case, the JSON snippet is valid if it matches *any* of the - given types. +1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type. -Here is a simple example of using the `type` keyword: +Here is an example of using the `string` keyword as a single string: ```json // props { "isSchema": true } @@ -156,8 +150,9 @@ Here is a simple example of using the `type` keyword: "42" ``` -In the following example, we accept strings and numbers, but not -structured data types: +2. **An array of strings**. When `type` is used as an array, it contains more than one string specifying the types mentioned above. In this case, the instance data is valid if it matches _any_ of the given types. + +Here is an example using the `type` keyword as an array of strings, where instance data of the type `string` and `number` are valid but `array` isn't: ```json // props { "isSchema": true } @@ -176,11 +171,26 @@ structured data types: ["Life", "the universe", "and everything"] ``` -For each of these types, there are keywords that only apply to those -types. For example, numeric types have a way of specifying a numeric -range, that would not be applicable to other types. In this reference, -these validation keywords are described along with each of their -corresponding types in the following chapters. +JSON Schema offers a variety of keywords to validate data against specific types. The following table outlines keywords that are specifically designed for each basic data type: + +| Type Keyword | Specific Keywords | Description | +|---|---|---| +| [array](../../understanding-json-schema/reference/array) | `items`, `additionalItems`, `minItems`, `maxItems`, `uniqueItems` | Define item schemas, additional item handling, item count constraints, and uniqueness. | +| [number](../../understanding-json-schema/reference/numeric) | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` | Define numeric ranges, including exclusive bounds and divisibility. | +| [object](../../understanding-json-schema/reference/object) | `required`, `properties`, `additionalProperties`, `patternProperties`, `minProperties`, `maxProperties`, `dependencies` | Define required properties, property schemas, additional property handling, pattern-based property matching, and property count constraints. | +| [string](../../understanding-json-schema/reference/string) | `minLength`, `maxLength`, `pattern`, `format`| Restrict string length, pattern matching, and format validation (e.g., email, date). | + + +Understanding these basic data types gives you a strong foundation for building more complex JSON Schemas. + + +Dive deeper into our reference and explore JSON Schema's flexibility for creating complex data structures: + +- [Value restrictions](/understanding-json-schema/reference/generic). Define precise limitations for data, ensuring accuracy and consistency. +- [Conditional schema validation](/understanding-json-schema/reference/conditionals). Validate schemas dynamically based on specific conditions. +- [Schema composition](/understanding-json-schema/reference/generic). Build modular and reusable schemas, making your validation process more efficient and maintainable. + +By utilizing these advanced features, you can create robust and flexible JSON Schemas that meet your exact needs. ## Format[#format] @@ -241,4 +251,4 @@ Dates and times are represented in [RFC 3339, section 5.6](https://tools.ietf.or #### Regular Expressions -- `"regex"`: A regular expression that should be valid according to the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) [dialect](../../learn/glossary#dialect). Be careful, in practice, JSON Schema validators are only required to accept the safe subset of [regular expressions](../../understanding-json-schema/reference/regular_expressions) described elsewhere in this document. +- `"regex"`: A regular expression that should be valid according to the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) [dialect](../../learn/glossary#dialect). Be careful, in practice, JSON Schema validators are only required to accept the safe subset of [regular expressions](../../understanding-json-schema/reference/regular_expressions) described elsewhere in this document. \ No newline at end of file diff --git a/pages/understanding-json-schema/structuring.md b/pages/understanding-json-schema/structuring.md index 1084966bf..5aa02de0c 100644 --- a/pages/understanding-json-schema/structuring.md +++ b/pages/understanding-json-schema/structuring.md @@ -1,33 +1,23 @@ --- -title: "Structuring a complex schema" +title: "Modular JSON Schema combination" section: docs prev: - label: Declaring a dialect - url: /understanding-json-schema/reference/schema + label: Boolean JSON Schema combination + url: /understanding-json-schema/reference/combining next: - label: For Implementers - url: /implementers + label: 'Media: string-encoding non-JSON data' + url: /understanding-json-schema/reference/non_json_data --- -* [Schema Identification](#schema-identification) -* [Base URI](#base-uri) -* [$ref](#dollarref) -* [$id](#id) -* [$defs](#defs) -* [Recursion](#recursion) -* [Extending Recursive Schemas](#extending-recursive-schemas) -* [Bundling](#bundling) +## Introduction When writing computer programs of even moderate complexity, it\'s commonly accepted that \"structuring\" the program into reusable -functions is better than copying-and-pasting duplicate bits of code -everywhere they are used. Likewise in JSON Schema, for anything but the -most trivial schema, it\'s really useful to structure the schema into -parts that can be reused in a number of places. This chapter will -present the tools available for reusing and structuring schemas as well -as some practical examples that use those tools. +functions is better than duplicating code. Similarly, in JSON Schema, structuring your schema into reusable components is highly beneficial for anything beyond the most trivial cases. + +Here, you will learn about the keywords used to combine JSON schemas modularly and see examples of their application. @@ -575,4 +565,4 @@ In Draft 4-7, a subschema `$id` is just a base URI change and not In Draft 2020-12, support for changing dialects in an embedded schema (using `$schema` with a different value than the parent schema) was added. - + \ No newline at end of file diff --git a/public/icons/grad-cap-dark.svg b/public/icons/grad-cap-dark.svg new file mode 100644 index 000000000..13add490b --- /dev/null +++ b/public/icons/grad-cap-dark.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/icons/grad-cap.svg b/public/icons/grad-cap.svg new file mode 100644 index 000000000..fa6b05913 --- /dev/null +++ b/public/icons/grad-cap.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + From 6bb68953c1d1aa3249909dc5f3538ff3f9efbb2b Mon Sep 17 00:00:00 2001 From: Valeria Hernandez Luzardo Date: Sat, 15 Feb 2025 13:45:36 +0100 Subject: [PATCH 2/4] add npm fix --- components/Sidebar.tsx | 2 +- pages/docs/index.page.tsx | 2 +- pages/learn/guides/index.page.tsx | 4 ++-- pages/learn/index.page.tsx | 6 +++--- pages/understanding-json-schema/keywords/index.page.tsx | 2 +- pages/understanding-json-schema/reference/index.page.tsx | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index 36680277b..ad52e2ab8 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -922,4 +922,4 @@ export const DocsNav = ({ }; export const getLayout = (page: React.ReactNode) => - getSiteLayout({page}); \ No newline at end of file + getSiteLayout({page}); diff --git a/pages/docs/index.page.tsx b/pages/docs/index.page.tsx index c7c4800fd..d68ed0c93 100644 --- a/pages/docs/index.page.tsx +++ b/pages/docs/index.page.tsx @@ -71,4 +71,4 @@ export default function Welcome() { ); } -Welcome.getLayout = getLayout; \ No newline at end of file +Welcome.getLayout = getLayout; diff --git a/pages/learn/guides/index.page.tsx b/pages/learn/guides/index.page.tsx index 20c01045f..1e2d09e8f 100644 --- a/pages/learn/guides/index.page.tsx +++ b/pages/learn/guides/index.page.tsx @@ -18,7 +18,7 @@ export default function Welcome() { {newTitle}

- Welcome to our new Guides section! + Welcome to our new Guides section!

@@ -41,4 +41,4 @@ export default function Welcome() { ); } -Welcome.getLayout = getLayout; \ No newline at end of file +Welcome.getLayout = getLayout; diff --git a/pages/learn/index.page.tsx b/pages/learn/index.page.tsx index cfbfd4703..7fc4b8bbc 100644 --- a/pages/learn/index.page.tsx +++ b/pages/learn/index.page.tsx @@ -18,13 +18,13 @@ export default function Welcome() { {newTitle}

- New to JSON Schema and don't know where to start? Explore our learning - resources and get started with JSON Schema. + New to JSON Schema and don't know where to start? Explore our learning + resources and get started with JSON Schema.

- ); } -StaticMarkdownPage.getLayout = getLayout; \ No newline at end of file +StaticMarkdownPage.getLayout = getLayout; diff --git a/pages/understanding-json-schema/reference/index.page.tsx b/pages/understanding-json-schema/reference/index.page.tsx index 88528bd40..f6afbfa76 100644 --- a/pages/understanding-json-schema/reference/index.page.tsx +++ b/pages/understanding-json-schema/reference/index.page.tsx @@ -111,4 +111,4 @@ export default function Welcome() { ); } -Welcome.getLayout = getLayout; \ No newline at end of file +Welcome.getLayout = getLayout; From ff028f980ec694c025e1225b3522ccb3f5ff077b Mon Sep 17 00:00:00 2001 From: Valeria Hernandez Luzardo Date: Fri, 28 Feb 2025 11:20:43 +0100 Subject: [PATCH 3/4] Add 301 redirects --- pages/understanding-json-schema/reference/index.page.tsx | 1 + public/_redirects | 3 +++ 2 files changed, 4 insertions(+) diff --git a/pages/understanding-json-schema/reference/index.page.tsx b/pages/understanding-json-schema/reference/index.page.tsx index f6afbfa76..763124561 100644 --- a/pages/understanding-json-schema/reference/index.page.tsx +++ b/pages/understanding-json-schema/reference/index.page.tsx @@ -20,6 +20,7 @@ export default function Welcome() {

Master the full power of JSON Schema with our reference documentation.
+
From basic data types to advanced techniques like conditional validation and schema composition, you will learn everything about JSON Schema keywords through clear explanations and examples. By learning best diff --git a/public/_redirects b/public/_redirects index 85e91c411..3b772478d 100644 --- a/public/_redirects +++ b/public/_redirects @@ -23,3 +23,6 @@ /obsolete-implementations /tools?showObsolete=true 301 /slack https://join.slack.com/t/json-schema/shared_invite/zt-2ued3v79g-Tk_aI32ZdW~ST0EWpGBwNQ 301 /slack-redirect https://join.slack.com/t/json-schema/shared_invite/zt-2ued3v79g-Tk_aI32ZdW~ST0EWpGBwNQ 301 +/understanding-json-schema /understanding-json-schema/reference 301 +/understanding-json-schema/conventions /understanding-json-schema/reference 301 +/understanding-json-schema/reference/_index.md /understanding-json-schema/reference 301 \ No newline at end of file From 5eb02b599c34f0330d5329deb9136a02897af53a Mon Sep 17 00:00:00 2001 From: Benjamin Granados <40007659+benjagm@users.noreply.github.com> Date: Tue, 4 Mar 2025 08:34:56 +0100 Subject: [PATCH 4/4] Rename link title --- components/Sidebar.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index ad52e2ab8..687995087 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -707,7 +707,7 @@ export const DocsNav = ({

Opening div tag: understanding JSON*/}