OpenApi Schema Object - dereference

[char0n]

Subject of implementation is dereferencing Schema Objects defined following specification: https://json-schema.org/draft/2020-12/json-schema-core.html

Notable sections

• References to Possible Non-Schemas
• "$schema" Keyword
• "$id" Keyword
• Default vocabularies
• The JSON Schema Core Vocabulary
• Base URI, Anchors, and Dereferencing
• Defining location-independent identifiers
• Schema References
• Direct References with "$ref"
• Dynamic References with "$dynamicRef"
• Loading a referenced schema
• Dereferencing
• JSON Pointer fragments and embedded schema resources
• OAS dialect

Notable excerpts

Unrecognized schemas

If "$vocabulary" is absent, an implementation MAY determine behavior based on the meta-schema if it is recognized from the URI value of the referring schema's "$schema" keyword. This is how behavior (such as Hyper-Schema usage) has been recognized prior to the existence of vocabularies.

If the meta-schema, as referenced by the schema, is not recognized, or is missing, then the behavior is implementation-defined. If the implementation proceeds with processing the schema, it MUST assume the use of the core vocabulary. If the implementation is built for a specific purpose, then it SHOULD assume the use of all of the most relevant vocabularies for that purpose.

For example, an implementation that is a validator SHOULD assume the use of all vocabularies in this specification and the companion Validation specification.

Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1.2.1

Unrecognized schema can change semantics

While custom identifier keywords are possible, vocabulary designers should take care not to disrupt the functioning of core keywords. For example, the "$dynamicAnchor" keyword in this specification limits its URI resolution effects to the matching "$dynamicRef" keyword, leaving the behavior of "$ref" undisturbed.

Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.7.4

Ignoring $vacabularies

The "$vocabulary" keyword MUST be ignored in schema documents that are not being processed as a meta-schema. This allows validating a meta-schema M against its own meta-schema M' without requiring the validator to understand the vocabularies declared by M.

Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1.2

Possible guidance of merging properties while dereferencing

The application programmer and the schema author need to agree on the usage. For this example, let's assume that they agree that the most specific "default" value will be used, and any additional, more generic "default" values will be silently ignored. Let's also assume that they agree that all "description" text is to be used, starting with the most generic, and ending with the most specific. This requires the schema author to write descriptions that work when combined in this way.

The application can use the schema location path to determine which values are which. The values in the feature's immediate "enabled" property schema are more specific, while the values under the re-usable schema that is referenced to with "$ref" are more generic. The schema location path will show whether each value was found by crossing a "$ref" or not.

Feature A will therefore use a default value of true, while Feature B will use the generic default value of null. Feature A will only have the generic description from the "enabledToggle" schema, while Feature B will use that description, and also append its locally defined description that explains how to interpret a null value.

Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.7.7.1.1

Handling Mixed Schemas

When multiple schema resources are present in a single document, schema resources which do not define with which dialect they should be processed MUST be processed with the same dialect as the enclosing resource.

Since any schema that can be referenced can also be embedded, embedded schema resources MAY specify different processing dialects using the "$schema" values from their enclosing resource.

Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.9.3.2

Notes

We will not be downloading URL contained within $schema and asserting it's content to check if it really contains core vocabulary. Instead we'll be asserting directly on URL itself.

Plan

• OpenApi 3.1 namespace - support assigning $schema in every Schema Object
• OpenApi 3.1 namespace - support assigning $id in every Schema Object
• OpenApi 3.1 - Naive implementation of Schema dereference
• OpenApi 3.1 namespace - support $id during dereference
• OpenApi 3.1 namespace - support $schema during dereference
• OpenApi 3.1 namespace - support $anchor during dereference
• OpenApi 3.1 namespace - support $dynamicRef + $dynamicAnchor during dereference
• Maintain information about original reference during dereferencing

[char0n]

All sub-issues for this issue has been resolved. #378 will be dealt with separately if and when needed.