2.2.1. Empty

The empty form is defined by the empty CDDL rule in Figure 1. The semantics of the empty form are described in Section 3.3.1.¶

Despite the name "empty", schemas of the empty form are not necessarily empty JSON objects. Like schemas of any of the eight forms, schemas of the empty form may contain members named nullable (whose value must be true or false) or metadata (whose value must be an object) or both.¶

Thus,¶

   {}

and¶

   { "nullable": true }

and¶

   { "nullable": true, "metadata": { "foo": "bar" }}

are correct JTD schemas of the empty form, but¶

   { "nullable": "foo" }

is not, because the value of the member named nullable must be true or false.¶

2.2.2. Ref

The ref form is defined by the ref CDDL rule in Figure 1. The semantics of the ref form are described in Section 3.3.2.¶

For a schema of the ref form to be correct, the value of the member named ref must refer to one of the definitions found at the root level of the schema it appears in. More formally, for a schema S of the ref form:¶

• Let B be the root schema containing the schema or the schema itself if it is a root schema.¶
• Let R be the value of the member of S with the name ref.¶

If the schema is correct, then B MUST have a member D with the name definitions, and D MUST contain a member whose name equals R.¶

Thus,¶

   {
     "definitions": {
       "coordinates": {
         "properties": {
           "lat": { "type": "float32" },
           "lng": { "type": "float32" }
         }
       }
     },
     "properties": {
       "user_location": { "ref": "coordinates" },
       "server_location": { "ref": "coordinates" }
     }
   }

is a correct JTD schema and demonstrates the point of the ref form: to avoid redefining the same thing twice. However,¶

   { "ref": "foo" }

is not a correct JTD schema, as there are no top-level definitions, and so the ref form cannot be correct. Similarly,¶

   { "definitions": { "foo": {}}, "ref": "bar" }

is not a correct JTD schema, as there is no member named bar in the top-level definitions.¶

2.2.3. Type

The type form is defined by the type CDDL rule in Figure 1. The semantics of the type form are described in Section 3.3.3.¶

As an example of a correct JTD schema of the type form,¶

   { "type": "uint8" }

is a correct JTD schema, whereas¶

   { "type": true }

and¶

   { "type": "foo" }

are not correct schemas, as neither true nor the JSON string foo are in the list of permitted values of the type member described in the type CDDL rule in Figure 1.¶

2.2.4. Enum

The enum form is defined by the enum CDDL rule in Figure 1. The semantics of the enum form are described in Section 3.3.4.¶

For a schema of the enum form to be correct, the value of the member named enum must be a nonempty array of strings, and that array must not contain duplicate values. More formally, for a schema S of the enum form:¶

• Let E be the value of the member of S with name enum.¶

If the schema is correct, then there MUST NOT exist any pair of elements of E that encode equal string values, where string equality is defined as in Section 8.3 of [RFC8259].¶

Thus,¶

   { "enum": [] }

is not a correct JTD schema, as the value of the member named enum must be nonempty, and¶

   { "enum": ["a\\b", "a\u005Cb"] }

is not a correct JTD schema, as¶

   "a\\b"

and¶

   "a\u005Cb"

encode strings that are equal by the definition of string equality given in Section 8.3 of [RFC8259]. By contrast,¶

   { "enum": ["PENDING", "IN_PROGRESS", "DONE" ]}

is an example of a correct JTD schema of the enum form.¶

2.2.5. Elements

The elements form is defined by the elements CDDL rule in Figure 1. The semantics of the elements form are described in Section 3.3.5.¶

As an example of a correct JTD schema of the elements form,¶

   { "elements": { "type": "uint8" }}

is a correct JTD schema, whereas¶

   { "elements": true }

and¶

   { "elements": { "type": "foo" } }

are not correct schemas, as neither¶

   true

nor¶

   { "type": "foo" }

are correct JTD schemas, and the value of the member named elements must be a correct JTD schema.¶

2.2.6. Properties

The properties form is defined by the properties CDDL rule in Figure 1. The semantics of the properties form are described in Section 3.3.6.¶

For a schema of the properties form to be correct, properties must either be required (i.e., in properties) or optional (i.e., in optionalProperties), but not both.¶

More formally, if a schema has both a member named properties (with value P) and another member named optionalProperties (with value O), then O and P MUST NOT have any member names in common; that is, no member of P may have a name equal to the name of any member of O, under the definition of string equality given in Section 8.3 of [RFC8259].¶

