-
+
diff --git a/assets/main.scss b/assets/main.scss
index 9e965232..23875e58 100644
--- a/assets/main.scss
+++ b/assets/main.scss
@@ -176,4 +176,11 @@ $content-width: 960px !default;
.wrapper.buttons {
margin-bottom: 10px;
+}
+
+.custom-logo-link {
+ /* display: inline-block; */
+ max-height: 40px;
+ padding-bottom: 0.7em;
+ /* width: auto; */
}
\ No newline at end of file
diff --git a/assets/openjs_foundation-logo.svg b/assets/openjs_foundation-logo.svg
new file mode 100644
index 00000000..fa063e7c
--- /dev/null
+++ b/assets/openjs_foundation-logo.svg
@@ -0,0 +1,67 @@
+
+
+
diff --git a/draft/2020-12/meta/hyper-schema b/draft/2020-12/meta/hyper-schema
new file mode 120000
index 00000000..29e3d6ac
--- /dev/null
+++ b/draft/2020-12/meta/hyper-schema
@@ -0,0 +1 @@
+../../../_includes/draft/2020-12/meta/hyper-schema.json
\ No newline at end of file
diff --git a/implementations.md b/implementations.md
index 92aae02c..c2df42b0 100644
--- a/implementations.md
+++ b/implementations.md
@@ -50,10 +50,11 @@ Validators
{{ implementation.name }}
Supports:
- {% if implementation.date-draft %}
+ {% if implementation.date-draft and implementation.date-draft != empty %}
{{ implementation.date-draft | sort | reverse | join: ", " }}
+ {%- if implementation.draft and implementation.draft != empty %}, {% endif %}
{% endif %}
- {% if implementation.draft %}
+ {% if implementation.draft and implementation.draft != empty %}
draft-0{{ implementation.draft | sort | reverse | join: ", -0" }}
{% endif %}
@@ -156,19 +157,24 @@ For example, the only incompatibilities between draft-04 and draft-06 involve `e
- Python
- [Pydantic](https://pydantic-docs.helpmanual.io/) (MIT) - generates schemas from Python models based on Python 3.6+ type hints.
- [msgspec](https://jcristharif.com/msgspec/) (BSD-3-Clause) - generates schemas from Python type annotations.
+ - [mashumaro](https://github.com/Fatal1ty/mashumaro) (Apache 2.0) - generates schemas from Python type annotations
+ - [drf-jsonschema-serializer](https://github.com/maykinmedia/drf-jsonschema-serializer) (BSD-3-Clause) - generates schemas from Django Rest Framework serializers
- Java
- [jsonschema-generator](https://github.com/victools/jsonschema-generator) (Apache 2.0) - generates schemas from Java types *supports Draft 7 and Draft 2019-09*
- Scala
- [scala-jsonschema](https://github.com/andyglow/scala-jsonschema) (Apache 2.0) - generates schemad out of Scala case classes
- Ruby
- [Shale](https://github.com/kgiszczak/shale) (MIT) - generates schema from Ruby models *supports Draft 2020-12*
+- Rust
+ - [Schemars](https://github.com/GREsau/schemars) (MIT) - generates schema from Rust code *supports Draft 7*
#### From data
- Java
- - [saasquatch/json-schema-inferrer](https://github.com/saasquatch/json-schema-inferrer) _draft-07, -06, -04_ (Apache 2.0) - Java library for inferring JSON Schemas from one or multiple JSON samples.
+ - [saasquatch/json-schema-inferrer](https://github.com/saasquatch/json-schema-inferrer) _2020-12, 2019-09, draft-07, draft-06, draft-04_ (Apache 2.0) - Java library for inferring JSON Schemas from one or multiple JSON samples.
- Scala
- [Schema Guru](https://github.com/snowplow/schema-guru) (Apache 2.0) - CLI util, Spark Job and Web UI for deriving JSON Schemas out of corpus of JSON instances; see issue [178](https://github.com/snowplow/schema-guru/issues/178) for progress towards draft-06+ support
+ - [JSONoid](https://github.com/michaelmior/jsonoid-discovery/) (MIT) - command line tool and Spark application for inferring schemas from JSON documents, supports draft 2019-09
- Clojure
- [luposlip/json-schema](https://github.com/luposlip/json-schema) (Apache 2.0) - infer JSON Schema from Clojure data
- Online (web tool)
@@ -176,6 +182,10 @@ For example, the only incompatibilities between draft-04 and draft-06 involve `e
- [Liquid Online Tools](https://www.liquid-technologies.com/online-json-to-schema-converter) - infer JSON Schema from sample JSON data
- [quicktype.io](https://app.quicktype.io/#l=schema) - infer JSON Schema from samples, and generate TypeScript, C++, go, Java, C#, Swift, etc. types from JSON Schema
+#### From model
+
+- [Dataspecer](https://dataspecer.com) - Generates JSON Schema (and JSON-LD context) from conceptual model *supports Draft 2020-12*
+
Generators from schemas
-----------------------
@@ -193,8 +203,13 @@ are the only keywords that changed.
#### Code generation
+- Dotnet
+ - [Corvus.JsonSchema](https://www.nuget.org/packages/Corvus.Json.JsonSchema.TypeGeneratorTool/) - generates an idiomatic dotnet type model from JSON Schema files, supporting all JSON Schema features, including property accessors, enumeration, common string `format`, and JSON document building/modification; over low-level `System.Text.Json` types. *supports Draft 6, Draft 7, Draft 2019-09 and Draft 2020-12*.
- Elm
- [json-schema-to-elm](https://github.com/dragonwasrobot/json-schema-to-elm) - generates Elm types, JSON decoders+encoders, and fuzz tests from one or more JSON Schema files, using [dragonwasrobot/json_schema](https://github.com/dragonwasrobot/json_schema) *supports Draft 7*
+- Go
+ - [go-jsonschema](https://git.sr.ht/~emersion/go-jsonschema) - generates Go types and helpers from JSON schema files *supports Draft 2020-12*
+ - [protoc-gen-jsonschema](https://github.com/chrusty/protoc-gen-jsonschema) - Generates JSON schemas from protobuf proto v2 and v3 files.
- Java
- [jsonCodeGen](https://github.com/schlothauer-wauer/jsoncodegen) (MIT) - Groovy based generation tasks from JSON schema. Already includes templates/generators for Java Beans, Swagger specification files and PlantUML diagrams.
- [jsonschema2pojo](https://github.com/joelittlejohn/jsonschema2pojo) (Apache 2.0) - generates Java types from JSON Schema (or example JSON) and can annotate those types for data-binding with Jackson 2.x or Gson. *draft-07*
@@ -211,6 +226,8 @@ are the only keywords that changed.
- [statham](https://github.com/jacksmith15/statham-schema) (MIT) - generate type-annotated models from JSON Schema documents.
- Rust
- [schemafy](https://github.com/Marwes/schemafy/) - generates Rust types and serialization code from a JSON schema. *supports Draft 4*
+- Scala
+ - [json-schema-to-case-class](https://github.com/cchandurkar/json-schema-to-case-class) (MIT) - NPM Package, [Web UI](https://cchandurkar.github.io/json-schema-to-case-class) and a CLI to generate Scala case classes from JSON Schema. *Supports JSON Schema 2019-09, draft-07, -06, -04, -03*
- TypeScript
- [jsongenerator](https://github.com/jimblackler/jsonschematypes/tree/master/codegen) *JSON Schema 2019-09, draft-07, -06, -04, -03* (Apache-2.0)
- Ruby
@@ -283,6 +300,7 @@ the utility, and decided on a case-by-case basis.
- OpenAPI
- [JSON Schema to OpenAPI Schema](https://github.com/wework/json-schema-to-openapi-schema) _draft-04_ Draft-06 and -07 planned per README (MIT)
+ - [OpenAPI specification to JSON Schema](https://github.com/instrumenta/openapi2jsonschema) Draft-07 (MIT)
- Orderly
- [Orderly](https://github.com/lloyd/orderly) (BSD-3-Clause)
- RAML
@@ -290,6 +308,9 @@ the utility, and decided on a case-by-case basis.
- Webpack
- [@cloudflare/json-schema-ref-loader](https://github.com/cloudflare/json-schema-tools/tree/master/workspaces/json-schema-ref-loader) ([JSON Schema Tools](https://github.com/cloudflare/json-schema-tools)), (BSD-3-Clause) Webpack loader for dereference-able schemas in JSON, JSON5, YAML, or JavaScript
- [@cloudflare/json-schema-apidoc-loader](https://github.com/cloudflare/json-schema-tools/tree/master/workspaces/json-schema-apidoc-loader) ([JSON Schema Tools](https://github.com/cloudflare/json-schema-tools)), Back-end for [@cloudflare/doca](https://github.com/cloudflare/json-schema-tools/tree/master/workspaces/doca), _draft-04, -06, -07, and Doca extensions_
+- XSD
+ - [Oxygen XSD to JSON Schema](https://www.oxygenxml.com/json_converter.html#xsd-to-json-schema) - Generate from an XSD file a similar JSON Schema structure.
+ - [XSD to JSON Schema IntellJ plugin](https://plugins.jetbrains.com/plugin/19024-xsd-to-json-schema) - Plugin for converting an XML Schema (XSD) file to a JSON Schema file.
#### Testing
@@ -301,10 +322,10 @@ the utility, and decided on a case-by-case basis.
- [Altova XMLSpy 2019r3](https://www.altova.com/xmlspy-xml-editor#json_schema) - *Graphical JSON Schema editor for draft-06 and draft-7, as well as validation of JSON files based on JSON Schema*
- [Dashjoin JSON Schema editor](https://dashjoin.github.io/#/schema) - *Graphical online JSON Schema editor for draft-06 (minus oneOf, anyOf, allOf, not). The generated schema can be tested immediately via a form that is driven by it.*
- [Hackolade Studio](https://hackolade.com/help/JSONSchemaEditor.html) - *Visual JSON Schema editor for draft-04, draft-06, draft-07, 2019-09, 2020-12, as well as data modeling tool for NoSQL databases, storage formats, REST APIs, and JSON in RDBMS. Also converts to and from: different draft specifications, DDL, XSD, Swagger, OpenAPI, YAML, Avro, Parquet, Protobuf, and most of the NoSQL script syntaxes. Includes a GUI for Entity-Relationship Diagrams and a Command-Line Interface.*
-- [JSONBuddy](https://www.json-buddy.com/) - *Text and grid-style JSON editor and validator with JSON schema analyzer, context sensitive entry-helpers and sample data generation based on JSON schema. Support for draft-4, draft-6, draft-7 and 2019-09. JSON Schema validation debugger: Step through the validation process and set breakpoints.*
+- [JSONBuddy](https://www.json-buddy.com/) - *Text and grid-style JSON editor and validator. Complete JSON Schema development environment with JSON Schema analyzer, context sensitive entry-helpers, sample data generation based on JSON Schema and JSON Schema validation debugger: Step through the validation process and set breakpoints. JSON Schema testing tool including schema coverage. Support for draft-4, draft-6, draft-7, 2019-09 and 2020-12.*
- [JSONEditor Online](https://jsoneditoronline.org/) - *View, edit, format, and validate JSON online* Support draft-4, draft-6, and draft-7.
- [Liquid JSON Schema Editor](https://www.liquid-technologies.com/json-schema-editor) - *Graphical JSON Schema editor for draft-04, draft-06, draft-07 and 2019-09, with split source code and grphical editing. Includes validation of JSON files based on JSON Schema, JSON Sample Generator and JSON Schema Documentation Generator.*
-- [Oxygen JSON Editor](https://www.oxygenxml.com/xml_editor/json.html) - *JSON editor with a variety of editing features and helper views. Support for validation and editing JSON Schema draft-4, draft-6, and draft-7. Validation and editing of JSON files based on JSON Schema.*
+- [Oxygen JSON Schema Editor](https://www.oxygenxml.com/xml_developer/json_schema_editor.html) - *JSON Schema editor with a variety of editing features and helper views (Design/Text/Author). Support for validation and editing JSON Schema draft-4, draft-6, and draft-7, 2019-09 (partial), 2020-12 (partial). Validation and editing of JSON files based on JSON Schema.*
- [Perseid Modeler](https://www.datensen.com/data-modeling/perseid-modeler-for-json-schema.html) - *a modeling tool for JSON Schema and OpenAPI. Key features include: visual JSON schema creation using tree and ERD-like diagrams, support for JSON schema structures including operators and conditions, import of existing schemas from files, creation of detailed HTML reports, export to PDF, script generation, and more. Supported versions: draft 4, 6, 7, 2019-09 and 2020-12*
- [Stoplight Studio](https://stoplight.io/) - *JSON Schema IDE (text-based and GUI) with support for JSON/YAML linting, which can also be based on JSON Schema rules via Spectral. Support for draft-4, draft-6 and draft-7.*
- [Visual Studio Code](https://code.visualstudio.com/) - *Schema driven code completion, hovers and validation for editing JSON files (including schemas)*
@@ -313,9 +334,13 @@ the utility, and decided on a case-by-case basis.
#### Documentation generators
+
+- [docusaurus-json-schema-plugin](https://github.com/jy95/docusaurus-json-schema-plugin) - Schema viewer. Runs within a [Docusaurus](https://docusaurus.io/) web app. Supports draft-7, 2019-09, Draft 2020-12
+- [json-schema-static-docs](https://tomcollins.github.io/json-schema-static-docs/) - Generates human friendly markdown documentation from JSON Schema. Includes links between pages based on $ref values. Supports draft-7.
- [jsonschematic](https://github.com/yanick/jsonschematic/) - Svelte-based schema viewer. Runs as a local web app. Supports draft-7.
- [docson](https://github.com/lbovet/docson) - Javascript-based schema viewer. Runs as a local web app. Supports draft-4.
- [json-schema-for-humans](https://pypi.org/project/json-schema-for-humans/) - Generate HTML representation of a schema. Python-based. Supports draft-7.
+- [oXygen JSON Schema Documentation](https://www.oxygenxml.com/json_converter.html#generate-json-schema-documentation) - Generate JSON Schema documentation in HTML format including diagrams.
- [wetzel](https://github.com/CesiumGS/wetzel) - Generates Markdown and AsciiDoc. With some limitations, supports draft-3, draft-4, draft-7, and 2020-12.
Schema Repositories
diff --git a/index.md b/index.md
index 84fcfde3..6d2a709c 100644
--- a/index.md
+++ b/index.md
@@ -4,8 +4,11 @@ title: JSON Schema
permalink: /
---
+
+**JSON Schema** is a declarative language that allows you to **annotate** and **validate** JSON documents.
-**JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents.
+JSON Schema enables the confident and reliable use of the JSON data format.
+
## Benefits
@@ -20,6 +23,16 @@ permalink: /
+## Announcements and Feedback Solicitation: Specification Process
+
+* The JSON Schema media types (`application/schema+json` and `application/schema-instance+json`) will be published as an [IETF RFC](https://datatracker.ietf.org/doc/draft-ietf-httpapi-rest-api-mediatypes/), which has already been adopted by the HTTP APIs working group.
+* As an [Incubation-status OpenJS Foundation project](https://openjsf.org/projects/#incubating), we continue to work through our governance [todo list](https://github.com/json-schema-org/community/issues/129) to move to either At-Large or Impact status.
+* The bulk of our specification will be published under a new process currently [under public discussion](https://github.com/orgs/json-schema-org/discussions/234). All are encouraged to provide feedback! Our goals with this process include:
+ * In the next release, offer stability guarantees for long-stable aspects of JSON Schema.
+ * Provide clarity regarding which other aspects are close to a stable form, and which are more experimental.
+ * Publish our specifications in a way similar to OpenAPI and AsyncAPI, which are also part of the Linux Foundation (the larger umbrella under which the OpenJS Foundation exists).
+* We are working on finding the right path for Relative JSON Pointer to reach standardization in the near future. An IETF RFC currently remains the most likely path, although several details are still being worked out.
+
## What now?
Learn, Get help, Shape the Community, Chat, with the JSON Schema team and Community!
@@ -79,40 +92,6 @@ so we will usually refer to `2020-12` (without the word "draft") on this web sit
See the [Specification page](specification.html) for details about naming and numbering.
-### The Path to Standardization
-
-The JSON Schema project intends to shepherd all three draft series to either: RFC status, the equivalent within another standards body, and/or join a foundation and establish self publication rules.
-
-
-Read more
-
-Currently, we are continuing to improve our self-published Internet-Drafts. We are not actively pursuing joining a standards organisation.
-
-We have a few contacts related to each potential path, but if you have experience with such things and would like to help, please still contact us!
-
-In the meantime, publication of Internet-Draft documents can be tracked through the IETF:
-* [JSON Schema (core)](https://datatracker.ietf.org/doc/draft-bhutton-json-schema/)
-* [JSON Schema Validation](https://datatracker.ietf.org/doc/draft-bhutton-json-schema-validation/)
-* [Relative JSON Pointers](https://datatracker.ietf.org/doc/draft-bhutton-relative-json-pointer/)
-
-Internet-Drafts expire after six months, so our goal is to publish often enough to always have a set of unexpired drafts available. There may be brief gaps as we wrap up each draft and finalize the text.
-
-
-### Use of the _draft_ designation
-Releases of the JSON schema specification and meta schemas use the _draft_ designation primarily for historical reasons stemming from the relationship of this specification to IETF ([explained here](https://json-schema.org/specification-links.html#understanding-draft-names-and-numbers)).
-The use of this designation is under review but will continue until this review process completes to avoid changing the designation style multiple times.
-
-Read more
-
-The JSON schema project recognizes, condones, and advocates for the use of the JSON schema standard in production.
-
-Each release of the JSON schema specification is treated as a production release by the JSON schema project. All changes in each new release are made judiciously, with great care, thorough review and careful consideration of how the changes will impact existing users and implementations of the JSON schema specification.
-
-Similarly to most specifications, the JSON schema specification will continue to evolve, and not all releases will be backwards compatible. The intention, particularly for vocabularies such as validation which have been widely implemented, is to remain as compatible as possible from release to release. However, major changes can still occur given a clear enough need validated with the user community.
-
-When the _draft_ designation is dropped this may indicate that the frequency of releases and amount of changes in each release will decrease, but it won't indicate that no new releases will be made, or that all future releases will be backwards compatible.
-
-
## Quickstart
The JSON document being validated or described we call the *instance*, and the document containing the description is called the *schema*.
diff --git a/learn/file-system.md b/learn/file-system.md
index da7630b9..0544e423 100644
--- a/learn/file-system.md
+++ b/learn/file-system.md
@@ -66,16 +66,16 @@ We will start with a base JSON Schema expressing the following constraints:
Building out our JSON Schema from top to bottom:
-* The [`$id`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.1) keyword.
-* The [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1.1) keyword.
-* The [`type`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.1) validation keyword.
-* The [`required`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.5.3) validation keyword.
-* The [`properties`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.2.1) validation keyword.
+* The [`$id`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.1) keyword.
+* The [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.1.1) keyword.
+* The [`type`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.1.1) validation keyword.
+* The [`required`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.5.3) validation keyword.
+* The [`properties`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.2.1) validation keyword.
* The `/` key is empty now; We will fill it out later.
-* The [`patternProperties`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.2.2) validation keyword.
+* The [`patternProperties`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.2.2) validation keyword.
* This matches other property names via a regular expression. Note: it does not match `/`.
* The `^(/[^/]+)+$` key is empty now; We will fill it out later.
-* The [`additionalProperties`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.2.3) validation keyword.
+* The [`additionalProperties`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.2.3) validation keyword.
* The value here is `false` to constrain object properties to be either `/` or to match the regular expression.
> You will notice that the regular expression is explicitly anchored (with `^` and `$`): in JSON Schema, regular expressions (in `patternProperties` and in `pattern`) are not anchored by default.
@@ -104,11 +104,11 @@ We saw these keywords in the prior exercise: `$id`, `$schema`, `type`, `required
To this we add:
-* The [`description`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.1) annotation keyword.
-* The [`oneOf`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.2.1.3) keyword.
-* The [`$ref`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.3.1) keyword.
+* The [`description`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.1) annotation keyword.
+* The [`oneOf`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.2.1.3) keyword.
+* The [`$ref`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.3.1) keyword.
* In this case, all references used are local to the schema using a relative fragment URI (`#/...`).
-* The [`$defs`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.4) keyword.
+* The [`$defs`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.4) keyword.
* Including several key names which we will define later.
```json
@@ -142,12 +142,12 @@ To this we add:
Let's now extend this skeleton to add constraints to some of the properties.
-* Our `fstype` key uses the [`enum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.2) validation keyword.
+* Our `fstype` key uses the [`enum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.1.2) validation keyword.
* Our `options` key uses the following:
* The `type` validation keyword (see above).
- * The [`minItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.4.2) validation keyword.
- * The [`items`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.1.2) validation keyword.
- * The [`uniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.4.3) validation keyword.
+ * The [`minItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.4.2) validation keyword.
+ * The [`items`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2) validation keyword.
+ * The [`uniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.4.3) validation keyword.
* Together these say: `options` must be an array, and the items therein must be strings, there must be at least one item, and all items should be unique.
* We have a `readonly` key.
@@ -198,7 +198,7 @@ With these added constraints, the schema now looks like this:
One new keyword is introduced here:
-* The [`pattern`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.3.3) validation keyword notes the `device` key must be an absolute path starting with */dev*.
+* The [`pattern`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.3.3) validation keyword notes the `device` key must be an absolute path starting with */dev*.
```json
{
@@ -246,7 +246,7 @@ We do have a new key: `label` and the `pattern` validation keyword states it mus
We find another new keyword:
-* The [`format`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.7) annotation and assertion keyword.
+* The [`format`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7) annotation and assertion keyword.
```json
{
@@ -276,8 +276,8 @@ We find another new keyword:
Our last definition introduces two new keywords:
-* The [`minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.4) validation keyword.
-* The [`maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.2) validation keyword.
+* The [`minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.2.4) validation keyword.
+* The [`maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.2.2) validation keyword.
* Together these require the size be between 16 and 512, inclusive.
```json
diff --git a/learn/getting-started-step-by-step.md b/learn/getting-started-step-by-step.md
index 5c2e51d5..5e299de1 100644
--- a/learn/getting-started-step-by-step.md
+++ b/learn/getting-started-step-by-step.md
@@ -50,10 +50,10 @@ We start with four properties called **keywords** which are expressed as [JSON](
> Yes. the standard uses a JSON data document to describe data documents, most often that are also JSON data documents but could be in any number of other content types like `text/xml`.
-* The [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1.1) keyword states that this schema is written according to a specific draft of the standard and used for a variety of reasons, primarily version control.
-* The [`$id`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.1) keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against.
-* The [`title`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.1) and [`description`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.1) annotation keywords are descriptive only. They do not add constraints to the data being validated. The intent of the schema is stated with these two keywords.
-* The [`type`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.1) validation keyword defines the first constraint on our JSON data and in this case it has to be a JSON Object.
+* The [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.1.1) keyword states that this schema is written according to a specific draft of the standard and used for a variety of reasons, primarily version control.
+* The [`$id`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.1) keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against.
+* The [`title`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.1) and [`description`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.1) annotation keywords are descriptive only. They do not add constraints to the data being validated. The intent of the schema is stated with these two keywords.
+* The [`type`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.1.1) validation keyword defines the first constraint on our JSON data and in this case it has to be a JSON Object.
```json
{
@@ -67,9 +67,9 @@ We start with four properties called **keywords** which are expressed as [JSON](
We introduce the following pieces of terminology when we start the schema:
-* [Schema Keyword](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1.1): `$schema` and `$id`.
-* [Schema Annotations](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.1): `title` and `description`.
-* [Validation Keyword](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.1): `type`.
+* [Schema Keyword](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.1.1): `$schema` and `$id`.
+* [Schema Annotations](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.1): `title` and `description`.
+* [Validation Keyword](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.1.1): `type`.
## Defining the properties
@@ -77,10 +77,10 @@ We introduce the following pieces of terminology when we start the schema:
In JSON Schema terms, we update our schema to add:
-* The [`properties`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.2.1) validation keyword.
+* The [`properties`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.2.1) validation keyword.
* The `productId` key.
* `description` schema annotation and `type` validation keyword is noted -- we covered both of these in the previous section.
-* The [`required`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.5.3) validation keyword listing `productId`.
+* The [`required`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.5.3) validation keyword listing `productId`.
```json
@@ -130,8 +130,8 @@ In JSON Schema terms, we update our schema to add:
According to the store owner there are no free products. ;)
* The `price` key is added with the usual `description` schema annotation and `type` validation keywords covered previously. It is also included in the array of keys defined by the `required` validation keyword.
-* We specify the value of `price` must be something other than zero using the [`exclusiveMinimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.5) validation keyword.
- * If we wanted to include zero as a valid price we would have specified the [`minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.4) validation keyword.
+* We specify the value of `price` must be something other than zero using the [`exclusiveMinimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.2.5) validation keyword.
+ * If we wanted to include zero as a valid price we would have specified the [`minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.2.4) validation keyword.
```json
{
@@ -172,9 +172,9 @@ Therefore:
* The `tags` key is added with the usual annotations and keywords.
* This time the `type` validation keyword is `array`.
-* We introduce the [`items`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.1.2) validation keyword so we can define what appears in the array. In this case: `string` values via the `type` validation keyword.
-* The [`minItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.4.2) validation keyword is used to make sure there is at least one item in the array.
-* The [`uniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.4.3) validation keyword notes all of the items in the array must be unique relative to one another.
+* We introduce the [`items`](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.1.2) validation keyword so we can define what appears in the array. In this case: `string` values via the `type` validation keyword.
+* The [`minItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.4.2) validation keyword is used to make sure there is at least one item in the array.
+* The [`uniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.4.3) validation keyword notes all of the items in the array must be unique relative to one another.
* We did not add this key to the `required` validation keyword array because it is optional.
```json
@@ -276,7 +276,7 @@ So far our JSON schema has been wholly self contained. It is very common to shar
For this example we introduce a new JSON Schema resource and for both properties therein:
* We use the `minimum` validation keyword noted earlier.
-* We add the [`maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.2) validation keyword.
+* We add the [`maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.2.2) validation keyword.
* Combined, these give us a range to use in validation.
```json
diff --git a/learn/glossary.md b/learn/glossary.md
index 6ffd5392..8328a958 100644
--- a/learn/glossary.md
+++ b/learn/glossary.md
@@ -14,6 +14,18 @@ If you encounter a term you wish were defined here, please feel free to [file an
The entries on this page can be linked to via anchor links (e.g. `https://json-schema.org/learn/glossary.html#vocabulary`) when sharing a definition with others.
+### dialect
+
+A cohesive collection of [keywords](#keyword) available for use within a schema, often representing a use-case specific single release of the JSON Schema specification.
+
+Dialects, particularly the 2019-09 and 2020-12 dialects, are often defined via a collection of [vocabularies](#vocabulary).
+
+Each dialect is identified by a URI, its *dialect identifier*, which [schemas](#schema) may then reference in their `$schema` [keyword](#keyword).
+Doing so identifies the schema as being written in the dialect, and thereby indicates which keywords are usable within it, along with their intended meaning.
+
+The JSON Schema specification defines a number of dialects, each of which enable vocabularies suitable for the dialect's specific use case.
+These vocabularies are [described](https://json-schema.org/specification.html#general-purpose-meta-schema) in meta-schemas.
+
### draft
An individual release of the JSON Schema specification.
@@ -24,6 +36,18 @@ While future drafts may introduce new behavior or changes to existing behavior,
The current list of drafts can be found [here](https://json-schema.org/specification-links.html#published-drafts).
+### JSON
+
+A pervasive data interchange format used for representing and transmitting data as human readable text.
+JSON is extremely widely used, and parsers which can read and write it exist for essentially every commonly-used programming language.
+
+JSON Schema, distinctly, is built *on top* of JSON, in that JSON [schemas](#schema) are themselves JSON objects which describe JSON values.
+The two are, however, entirely different pieces of the conceptual puzzle, with JSON being a concrete format for *representing* data, and JSON Schema being a way to *schematize* data which is written in a JSON-compatible format.
+
+The JSON format is an open format, with its own [homepage](https://www.json.org/), and specifications published in the [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and [RFC-8259](https://datatracker.ietf.org/doc/html/rfc8259) documents from ECMA and the IETF respectively.
+In particular, it is not managed or developed by the JSON Schema team, who simply make use of the format.
+
+
### keyword
A property appearing within a [schema](#schema) object.
@@ -67,6 +91,40 @@ A document, written according to the proscribed structure of the JSON Schema spe
The rules constituting which schemas are conformant, as well as the rules governing their behavior when validating instances, are defined by the [JSON Schema specification](https://json-schema.org/specification.html).
-Strictly speaking, according to the specification, schemas are themselves JSON documents, though it is somewhat common for them to be authored or maintained in other languages which are easily translated to JSON, such as YAML.
+Strictly speaking, according to the specification, schemas are themselves [JSON documents](#JSON), though it is somewhat common for them to be authored or maintained in other languages which are easily translated to JSON, such as YAML.
In recent [drafts](#draft) of the specification, a schema is either a JSON object or a JSON boolean value.
+
+### subschema
+
+A [schema](#schema) which is itself contained within a surrounding parent schema.
+Like schemas themselves, in recent [drafts](#draft) of JSON Schema, subschemas are either [JSON](#JSON) objects or JSON boolean values.
+
+Within the JSON Schema specification and its [dialects](#dialect), a number of [keywords](#keyword) take subschemas as part of their values.
+For example, the `not` keyword takes a subschema value and inverts its result, succeeding whenever the subschema does not succeed, such that the [instance](#instance) `12` is invalid under `{"type": "string"}` but valid under `{"not": {"type": "string"}}`, where `{"type": "string"}` is a subschema contained in the full schema.
+
+Some subschemas may appear in more complex nested locations within a parent schema.
+The `allOf` keyword, for instance, takes an array of multiple subschemas and succeeds whenever all of the subschemas do individually.
+
+Whether something that otherwise *appears* to be a schema (based on its contents) actually *is* a subschema can be misleading at first glance without context or knowlege about its location within the parent schema.
+Specifically, in our above example, `{"type": "string"}` was a subschema of a larger schema, but in the schema `{"const": {"type": "string"}}`, it is *not* a subschema.
+Even though as a value it looks the same, the `const` keyword, which compares instances against a specific expected value, does *not* take a subschema as its value, its value is an opaque value with no particular meaning (such that in this schema, the number 12 would be invalid, but the precise instance `{"type": "string"}` is valid).
+Said more plainly, whether a particular value is a subschema or not depends on its precise location within a parent schema, as interpretation of the value depends on the defined behavior of the keyword(s) it lives under.
+
+Subschemas may themselves contain sub-subschemas, though colloquially one generally uses the term "subschema" regardless of the level of nesting, further clarifying which larger schema is the parent schema whenever needed.
+
+### vocabulary
+
+A tightly related collection of [keywords](keyword), grouped to facilitate re-use.
+
+A vocabulary is specified by a prose document or specification which explains the semantics of its keywords in a way suitable for implementers and users of the vocabulary.
+It often also includes a [meta-schema](#meta-schema) (or multiple metaschemas) which define the syntax of its keywords.
+
+Anyone can create and publish a vocabulary, and implementations generally will include facilities for extending themselves with support for additional vocabularies and their keywords.
+The JSON Schema specification includes a number of vocabularies which cover each of the keywords it defines.
+
+In some [dialects](#dialect) of JSON Schema, the `$vocabulary` keyword can be used to include the keywords defined by a vocabulary into the dialect, as well as to indicate whether implementations must specifically recognize the vocabulary in order to be able to process schemas written in the dialect or not.
+
+#### See also
+
+* [`json-schema-vocabularies`](https://github.com/json-schema-org/json-schema-vocabularies), a repository which collects known third-party JSON Schema vocabularies
diff --git a/learn/index.md b/learn/index.md
index 37c3a883..f94aaff2 100644
--- a/learn/index.md
+++ b/learn/index.md
@@ -12,4 +12,5 @@ title: Learn
* [card.schema.json](./examples/card.schema.json)
* [geographical-location.schema.json](./examples/geographical-location.schema.json)
* [Understanding JSON Schema](/understanding-json-schema/)
+* [JSON Schema reference documentation](https://www.learnjsonschema.com/)
* [JSON Schema Glossary](./glossary.md) which attempts to explain conversational terminology
diff --git a/slack.md b/slack.md
index 18113d47..cc97f5ed 100644
--- a/slack.md
+++ b/slack.md
@@ -1,3 +1,3 @@
---
-redirect_to: https://join.slack.com/t/json-schema/shared_invite/zt-15ylccbuu-3T2bRia8uzhE157TSW6nXg
+redirect_to: https://join.slack.com/t/json-schema/shared_invite/zt-1ywpdj4yd-bXiBLjYEbKWUjzon0qiY9Q
---
diff --git a/specification.md b/specification.md
index e70419a9..742d633c 100644
--- a/specification.md
+++ b/specification.md
@@ -30,7 +30,7 @@ They are also available on the IETF main site:
Meta-schemas
------------
-The meta-schemas are schemas against which other schemas can be validated.It is self-descriptive: the JSON Schema meta-schema validates itself.
+The meta-schemas are schemas against which other schemas can be validated. It is self-descriptive: the JSON Schema meta-schema validates itself.
The latest meta-schema is **2020-12**. For an explanation of the change to date-based identifiers, see the [Specification Links](specification-links.html) page.
+