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

Commit d19bf52

Browse files
committed
Add a Glossary page with 2 initial entries.
Doing so should hopefully now allow farming out additional entries. Refs: json-schema-org/community#199.
1 parent 56b08a2 commit d19bf52

File tree

2 files changed

+34
-0
lines changed

2 files changed

+34
-0
lines changed

learn/glossary.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# JSON Schema Glossary
2+
3+
This document collects short explanations of terminology one may encounter within the JSON Schema community.
4+
5+
Whilst many of the entries below have precise technical definitions, preference is given to explanations of their conversational use, with additional references linked for further information.
6+
This page is not meant to be [normative](#normative), nor is it meant to contain fully original research or explanation.
7+
It is meant to aid the understanding of those less familiar with formal language used within JSON Schema, or within specifications more broadly.
8+
(In fact, entries below make effort to avoid terminology like "normative" itself for reasons just mentioned.)
9+
10+
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.
11+
12+
### draft
13+
14+
An individual release of the JSON Schema specification.
15+
16+
JSON Schema drafts are not intended to be provisional documents, as the layman's use of the word "draft" might indicate.
17+
18+
While future drafts may introduce new behavior or changes to existing behavior, each draft is a completed, released document, batching together changes to the specification, and intended for implementation and use.
19+
20+
The current list of drafts can be found [here](https://json-schema.org/specification-links.html#published-drafts).
21+
22+
### normative
23+
24+
In the context of JSON Schema, and formal specifications more broadly, a document which outlines standardized behavior.
25+
This is as distinct from *non*-normative or informational documents, meant to explain, simplify or offer opinions.
26+
27+
Distinguishing between whether a document is normative or not is intended to clarify to those using the document whether its contents are allowed to contradict or augment behavior described in other normative documents.
28+
JSON Schema's normative documents notably include its [specification](https://json-schema.org/specification.html).
29+
This page for instance, not being a normative document, is not able to proscribe new JSON Schema behavior not already covered by the specification.
30+
31+
##### See also
32+
33+
* [normative](https://developer.mozilla.org/en-US/docs/Glossary/Normative) and [non-normative](https://developer.mozilla.org/en-US/docs/Glossary/non-normative) in the Mozilla Glossary, and its links

learn/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ title: Learn
1212
* [card.schema.json](./examples/card.schema.json)
1313
* [geographical-location.schema.json](./examples/geographical-location.schema.json)
1414
* [Understanding JSON Schema](/understanding-json-schema/)
15+
* [JSON Schema Glossary](./glossary.md) which attempts to explain conversational terminology

0 commit comments

Comments
 (0)