Thus,¶

   {
     "properties": { "confusing": {} },
     "optionalProperties": { "confusing": {} }
   }

is not a correct JTD schema, as confusing appears in both properties and optionalProperties. By contrast,¶

   {
     "properties": {
       "users": {
         "elements": {
           "properties": {
             "id": { "type": "string" },
             "name": { "type": "string" },
             "create_time": { "type": "timestamp" }
           },
           "optionalProperties": {
             "delete_time": { "type": "timestamp" }
           }
         }
       },
       "next_page_token": { "type": "string" }
     }
   }

is a correct JTD schema of the properties form, describing a paginated list of users and demonstrating the recursive nature of the syntax of JTD schemas.¶

2.2.7. Values

The values form is defined by the values CDDL rule in Figure 1. The semantics of the values form are described in Section 3.3.7.¶

As an example of a correct JTD schema of the values form,¶

   { "values": { "type": "uint8" }}

is a correct JTD schema, whereas¶

   { "values": true }

and¶

   { "values": { "type": "foo" } }

are not correct schemas, as neither¶

   true

nor¶

   { "type": "foo" }

are correct JTD schemas, and the value of the member named values must be a correct JTD schema.¶

2.2.8. Discriminator

The discriminator form is defined by the discriminator CDDL rule in Figure 1. The semantics of the discriminator form are described in Section 3.3.8. Understanding the semantics of the discriminator form will likely aid the reader in understanding why this section provides constraints on the discriminator form beyond those in Figure 1.¶

To prevent ambiguous or unsatisfiable constraints on the discriminator property of a tagged union, an additional constraint on schemas of the discriminator form exists. For schemas of the discriminator form:¶

• Let D be the member of the schema with the name discriminator.¶
• Let M be the member of the schema with the name mapping.¶

If the schema is correct, then all member values S of M will be schemas of the "properties" form. For each S:¶

• If S has a member N whose name equals nullable, N's value MUST NOT be the JSON primitive value true.¶
• For each member P of S whose name equals properties or optionalProperties, P's value, which must be an object, MUST NOT contain any members whose name equals D's value.¶

Thus,¶

   {
     "discriminator": "event_type",
     "mapping": {
       "can_the_object_be_null_or_not?": {
         "nullable": true,
         "properties": { "foo": { "type": "string" } }}
       }
     }
   }

is an incorrect schema, as a member of mapping has a member named nullable whose value is true. This would suggest that the instance may be null. Yet, the top-level schema lacks such a nullable set to true, which would suggest that the instance in fact cannot be null. If this were a correct JTD schema, it would be unclear which piece of information takes precedence.¶

JTD handles such possible ambiguity by disallowing, at the syntactic level, the possibility of contradictory specifications of whether an instance described by a schema of the discriminator form may be null. The schemas in a discriminator mapping cannot have nullable set to true; only the discriminator itself can use nullable in this way.¶

It also follows that¶

   {
     "discriminator": "event_type",
     "mapping": {
       "is_event_type_a_string_or_a_float32?": {
         "properties": { "event_type": { "type": "float32" }}
       }
     }
   }

and¶

   {
     "discriminator": "event_type",
     "mapping": {
       "is_event_type_a_string_or_an_optional_float32?": {
         "optionalProperties": { "event_type": { "type": "float32" }}
       }
     }
   }

are incorrect schemas, as event_type is both the value of discriminator and a member name in one of the mapping member properties or optionalProperties. This is ambiguous, because ordinarily the discriminator keyword would indicate that event_type is expected to be a string, but another part of the schema specifies that event_type is expected to be a number.¶

JTD handles such possible ambiguity by disallowing, at the syntactic level, the possibility of contradictory specifications of discriminator "tags". Discriminator "tags" cannot be redefined in other parts of the schema.¶

By contrast,¶

   {
     "tag": "event_type",
     "mapping": {
       "account_deleted": {
         "properties": {
           "account_id": { "type": "string" }
         }
       },
       "account_payment_plan_changed": {
         "properties": {
           "account_id": { "type": "string" },
           "payment_plan": { "enum": ["FREE", "PAID"] }
         },
         "optionalProperties": {
           "upgraded_by": { "type": "string" }
         }
       }
     }
   }

