JSON-Schema v6 updates roadmap

[lexaknyazev]

JSON-Schema specification draft was recently updated to draft-06 and it's available now from IETF:
https://datatracker.ietf.org/doc/draft-wright-json-schema-validation/

Since JSON-Schema ecosystem moves towards new revision, we should update our schemas at some point.

Here're affecting changes (full v4-v6 list):

• Use $schema only in the main file (glTF.schema.json).
• Rename "uriref" to "uri-reference".
• Change usage of exclusiveMinimum.
• Use const for our "extendable enums".

All these changes are trivial and could be done as soon as our tools (wetzel, codegens) are ready for them.

CC @pjcozzi @bghgary @sbtron

[pjcozzi]

Sounds great if someone has bandwidth; otherwise, pushing post 2.0 would be OK with me as well.

[lexaknyazev]

Since JSON-Schema spec is a moving target (there never was a "final" version, I hope that it will emerge from IETF process), we shouldn't stick each glTF release to a particular JSON-Schema draft revision.

Updating schema files doesn't change their meaning so we can do it at any time.

[bghgary]

we shouldn't stick each glTF release to a particular JSON-Schema draft revision

I'm not sure I agree with this. Implementations that use the schema to verify the asset before loading them will want the schema to be stable and not change often. I agree we can change the schema without affecting the actual bits of the asset, but I think we should change it only when we can ensure we're not breaking implementations. That might mean each glTF release is tied to a specific JSON-Schema version.

[lexaknyazev]

Implementations that use the schema to verify the asset before loading them will want the schema to be stable and not change often.

I assume that underlying JSON-Schema libraries will be updated to the release version of the JSON-Schema. E.g., one of the most active node.js library for JSON-Schema processing has already dropped v4 schemas support.

[bghgary]

I assume that underlying JSON-Schema libraries will be updated to the release version of the JSON-Schema.

This probably happens faster for web than native. Maybe it's okay if the new schema doesn't change the semantic meaning of the schema (i.e. the set of assets that are allowed by old schema is the same as the new schema)? That has to be true to be backwards and forwards compatible right?

[lexaknyazev]

the set of assets that are allowed by old schema is the same as the new schema

Absolutely. Just look at four changes that affects us:

Headers

v4 language on $schema:

This keyword MUST be located at the root of a JSON Schema.

v6 language:

The "$schema" keyword SHOULD be used in a root schema. It MUST NOT appear in subschemas.

The root schema of a JSON Schema document SHOULD contain an "$id" keyword with a URI (containing a scheme).

URI Reference

v4:

{
    "uri": {
        "type": "string",
        "description": "The uri of the buffer.",
        "format": "uriref"
    }
}

v6:

{
    "uri": {
        "type": "string",
        "description": "The uri of the buffer.",
        "format": "uri-reference"
    }
}

exclusiveMinimum

v4:

{
    "znear" : {
        "type" : "number",
        "description" : "The floating-point distance to the near clipping plane.",
        "minimum" : 0.0,
        "exclusiveMinimum" : true,
    }
}

v6:

{
    "znear" : {
        "type" : "number",
        "description" : "The floating-point distance to the near clipping plane.",
        "exclusiveMinimum" : 0.0
    }
}

const (optional update, makes schema a bit more simple):

v4:

{
    "mimeType": {
        "anyOf": [
            {
                "enum": [ "image/jpeg" ]
            },
            {
                "enum": [ "image/png" ]
            },
            {
                "type": "string"
            }
        ],
        "description": "The image's MIME type."
    }
}

v6:

{
    "mimeType": {
        "anyOf": [
            {
                "const": "image/jpeg"
            },
            {
                "const": "image/png"
            },
            {
                "type": "string"
            }
        ],
        "description": "The image's MIME type."
    }
}

[bghgary]

Absolutely. Just look at four changes that affects us

That sounds good.

The only worry I have is with parsers that validate against the schema. Parsers that do this will have to make sure the JSON validation library they are using support v6 which might or might not be available yet.

I propose that we keep using v4 until 2.0 schema is very stable and then switch to v6 right after so that we effectively have both v4 and v6 in the commit history. Parsers will be free to use either v4 or v6 but should use v6 if possible.

[lexaknyazev]

I propose that we keep using v4 until 2.0 schema is very stable

Agree.

[sakrist]

I think (not sure, confusing me with many drafts too) $ref being misunderstood and been use for many things.
And also it's changing with v6
http://json-schema.org/draft-06/json-schema-migration-faq.html

[lexaknyazev]

@bghgary
Seems like Newtonsoft Json.NET Schema has full draft-06 support.

Also from http://json-schema.org/work-in-progress:

The next draft (informally known as draft-07, formal IETF draft names to be determined) is now feature-frozen and entering the final feedback month before publication. The feedback period will last from October 20th to November 20th, 2017.

[pjcozzi]

CC #1144

[lexaknyazev]

draft-07 has been released:
http://json-schema.org/latest/json-schema-core.html
http://json-schema.org/latest/json-schema-validation.html

[sbtron]

We dont think the scope to do this is significant. We will wait for json schema updates to be ratified or a new version update to gltf.

[lexaknyazev]

The repo now has schemas updated to draft/2020-12.