]> Microsoft Corporation

clemensv@microsoft.com

Web and Internet Transport Building Blocks for HTTP APIs Internet-Draft This document specifies JSON Structure Conditional Composition, an extension to JSON Structure Core that introduces composition constructs for combining multiple schema definitions. In particular, this specification defines the semantics, syntax, and constraints for the keywords allOf, anyOf, oneOf, and not, as well as the if/then/else conditional construct. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction This document specifies JSON Structure Conditional Composition, an extension to JSON Structure Core that introduces conditional composition constructs for combining multiple schema definitions. In particular, this specification defines the semantics, syntax, and constraints for the keywords allOf, anyOf, oneOf, and not, as well as the if/then/else conditional construct.

Terminology and Conventions The key words MUST, MUST NOT, SHALL, SHALL NOT, REQUIRED, SHOULD, and OPTIONAL are to be interpreted as described in and . Unless otherwise specified, all references to "non-schema" refer to a JSON Structure Core non-schema object, which is an inert JSON object that does not declare a type constraint.

Composition and Evaluation Model The keywords introduced in this document extend the set of keywords allowed for non-schemas and schemas as defined in JSON Structure Core. In particular, the keywords defined herein MAY extend all non-schema and schema definitions. The focus of JSON Structure Core is on data definitions. The conditional composition keywords introduced in this document allow authors to define conditional matching rules that use these fundamental data definitions. A schema document using these keywords is not a data definition; rather, it is a rule set for evaluating JSON node instances against schema definitions and for laying the groundwork for validation. Fundamentally, evaluating a JSON node against a schema involves matching the node against the schema's constraints. The outcome of evaluating a JSON node against a schema is ultimately a boolean value that states whether the node met all constraints defined in the schema. The evaluation also creates an understanding of which constraint was met for each subschema during evaluation. A schema evaluation engine traverses the given JSON node and the schema definition, evaluating the node and the schema recursively. When a conditional composition keyword is encountered, the engine evaluates each subschema independently against the current node and then combines the results as specified by the composition keyword.

Conditional Composition Keywords This section defines several composition keywords that combine schema definitions with evaluation rules. Each keyword has a specific evaluation semantics that determines the outcome of the validation process.

allOf The value of the allOf keyword MUST be a type-union array containing at least one schema object. A JSON node is valid against allOf if and only if it is valid against every schema in the array. Consider the following non-schema, which does not define its own type but rather contains an allOf keyword with three subschemas: Here, a JSON node evaluates to true if it is an object with at least three properties a, b, and c, where a is a string, b is a number, and c is a boolean: The JSON node satisfies all constraints defined by all subschemas. Conflicting constraints among subschemas result in an unsatisfiable schema—for example, if two subschemas require the same property to have different types or if one of the subschemas has additionalProperties set to false.

anyOf The value of the anyOf keyword MUST be a type-union array containing at least one schema object. A JSON node is valid against anyOf if and only if it is valid against at least one of the schemas in the array. Consider the following schema: Here, a JSON node evaluates to true if it is an object with at least one of the properties a, b, or c, where a is a string, b is a number, and c is a boolean: or Both JSON nodes satisfy the constraints defined by at least one subschema.

oneOf The value of the oneOf keyword MUST be a type-union array containing at least one schema object. A JSON node is valid against oneOf if and only if it is valid against exactly one of the schemas in the array. Consider the following schema: Here, a JSON node evaluates to true if it is an object with exactly one of the properties a, b, or c, where a is a string, b is a number, and c is a boolean: The following JSON node evaluates to false because it matches two subschemas:

not The value of the keyword not is a single schema object, which MAY be a type union. A JSON node is valid against not if it is not valid against the schema. For example, the schema is written as follows: Here, a JSON node evaluates to true if it is not a string:

if/then/else The values of the keywords if, then, and else are schema objects. If the processed JSON node is valid against the if schema, the then schema further constrains the JSON node and MUST match the input. If the processed JSON node is not valid against the if schema, the else schema further constrains the JSON node and MUST match the input. Consider the following schema: Here, a JSON node evaluates to true if it is an object with a property a that is a string; then it must also have a property b that is a number: Otherwise, if the JSON node does not have a property a that is a string, it must have a property c that is a boolean: or

Enabling the Extensions The conditional composition extensions can be enabled in a schema or meta-schema by adding the JSONSchemaConditionalComposition key to the $uses clause when referencing the extended meta-schema: Conditional composition is enabled by default in the validation meta-schema:

Security Considerations

• The use of composition keywords does not alter the security model of JSON Structure Core; however, excessive nesting or overly complex compositions may impact performance and resource usage.
• Implementations MUST ensure that all subschema references resolve within the same document or trusted sources to prevent external schema injection.

IANA Considerations This document does not require any IANA actions.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. n.d.

Changes from draft-vasters-json-structure-cond-composition-01

• Aligned introduction terminology with document title ("Conditional Composition" instead of "Conditionals").
• Improved awkward sentence structure in the introduction.
• Removed unused/obsolete RFC 4646 from normative references.

Changes from draft-vasters-json-structure-cond-composition-00

• No changes; date update only.

Acknowledgments TODO acknowledge.