From a0c4a67b206df186a185c7e03861ca58addfd8f2 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Sun, 28 Aug 2022 12:41:20 +0300 Subject: [PATCH 1/3] Add glossary entries for keyword and meta-schema. --- learn/glossary.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/learn/glossary.md b/learn/glossary.md index 0b585c7a..94f1afbc 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -24,6 +24,12 @@ 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). @@ -33,6 +39,15 @@ JSON Schema can be used to validate JSON values of any type (as well as values f 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. + +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. From d6e3a4899366dbd73d8f1a9a43c7b5c6c0f4a759 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Sun, 28 Aug 2022 12:41:46 +0300 Subject: [PATCH 2/3] Loosen the verbiage around the schema<->instance interaction in the glossary. --- learn/glossary.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/learn/glossary.md b/learn/glossary.md index 94f1afbc..8cbbda00 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -32,9 +32,9 @@ The [JSON Schema specification](https://json-schema.org/specification.html) defi ### 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. @@ -63,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. From c5ecf1c924746f17517a8168161af382502fb669 Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Tue, 30 Aug 2022 18:27:43 +0300 Subject: [PATCH 3/3] =?UTF-8?q?Avoid=20getting=20anywhere=20near=20=C2=A79?= =?UTF-8?q?.3.3=20in=20the=20meta-schema=20glossary=20entry.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- learn/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/glossary.md b/learn/glossary.md index 8cbbda00..6ffd5392 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -44,7 +44,7 @@ In particular it does not reserve any properties within a JSON object for its ow 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. +Since schemas are themselves JSON values, they may be also be treated as *instances*, and therefore described by other schemas. We refer to the schema-of-a-schema as a "meta-schema" to express this use.