Rules of JSON Schema 2020-12 resolution

[char0n]

Hi all,

I was wondering if JSON Schema like the following is valid and would correctly resolve given JSON Schema 2020-12 spec. $ref fields in PartOfMySharedResponse are pointing to future values of SharedResponse. Thank you very much!

{
  "$defs": {
    "PartOfMySharedResponse": {
      "type": "object",
      "properties": {
        "foo": {
          "$ref": "#/$defs/SharedResponse/properties/foo"
        },
        "bar": {
          "$ref": "#/$defs/SharedResponse/properties/bar"
        }
      }
    },
    "SharedResponse": {
        "$ref": "//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties"
    }
  }
}

[Relequestual]

template is an unknown keyword, so those references are "References to Possible Non-Schemas".

https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9.4.2

Some extracts...

Multi-level structures of unknown keywords are capable of introducing
nested subschemas, which would be subject to the processing rules for
"$id". Therefore, having a reference target in such an unrecognized
structure cannot be reliably implemented, and the resulting behavior
is undefined.

Note that single-level custom keywords with identical syntax and
semantics to "$defs" do not allow for any intervening "$id" keywords,
and therefore will behave correctly under implementations that
attempt to use any reference target as a schema. However, this
behavior is implementation-specific and MUST NOT be relied upon for
interoperability.

In short, you COULD do this, and it MIGHT work, but you really probably SHOULD NOT do this, and you MUST NOT do this if you care about interoperability or reliability (an implementations support for this might change).

[char0n]

@Relequestual thanks,

I had an error in my example (I'm very sorry about that).

We have two directly embedded schemas in $defs. foo and bar of PartOfMySharedResponse are now referencing non existing fields of SharedResponse. These fields will exist eventually when SharedResponse.$ref is removed and replaced by the resolved value. I've seen people use this pattern, so that they avoid referencing external schemas with full absolute URL repeatedly. Instead they use this "shortcut" to resolve the external schema once, and then use internal pointers only. The argument is that they have to change the URL in one place, instead of changing it on 100 different places.

We must first resolve SharedResponse in order for foo and bar of PartOfMySharedResponse to resolve.

[jdesrosiers]

The short answer is no, those aren't valid reference. The short explanation is that it's because JSON Pointers aren't allowed to cross document boundaries. I'll follow up later with a better explanation.

[jdesrosiers]

Here's the full explanation.

Let's start here,

when SharedResponse.$ref is removed and replaced by the resolved value.

That's not how $ref is supposed to work. Nothing should ever be removed or replaced. Even when bundling, we only ever add. The first thing you have to remember is that $ref is now (since 2019-09) a keyword. It's not the whole object with a $ref that points to another schema, it's the value of the $ref that points to another schema. So, if you were to replace something, it would look like this.

{
  "$defs": {
    "SharedResponse": {
      "$ref": {
        "properties": {
          "foo": {},
          "bar": {}
        }
      }
    }
  }
}

It isn't valid for a $ref to have a schema instead of a URI and it isn't valid to embed a sub-schema without an $id, so this isn't a valid schema. In order make this a valid bundled schema, you'd have to do this,

{
  "$defs": {
    "SharedResponse": {
      "$ref": "//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties"
    },
    "https://example.com/shared.yaml": {
      "$id": "https://example.com/shared.yaml",
      "components": {
        "schemas": {
          "MyResponseDefinitionWithFooAndBarProperties": {
            "properties": {
              "foo": {},
              "bar": {}
            }
          }
        }
      }
    }
  }
}

So, now let's look at how the #/$defs/SharedResponse/properties/foo reference is going to resolve. It will follow the pointer fine up through /$defs/SharedResponse, but properties is not found, only $ref, so if fails. So, let's modify the pointer to take $ref into account properly, #/$defs/SharedResponse/$ref/properties/foo. Now it will get up to /$defs/SharedResponse/$ref without problem, but it would have to follow the $ref and then continue evaluating the JSON Pointer, which is not allowed. JSON Pointers can only point within the current document.

Hope that helps.

[char0n]

@jdesrosiers thanks! Looking forward for long explanation.

[karenetheridge]

also asked at OAI/OpenAPI-Specification#2739