[lexaknyazev]

Fixes #2182.

This PR only covers the main schemas. Aligning the extension schemas to use absolute URIs for $id values (among various other tweaks) would be done as a part of #2049.

Note that $ref properties inside the main schema files do not need to be updated because $ref URIs are resolved against base URIs derived from $id URIs.

However, $ref properties that refer to something like glTFid.schema.json from extension schemas will have to be adjusted together with their $id URIs.

[javagl]

I scrolled over the changes, and it seems to insert
https://schema.khronos.org/gltf/2.0/specification/
everywhere. I have not verified that none of the changes contained a typo (but that's unlikely). I have not checked that all files are covered (but it looks like they are).

I have not yet tried out my code generator or wetzel on this state, but I think that they are both not using the id to begin with.

Whether or not this change affects other code generators is hard to say, but regardless of that, the change is "The Right Thing To Do".

[javagl]

However, $ref properties that refer to something like glTFid.schema.json from extension schemas will have to be adjusted together with their $id URIs.

Can you elabroate that? There are references like

glTF/extensions/2.0/Khronos/KHR_lights_punctual/schema/node.KHR_lights_punctual.schema.json

Line 10 in 9a15a26

"$ref": "glTFid.schema.json"

but they don't involve IDs. Where will that adjustment be necessary?

EDIT: Does this only refer to the (intended) portability, of essentially replacing this ref with the "full URL / ID"? That would make sense, but wouldn't be strictly required, I guess...

[lexaknyazev]

An URI used in $ref must be resolved to correctly identify the referenced schema. Here's how that works here.

Main spec example (heavily reduced):

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://schema.khronos.org/gltf/2.0/specification/texture.schema.json",
    "properties": {
        "sampler": { "$ref": "glTFid.schema.json" },
        "source": { "$ref": "glTFid.schema.json" }
    }
}

The $ref is resolved against the base URI of the schema, i.e., the $id. So the resolved $ref value would be https://schema.khronos.org/gltf/2.0/specification/glTFid.schema.json that matches an existing $id defined in the corresponding file.

---

Now let's look at the punctual light example (with the expected updates applied).

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://schema.khronos.org/gltf/2.0/extensions/KHR_lights_punctual/node.KHR_lights_punctual.schema.json",
...

The base URI is different here so there are two equivalent options for $ref values that refer to the main spec schemas: relative paths or absolute URIs. Both are shown below.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://schema.khronos.org/gltf/2.0/extensions/KHR_lights_punctual/node.KHR_lights_punctual.schema.json",
    "$ref": "../../specification/glTFProperty.schema.json",
    "properties": {
        "light": { "$ref": "../../specification/glTFid.schema.json" }
    }
}

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://schema.khronos.org/gltf/2.0/extensions/KHR_lights_punctual/node.KHR_lights_punctual.schema.json",
    "$ref": "https://schema.khronos.org/gltf/2.0/specification/glTFProperty.schema.json",
    "properties": {
        "light": { "$ref": "https://schema.khronos.org/gltf/2.0/specification/glTFid.schema.json" }
    }
}

[javagl]

The statement

So the resolved $ref value would be https://schema.khronos.org/gltf/2.0/specification/glTFid.schema.json that matches an existing $id defined in the corresponding file.

sounds like a strong (and somewhat surprising) constraint that doesn't appear to be derived directly from things like https://json-schema.org/draft/2020-12/json-schema-core (but it has been a while since I read the related parts of these ""specs"" the last time).

My understanding was (roughly):

• That ref must be an absolute URL, or a relative one that is then resolved against the base URI - all good
• But it is not necessary for the schema that is found there to have an id that matches that exact (resolved or absolute) URL

In any case, if these are replaced with absolute URLs, then there shouldn't be an issue: Everything is absolute (and matches the IDs).

For practical applications, using absolute URIs may be a challenge, though. Tools like wetzel may then have to dissect that absolute URI, for example, to find out that
https://schema.khronos.org/gltf/2.0/specification/glTFid.schema.json
should be resolved against
C:\glTF\specification\2.0\schema\glTFid.schema.json
They'll have to twiddle with some mapping of directories and "resolution contexts" identified by certain prefixes. (That's doable, but certainly not trivially supported right now...)

[lexaknyazev]

But it is not necessary for the schema that is found there to have an id that matches that exact (resolved or absolute) URL

From the upstream specs:

Schemas can be identified by any URI that has been given to them, including a JSON Pointer or their URI given directly by "$id". In all cases, dereferencing a "$ref" reference involves first resolving its value as a URI reference against the current base URI per RFC 3986.

So if the node.KHR_lights_punctual.schema.json schema has an absolute $id as shown above AND that schema uses $ref with a value like "../../specification/glTFid.schema.json", then the resolved $ref value is derived from those two values and it must be "https://schema.khronos.org/gltf/2.0/specification/glTFid.schema.json". Note that this resolution yields exactly the same absolute URI value as if it was used directly. On-disk paths are not used here.

Another upstream quote:

The use of URIs to identify remote schemas does not necessarily mean anything is downloaded, but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using, and the URIs that identify them.

So any tool processing glTF schemas should ignore physical locations of schema files and instead load them all at once and use those absolute $id values to map schema identifiers to their content.

This only becomes an issue for schemas without $ids because their base URIs would be implementation-defined (most likely derived from a local filesystem) and thus it would be very difficult to link them reliably. The solution is simple: all glTF schemas in this repo must define stable $id values.