Skip to content
This repository was archived by the owner on Nov 2, 2023. It is now read-only.

Commit a0611aa

Browse files
committed
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.
1 parent fe3f20b commit a0611aa

File tree

1 file changed

+8
-5
lines changed

1 file changed

+8
-5
lines changed

learn/glossary.md

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,15 @@ The entries on this page can be linked to via anchor links (e.g. `https://json-s
1616

1717
### dialect
1818

19-
A collection of [vocabularies](#vocabulary), along with an indication of whether supporting each vocabulary is required to process schemas written in the dialect.
19+
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.
2020

21-
Dialects are identified by a URI, which [schemas](#schema) may then reference in their `$schema` [keyword](#keyword).
21+
Dialects, particularly the 2019-09 and 2020-12 dialects, are often defined via a collection of [vocabularies](#vocabulary).
22+
23+
Each dialect is identified by a URI, its *dialect identifier*, which [schemas](#schema) may then reference in their `$schema` [keyword](#keyword).
2224
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.
2325

24-
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.
26+
The JSON Schema specification defines a number of dialects, each of which enable vocabularies suitable for the dialect's specific use case.
27+
These vocabularies are [described](https://json-schema.org/specification.html#general-purpose-meta-schema) in meta-schemas.
2528

2629
### draft
2730

@@ -82,15 +85,15 @@ In recent [drafts](#draft) of the specification, a schema is either a JSON objec
8285

8386
### vocabulary
8487

85-
A collection of related [keywords](keyword), grouped to facilitate re-use.
88+
A tightly related collection of related [keywords](keyword), grouped to facilitate re-use.
8689

8790
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.
8891
It often also includes a [meta-schema](#meta-schema) (or multiple metaschemas) which define the syntax of its keywords.
8992

9093
Anyone can create and publish a vocabulary, and implementations generally will include facilities for extending themselves with support for additional vocabularies and their keywords.
9194
The JSON Schema specification includes a number of vocabularies which cover each of the keywords it defines.
9295

93-
Vocabularies are identified by a URI which may be referenced via the `$vocabulary` keyword in order to enable the vocabulary within a [dialect](#dialect).
96+
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.
9497

9598
#### See also
9699

0 commit comments

Comments
 (0)