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

Add glossary entries for schema and instance. #462

Merged
merged 1 commit into from
Aug 26, 2022
Merged

Add glossary entries for schema and instance. #462

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 19 additions & 0 deletions learn/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,15 @@ 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).

### instance

A piece of JSON data which is to be validated 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).

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.

### normative

In the context of JSON Schema, and formal specifications more broadly, a document which outlines standardized behavior.
Expand All @@ -36,3 +45,13 @@ This page for instance, not being a normative document, is not able to proscribe
#### See also

* [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

### schema

A document, written according to the proscribed structure of the JSON Schema specification, which can be used to validate [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.
Copy link
Contributor

Choose a reason for hiding this comment

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

I always feel like using the term "valid" in describing schemas that don't break any rules of the specification is asking for confusing with "valid" as a result of validating an instance against a schema. Especially since a schema can be valid against the specification, or valid against its metaschema, with pretty different (though strongly related) meanings. In that suite I'm working on of schemas that violate their spec, I landed on "conformant" to the spec to differentiate that from validation.


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.