is a correct schema, describing a pattern of data common in JSON-based messaging systems. Section 3.3.8 provides examples of what this schema accepts and rejects.¶

3.3.1. Empty

The empty form is meant to describe instances whose values are unknown, unpredictable, or otherwise unconstrained by the schema. The syntax of the empty form is described in Section 2.2.1.¶

If a schema is of the empty form, then it accepts all instances. A schema of the empty form will never produce any error indicators.¶

3.3.2. Ref

The ref form is for when a schema is defined in terms of something in the definitions of the root schema. The ref form enables schemas to be less repetitive and also enables describing recursive structures. The syntax of the ref form is described in Section 2.2.2.¶

If a schema is of the ref form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise:¶
• Let B be the root schema containing the schema or the schema itself if it is a root schema.¶
• Let D be the member of B with the name definitions. By Section 2, D exists.¶
• Let R be the value of the schema member with the name ref.¶
• Let S be the value of the member of D whose name equals R. By Section 2.2.2, S exists and is a schema.¶

The schema accepts the instance if and only if S accepts the instance. Otherwise, the error indicators to return in this case are the union of the error indicators from evaluating S against the instance.¶

For example, the schema¶

   {
     "definitions": { "a": { "type": "float32" }},
     "ref": "a"
   }

accepts¶

   123

but rejects¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/definitions/a/type" }]

The schema¶

   {
     "definitions": { "a": { "type": "float32" }},
     "ref": "a",
     "nullable": true
   }

accepts¶

   null

because the schema has a nullable member whose value is true.¶

Note that nullable being false has no effect in any of the forms described in this document. For example, the schema¶

   {
     "definitions": { "a": { "nullable": false, "type": "float32" }},
     "ref": "a",
     "nullable": true
   }

accepts¶

   null

In other words, it is not the case that putting a false value for nullable will ever override a nullable member in schemas of the ref form; it is correct, though ineffectual, to have a value of false for the nullable member in a schema.¶

3.3.3. Type

The type form is meant to describe instances whose value is a boolean, number, string, or timestamp [RFC3339]. The syntax of the type form is described in Section 2.2.3.¶

If a schema is of the type form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise:¶
• Let T be the value of the member with the name type. The following table describes whether the instance is accepted, as a function of T's value:¶

float32 and float64 are distinguished from each other in their intent. float32 indicates data intended to be processed as an IEEE 754 single-precision float, whereas float64 indicates data intended to be processed as an IEEE 754 double-precision float. Tools that generate code from JTD schemas will likely produce different code for float32 than for float64.¶

If T starts with int or uint, then the instance is accepted if and only if it is a JSON number encoding a value with zero fractional part. Depending on the value of T, this encoded number must additionally fall within a particular range:¶

Note that¶

   10

and¶

   10.0

and¶

   1.0e1

encode values with zero fractional part, whereas¶

   10.5

encodes a number with a non-zero fractional part. Thus, the schema¶

   {"type": "int8"}

accepts¶

   10

and¶

   10.0

and¶

   1.0e1

but rejects¶

   10.5

as well as¶

   false

because "false" is not a number at all.¶

If the instance is not accepted, then the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the schema member with the name type.¶

For example, the schema¶

   {"type": "boolean"}

accepts¶

   false

but rejects¶

   127

The schema¶

   {"type": "float32"}

accepts¶

   10.5

and¶

   127

but rejects¶

   false

The schema¶

   {"type": "string"}

accepts¶

   "1985-04-12T23:20:50.52Z"

and¶

   "foo"

but rejects¶

   false

The schema¶

   {"type": "timestamp"}

accepts¶

   "1985-04-12T23:20:50.52Z"

but rejects¶

   "foo"

and¶

   false

The schema¶

   {"type": "boolean", "nullable": true}

accepts¶

   null

and¶

   false

but rejects¶

   127

In all of the examples of rejected instances given in this section, the error indicator to produce is:¶

   [{ "instancePath": "", "schemaPath": "/type" }]

3.3.4. Enum

The enum form is meant to describe instances whose value must be one of a given set of string values. The syntax of the enum form is described in Section 2.2.4.¶

If a schema is of the enum form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise:¶
• Let E be the value of the schema member with the name enum. The instance is accepted if and only if it is equal to one of the elements of E.¶

If the instance is not accepted, then the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the schema member with the name enum.¶

For example, the schema¶

   { "enum": ["PENDING", "DONE", "CANCELED"] }

