diff --git a/learn/glossary.md b/learn/glossary.md index 325cd5a..15f8a9d 100644 --- a/learn/glossary.md +++ b/learn/glossary.md @@ -83,6 +83,24 @@ Strictly speaking, according to the specification, schemas are themselves JSON d In recent [drafts](#draft) of the specification, a schema is either a JSON object or a JSON boolean value. +### subschema + +A [schema](#schema) which is itself contained within a surrounding parent schema. +Like schemas themselves, in recent [drafts](#draft) of JSON Schema, subschemas are either JSON objects or JSON boolean values. + +Within the JSON Schema specification and its [dialects](#dialect), a number of [keywords](#keyword) take subschemas as part of their values. +For example, the `not` keyword takes a subschema value and inverts its result, succeeding whenever the subschema does not succeed, such that the [instance](#instance) `12` is invalid under `{"type": "string"}` but valid under `{"not": {"type": "string"}}`, where `{"type": "string"}` is a subschema contained in the full schema. + +Some subschemas may appear in more complex nested locations within a parent schema. +The `allOf` keyword, for instance, takes an array of multiple subschemas and succeeds whenever all of the subschemas do individually. + +Whether something that otherwise *appears* to be a schema (based on its contents) actually *is* a subschema can be misleading at first glance without context or knowlege about its location within the parent schema. +Specifically, in our above example, `{"type": "string"}` was a subschema of a larger schema, but in the schema `{"const": {"type": "string"}}`, it is *not* a subschema. +Even though as a value it looks the same, the `const` keyword, which compares instances against a specific expected value, does *not* take a subschema as its value, its value is an opaque value with no particular meaning (such that in this schema, the number 12 would be invalid, but the precise instance `{"type": "string"}` is valid). +Said more plainly, whether a particular value is a subschema or not depends on its precise location within a parent schema, as interpretation of the value depends on the defined behavior of the keyword(s) it lives under. + +Subschemas may themselves contain sub-subschemas, though colloquially one generally uses the term "subschema" regardless of the level of nesting, further clarifying which larger schema is the parent schema whenever needed. + ### vocabulary A tightly related collection of [keywords](keyword), grouped to facilitate re-use.