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

Add glossary entries for keyword and meta-schema. #469

Merged
merged 3 commits into from
Aug 31, 2022
Merged

Add glossary entries for keyword and meta-schema. #469

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a0c4a67
Add glossary entries for keyword and meta-schema.
Julian Aug 28, 2022
d6e3a48
Loosen the verbiage around the schema<->instance interaction in the g…
Julian Aug 28, 2022
c5ecf1c
Avoid getting anywhere near §9.3.3 in the meta-schema glossary entry.
Julian Aug 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions learn/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,30 @@ 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).

### keyword

A property appearing within a [schema](#schema) object.

The [JSON Schema specification](https://json-schema.org/specification.html) defines behavior for a large library of keywords which can be used to describe [instances](#instance).

### instance

A piece of JSON data which is to be validated by a [schema](#schema).
A piece of JSON data which is to be described by a [schema](#schema).

JSON Schema can be used to validate JSON values of any type (as well as values from many JSON-like formats which can be reasonably represented as JSON).
JSON Schema can be used to describe JSON values of any type (as well as values from many JSON-like formats which can be reasonably represented as JSON).

The JSON Schema specification makes no broad assumptions about the structure of instances themselves beyond those of the JSON specification itself.
In particular it does not reserve any properties within a JSON object for its own use, or require parsers of JSON to support features beyond those already mandated of JSON implementations.

### meta-schema

A [schema](#schema) which is itself intended to describe other *schemas*.

JSON Schema defines a language for describing any [instance](#instance) using a schema written in JSON.
Since schemas are themselves JSON values, they may be opaquely treated as *instances*, and therefore described by other schemas.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it's not entirely opaque, §9.3.3 notes that in some circumstances an alternate way of handling schema-instances SHOULD be implemented. I'm not quite sure how that should be dealt with as we don't want a huge tangent on an obscure case, but it should be acknowledged that meta-schema validation can be more complex.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you happy with deleting the word opaquely and just saying may also be treated as instances? That matches the language from §4.3.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Julian yeah that would work, thanks! Better than too much detail on the basic concept. I'll bonk the approve button again when I see that change, but feel free to consider it pre-approved - everything else is great.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, done. Thanks.


We refer to the schema-of-a-schema as a "meta-schema" to express this use.

### normative

In the context of JSON Schema, and formal specifications more broadly, a document which outlines standardized behavior.
Expand All @@ -48,9 +63,9 @@ This page for instance, not being a normative document, is not able to proscribe

### schema

A document, written according to the proscribed structure of the JSON Schema specification, which can be used to validate [instances](#instance).
A document, written according to the proscribed structure of the JSON Schema specification, which can be used to describe [instances](#instance).

The rules constituting what schemas are *valid* JSON Schemas, as well as the rules governing their behavior when validating instances, are defined by the JSON Schema specification.
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.

Expand Down