Reference subschemas on multiple levels, '$defs' and '#' character

[FTravaglini-crif]

address-before-bundle.txt
contact-before-bundle.txt
org-before-bundle.txt
party-before-bundle.txt

org-bundled-flat-defs.txt
org-bundled-multi-level.txt

Hello, I am developing a solution where I use local references in the schemas to simulate inheritance. I have some schemas which have remote references and I use the sourcemeta/jsonschema tool to bundle them. Is the correct structure a flat 'defs' section at root level with all subschemas at the same level, or do I need to bundle the schemas as in the 'org-bundled-multi-level' example?

I would have thought the flat structure was correct but then I encountered issues when publishing on the registry: the validation process doesn't accept the flat structure. Thinking it was a validation bug I opened a ticket, their explanation seems reasonable but I cannot find proper documentation to support it, thus wanted to try and open this discussion to have more insight.

I think the problem could be narrowed down to: is the '#' referencing the root level of the json file or does it reference the root level of the schema which it is inside of? In other words, does the '#/$defs/address' inside the party schema, when bundled inside the organization schema, reference the root level of party, which is inside the '$defs' section of organization, or does it reference the root level of the organization file?

[jviotti]

Hey @FTravaglini-crif , thanks for reaching out!

What has been said here (Apicurio/apicurio-registry#6727 (comment)) is correct. Essentially, when you have a $ref that is a relative JSON Pointer fragment-only reference, that will be resolved against the current URI base. If you have a bundled schema (a schema with multiple embedded schema resources), the base of each reference will be its own schema resource and NOT the root.

On documentation, the specification (https://json-schema.org/draft/2020-12/json-schema-core#name-base-uri-anchors-and-derefe) of course covers this, but it is a bit dense and hard to grasp the practical impacts of their definitions. The documentation for $ref also offers some better details (https://www.learnjsonschema.com/2020-12/core/ref/).

When it comes to debugging these things, what you can also try is the inspect command from this tool. For example, consider this schema from the issue you linked to:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema1",
  "$defs": {
    "schema2": {
      "$id": "schema2",
      "properties": {
        "field2-1": {
          "items": {
            "$ref": "#/$defs/schema3"
          }
        }
      }
    },
    "schema3": { 
      "$id": "schema3"
    }
  }
}

You can run inspect on it and get specific information about the references:

$ jsonschema inspect schema.json
...

(REFERENCE) ORIGIN: /$defs/schema2/properties/field2-1/items/$ref
    Type              : Static
    File Position     : 10:13
    Destination       : schema2#/$defs/schema3
    - (w/o fragment)  : schema2
    - (fragment)      : /$defs/schema3

...

There you can see that in /$defs/schema2/properties/field2-1/items/$ref, #/$defs/schema3 resolves to schema2#/$defs/schema3, and NOT to schema1#/$defs/schema3.

As a side note, we are just announcing an in-depth video course on JSON Schema that you might find useful: https://www.sourcemeta.com/courses/jsonschema-for-openapi/. We cover all of these things and more.

Hope that helps and feel free to reach out if you have any further questions!

[jviotti]

If you wanted /$defs/schema2/properties/field2-1/items/$ref to point to the root one, you can change the reference to schema1#/$defs/schema3. But overall, if your schemas make use of $id, I would very much recommend just referencing identifiers and not JSON Pointers. Then everything is a lot more clear

[jviotti]

@FTravaglini-crif Also if I may ask, how are you using the Apicurio Registry? What kind of workflows are you using it for? Asking because we are developing our own JSON Schema Registry, and any information about your use case could help us build it in the right way!