accepts¶

   "PENDING"

and¶

   "DONE"

and¶

   "CANCELED"

but rejects all of¶

   0

and¶

   1

and¶

   2

and¶

   "UNKNOWN"

and¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/enum" }]

The schema¶

   { "enum": ["PENDING", "DONE", "CANCELED"], "nullable": true }

accepts¶

   "PENDING"

and¶

   null

but rejects¶

   1

and¶

   "UNKNOWN"

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/enum" }]

3.3.5. Elements

The elements form is meant to describe instances that must be arrays. A further subschema describes the elements of the array. The syntax of the elements form is described in Section 2.2.5.¶

If a schema is of the elements form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise:¶

• Let S be the value of the schema member with the name elements. The instance is accepted if and only if all of the following are true:¶

  • The instance is an array. Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the schema member with the name elements.¶
  • If the instance is an array, then every element of the instance must be accepted by S. Otherwise, the error indicators for this case are the union of all the errors arising from evaluating S against elements of the instance.¶

For example, the schema¶

   {
     "elements": {
       "type": "float32"
     }
   }

accepts¶

   []

and¶

   [1, 2, 3]

but rejects¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/elements" }]

and rejects¶

   [1, 2, "foo", 3, "bar"]

with the error indicators¶

   [
     { "instancePath": "/2", "schemaPath": "/elements/type" },
     { "instancePath": "/4", "schemaPath": "/elements/type" }
   ]

The schema¶

   {
     "elements": {
       "type": "float32"
     },
     "nullable": true
   }

accepts¶

   null

and¶

   []

and¶

   [1, 2, 3]

but rejects¶

   [1, 2, "foo", 3, "bar"]

with the error indicators¶

   [
     { "instancePath": "/2", "schemaPath": "/elements/type" },
     { "instancePath": "/4", "schemaPath": "/elements/type" }
   ]

3.3.6. Properties

The properties form is meant to describe JSON objects being used as a "struct". The syntax of the properties form is described in Section 2.2.6.¶

If a schema is of the properties form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise, the instance is accepted if and only if all of the following are true:¶

• The instance is an object.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the schema member with the name properties if such a schema member exists; if such a member doesn't exist, schemaPath shall point to the schema member with the name optionalProperties.¶

• If the instance is an object, and the schema has a member named properties, then let P be the value of the schema member named properties. By Section 2.2.6, P must be an object. For every member name in P, a member of the same name in the instance must exist.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the member of P failing the requirement just described.¶

• If the instance is an object, then let P be the value of the schema member named properties (if it exists) and O be the value of the schema member named optionalProperties (if it exists).¶

  For every member I of the instance, find a member with the same name as I's in P or O. By Section 2.2.6, it is not possible for both P and O to have such a member. If the "discriminator tag exemption" is in effect on I (see Section 3.3.8), then ignore I. Otherwise:¶

  • If no such member in P or O exists and validation is not in "allow additional properties" mode (see Section 3.1), then the instance is rejected.¶

    The error indicator for this case has an instancePath pointing to I and a schemaPath pointing to the schema.¶

  • If such a member in P or O does exist, then call this member S. If S rejects I's value, then the instance is rejected.¶

    The error indicators for this case are the union of the error indicators from evaluating S against I's value.¶

An instance may have multiple errors arising from the third and fourth bullets in the list above. In this case, the error indicators are the union of the errors.¶

For example, the schema¶

   {
     "properties": {
       "a": { "type": "string" },
       "b": { "type": "string" }
     },
     "optionalProperties": {
       "c": { "type": "string" },
       "d": { "type": "string" }
     }
   }

accepts¶

   { "a": "foo", "b": "bar" }

and¶

   { "a": "foo", "b": "bar", "c": "baz" }

and¶

   { "a": "foo", "b": "bar", "c": "baz", "d": "quux" }

and¶

   { "a": "foo", "b": "bar", "d": "quux" }

but rejects¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/properties" }]

and rejects¶

   { "b": 3, "c": 3, "e": 3 }

with the error indicators¶

   [
     { "instancePath": "",
       "schemaPath": "/properties/a" },
     { "instancePath": "/b",
       "schemaPath": "/properties/b/type" },
     { "instancePath": "/c",
       "schemaPath": "/optionalProperties/c/type" },
     { "instancePath": "/e",
       "schemaPath": "" }
   ]

