From 2f0f2ff5372340d18361cc9024b7bf6658908788 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Tue, 11 Oct 2022 11:50:18 +0000 Subject: [PATCH 1/3] Add glossary entries for dialect and vocabulary. --- learn/glossary.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/learn/glossary.md b/learn/glossary.md index 6ffd5392..8f0cc815 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -14,6 +14,15 @@ 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 collection of [vocabularies](#vocabulary), along with an indication of whether supporting each vocabulary is required to process schemas written in the dialect. + +Dialects are identified by a URI, 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](https://json-schema.org/specification.html#general-purpose-meta-schema) a number of dialects, each of which enable vocabularies suitable for the dialect's specific use case. + ### draft An individual release of the JSON Schema specification. @@ -70,3 +79,18 @@ The rules constituting which schemas are conformant, as well as the rules govern 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. In recent [drafts](#draft) of the specification, a schema is either a JSON object or a JSON boolean value. + +### vocabulary + +A collection of related [keywords](keyword), grouped to facilitate re-use. + +A vocabulary typically includes both a [meta-schema](#meta-schema) which formally defines the keywords it contains, as well as a prose document or specification which explains the semantics of its keywords in a way suitable for implementers and users of the vocabulary. + +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. + +Vocabularies are identified by a URI which may be referenced via the `$vocabulary` keyword in order to enable the vocabulary within a [dialect](#dialect). + +#### See also + +* [`json-schema-vocabularies`](https://github.com/json-schema-org/json-schema-vocabularies), a repository which collects known third-party JSON Schema vocabularies From fe3f20bf46a7abc3b6427e49af1af35aa4f83446 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Wed, 12 Oct 2022 15:56:49 +0000 Subject: [PATCH 2/3] The vocabulary document is considered authoritative. --- learn/glossary.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/learn/glossary.md b/learn/glossary.md index 8f0cc815..1fd68007 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -84,7 +84,8 @@ In recent [drafts](#draft) of the specification, a schema is either a JSON objec A collection of related [keywords](keyword), grouped to facilitate re-use. -A vocabulary typically includes both a [meta-schema](#meta-schema) which formally defines the keywords it contains, as well as a prose document or specification which explains the semantics of its keywords in a way suitable for implementers and users of the vocabulary. +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. From 2f0a2f8b8304afcc263a242567dc04a2890a195e Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Wed, 26 Apr 2023 16:56:50 -0400 Subject: [PATCH 3/3] Slightly loosen the language defining dialects and vocabularies. Even though this isn't fully consistent with the current spec definitions, it matches colloquial uses, and perhaps plans for future changes to these two concepts, without sacrificing accuracy today. --- learn/glossary.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/learn/glossary.md b/learn/glossary.md index 1fd68007..325cd5a9 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -16,12 +16,15 @@ The entries on this page can be linked to via anchor links (e.g. `https://json-s ### dialect -A collection of [vocabularies](#vocabulary), along with an indication of whether supporting each vocabulary is required to process schemas written in the 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 are identified by a URI, which [schemas](#schema) may then reference in their `$schema` [keyword](#keyword). +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](https://json-schema.org/specification.html#general-purpose-meta-schema) a number of dialects, each of which enable vocabularies suitable for the dialect's specific use case. +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 @@ -82,7 +85,7 @@ In recent [drafts](#draft) of the specification, a schema is either a JSON objec ### vocabulary -A collection of related [keywords](keyword), grouped to facilitate re-use. +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. @@ -90,7 +93,7 @@ It often also includes a [meta-schema](#meta-schema) (or multiple metaschemas) w 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. -Vocabularies are identified by a URI which may be referenced via the `$vocabulary` keyword in order to enable the vocabulary within a [dialect](#dialect). +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