If instead the schema had additionalProperties: true but was otherwise the same:¶

   {
     "properties": {
       "a": { "type": "string" },
       "b": { "type": "string" }
     },
     "optionalProperties": {
       "c": { "type": "string" },
       "d": { "type": "string" }
     },
     "additionalProperties": true
   }

and the instance remained the same:¶

   { "b": 3, "c": 3, "e": 3 }

then the error indicators from evaluating the instance against the schema would be:¶

   [
     { "instancePath": "",
       "schemaPath": "/properties/a" },
     { "instancePath": "/b",
       "schemaPath": "/properties/b/type" },
     { "instancePath": "/c",
       "schemaPath": "/optionalProperties/c/type" },
   ]

These are the same errors as before, except the final error (associated with the additional member named e in the instance) is no longer present. This is because additionalProperties: true enables "allow additional properties" mode on the schema.¶

Finally, the schema¶

   {
     "nullable": true,
     "properties": {
       "a": { "type": "string" },
       "b": { "type": "string" }
     },
     "optionalProperties": {
       "c": { "type": "string" },
       "d": { "type": "string" }
     },
     "additionalProperties": true
   }

accepts¶

   null

but rejects¶

   { "b": 3, "c": 3, "e": 3 }

with the error indicators¶

   [
     { "instancePath": "",
       "schemaPath": "/properties/a" },
     { "instancePath": "/b",
       "schemaPath": "/properties/b/type" },
     { "instancePath": "/c",
       "schemaPath": "/optionalProperties/c/type" },
   ]

3.3.7. Values

The values form is meant to describe instances that are JSON objects being used as an associative array. The syntax of the values form is described in Section 2.2.7.¶

If a schema is of the values form, then:¶

• If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise:¶

• Let S be the value of the schema member with the name values. The instance is accepted if and only if all of the following are true:¶

  • The instance is an object. Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to the schema member with the name values.¶
  • If the instance is an object, then every member value of the instance must be accepted by S. Otherwise, the error indicators for this case are the union of all the error indicators arising from evaluating S against member values of the instance.¶

For example, the schema¶

   {
     "values": {
       "type": "float32"
     }
   }

accepts¶

   {}

and¶

   {"a": 1, "b": 2}

but rejects¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/values" }]

and rejects¶

   { "a": 1, "b": 2, "c": "foo", "d": 3, "e": "bar" }

with the error indicators¶

   [
     { "instancePath": "/c", "schemaPath": "/values/type" },
     { "instancePath": "/e", "schemaPath": "/values/type" }
   ]

The schema¶

   {
     "nullable": true,
     "values": {
       "type": "float32"
     }
   }

accepts¶

   null

but rejects¶

   { "a": 1, "b": 2, "c": "foo", "d": 3, "e": "bar" }

with the error indicators¶

   [
     { "instancePath": "/c", "schemaPath": "/values/type" },
     { "instancePath": "/e", "schemaPath": "/values/type" }
   ]

3.3.8. Discriminator

The discriminator form is meant to describe JSON objects being used in a fashion similar to a discriminated union construct in C-like languages. The syntax of the discriminator form is described in Section 2.2.8.¶

When a schema is of the "discriminator" form, it validates that:¶

• the instance is an object,¶
• the instance has a particular "tag" property,¶
• this "tag" property's value is a string within a set of valid values, and¶
• the instance satisfies another schema, where this other schema is chosen based on the value of the "tag" property.¶

The behavior of the discriminator form is more complex than the other keywords. Readers familiar with CDDL may find the final example in Appendix B helpful in understanding its behavior. What follows in this section is a description of the discriminator form's behavior, as well as some examples.¶

If a schema is of the "discriminator" form, then:¶

• Let D be the schema member with the name discriminator.¶
• Let M be the schema member with the name mapping.¶
• Let I be the instance member whose name equals D's value. I may, for some rejected instances, not exist.¶
• Let S be the member of M whose name equals I's value. S may, for some rejected instances, not exist.¶

If the schema has a member named nullable whose value is the boolean true, and the instance is the JSON primitive value null, then the schema accepts the instance. Otherwise, the instance is accepted if and only if all of the following are true:¶

• The instance is an object.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to D.¶

• If the instance is a JSON object, then I must exist.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to the instance and a schemaPath pointing to D.¶

• If the instance is a JSON object and I exists, I's value must be a string.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to I and a schemaPath pointing to D.¶

• If the instance is a JSON object and I exists and has a string value, then S must exist.¶

  Otherwise, the error indicator for this case shall have an instancePath pointing to I and a schemaPath pointing to M.¶

• If the instance is a JSON object, I exists, and S exists, then the instance must satisfy S's value. By Section 2, S's value must be a schema of the properties form. Apply the "discriminator tag exemption" afforded in Section 3.3.6 to I when evaluating whether the instance satisfies S's value.¶

  Otherwise, the error indicators for this case shall be error indicators from evaluating S's value against the instance, with the "discriminator tag exemption" applied to I.¶

The list items above are defined in a mutually exclusive way. For any given instance and schema, exactly one of the list items above will apply.¶

For example, the schema¶

   {
     "discriminator": "version",
     "mapping": {
       "v1": {
         "properties": {
           "a": { "type": "float32" }
         }
       },
       "v2": {
         "properties": {
           "a": { "type": "string" }
         }
       }
     }
   }

rejects¶

   null

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/discriminator" }]

(This is the case of the instance not being an object.)¶

Also rejected is¶

   {}

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/discriminator" }]

(This is the case of I not existing.)¶

Also rejected is¶

   { "version": 1 }

with the error indicator¶

   [
     {
       "instancePath": "/version",
       "schemaPath": "/discriminator"
     }
   ]

(This is the case of I existing but not having a string value.)¶

Also rejected is¶

   { "version": "v3" }

with the error indicator¶

   [
     {
       "instancePath": "/version",
       "schemaPath": "/mapping"
     }
   ]

(This is the case of I existing and having a string value but S not existing.)¶

Also rejected is¶

   { "version": "v2", "a": 3 }

with the error indicator¶

   [
     {
       "instancePath": "/a",
       "schemaPath": "/mapping/v2/properties/a/type"
     }
   ]

(This is the case of I and S existing but the instance not satisfying S's value.)¶

Finally, the schema accepts¶

   { "version": "v2", "a": "foo" }

This instance is accepted even though version is not mentioned by /mapping/v2/properties; the "discriminator tag exemption" ensures that version is not treated as an additional property when evaluating the instance against S's value.¶

By contrast, consider the same schema but with nullable being true. The schema¶

   {
     "nullable": true,
      "discriminator": "version",
      "mapping": {
        "v1": {
          "properties": {
            "a": { "type": "float32" }
          }
        },
        "v2": {
          "properties": {
            "a": { "type": "string" }
          }
        }
      }
   }

accepts¶

   null

To further illustrate the discriminator form with examples, recall the JTD schema in Section 2.2.8, reproduced here:¶

   {
     "discriminator": "event_type",
     "mapping": {
       "account_deleted": {
         "properties": {
           "account_id": { "type": "string" }
         }
       },
       "account_payment_plan_changed": {
         "properties": {
           "account_id": { "type": "string" },
           "payment_plan": { "enum": ["FREE", "PAID"] }
         },
         "optionalProperties": {
           "upgraded_by": { "type": "string" }
         }
       }
     }
   }

This schema accepts¶

   { "event_type": "account_deleted", "account_id": "abc-123" }

and¶

   {
     "event_type": "account_payment_plan_changed",
     "account_id": "abc-123",
     "payment_plan": "PAID"
   }

and¶

   {
     "event_type": "account_payment_plan_changed",
     "account_id": "abc-123",
     "payment_plan": "PAID",
     "upgraded_by": "users/mkhwarizmi"
   }

but rejects¶

   {}

with the error indicator¶

   [{ "instancePath": "", "schemaPath": "/discriminator" }]

and rejects¶

   { "event_type": "some_other_event_type" }

with the error indicator¶

   [
     {
       "instancePath": "/event_type",
       "schemaPath": "/mapping"
     }
   ]

and rejects¶

   { "event_type": "account_deleted" }

with the error indicator¶

   [{
     "instancePath": "",
     "schemaPath": "/mapping/account_deleted/properties/account_id"
   }]

and rejects¶

   {
     "event_type": "account_payment_plan_changed",
     "account_id": "abc-123",
     "payment_plan": "PAID",
     "xxx": "asdf"
   }

with the error indicator¶

   [{
     "instancePath": "/xxx",
     "schemaPath": "/mapping/account_payment_plan_changed"
   }]