Add versioning info #899

sbtron · 2017-04-07T00:30:55Z

Added explanation of how we envision glTF will version with backwards and forwards compatibility in the 2.x timeframe.

https://github.com/sbtron/glTF/tree/Versioning/specification/2.0#versioning

Updated schema to allow for forwards compatibility

additionalProperties:false is removed so that future versions can add additional properties and a 2.0 loader can still validate a 2.x file using schema.
All enums now use anyOf with an additional generic type object to allow for additional enums in future versions. This also addresses Replace 'gltf_enumNames' with 'oneOf', and other schema cleanup #891
Added optional minVersion property to allow asset authors to opt out of forwards compat and require a minimum supported version (similar to extensionsRequired concept).

emackey · 2017-04-07T15:29:42Z

specification/2.0/schema/accessor.schema.json

+                    "description": "FLOAT"
+                },
+                {
+                    "type": "integer"


Why is this needed? Are there integers that are valid here, other than the ones listed above?

emackey · 2017-04-07T15:41:22Z

specification/2.0/schema/accessor.schema.json

+                    "enum": [ "MAT4" ]
+                },
+                {
+                    "type": "string"


Same comment here with string. I'm not a JSON Schema expert, but I tried actually loading this branch into VSCode's JSON validator, and having this type at the end of the enum list allows arbitrary strings (or arbitrary ints in the comment above) to validate as correct. Removing this type means it will only validate with an exact match to one of the named enum values.

For example:

"componentType": 99999, "type": "UNKNOWN"

This validates as allowed, because it matches anyOf integer and anyOf string.

There are a couple of ways these schemas will get used;

Viewers/Loaders can validate a file before trying to display it. The additional objects in anyOf allow loaders to validate a future version and continue to load it while ignoring any new elements.

Validators like in vs-code or glTF-validator may want to ensure the file is exactly 2.0 and not 2.1. Loosening up the schema will not be useful for this type of use case. If strict validations are required then these tools will need to use a stricter version of the schema that is specific to a version and doesn't do the forwards compatibility.

Do we need to consider making a "strict" version of the schema? By default the schema should be flexible because its still valid 2.0 with the forwards compat capabilities. We could do some script to create the stricter version that specifically checks for 2.0 without forwards compat.

I see. What behavior should a 2.0-capable loader take if it finds a "future" value that it doesn't understand? Will it just look for a default value in the schema?

The short answer is - it can be ignored. The long answer is - future updates will have to be designed such that new values can be ignored safely. Just pasted some examples we have been discussing below that goes into more detail.

sbtron · 2017-04-08T00:01:37Z

The working group has been discussing this. Pasting it here so everyone can read. The examples are speculations of features that could be added in future versions and are only meant to show potential approaches of adding them.

To support forwards compatibility, whenever a new feature is added the spec needs to allow for the following requirements:

Only specifying old the feature set (no new features used)
Specifying the new feature but allowing for a fallback
a. The fallback could be allowing older parsers to completely ignore the feature.
b. If the new feature is not supported then use the old feature.
Allowing authors to require that a runtime supports a new feature in order to load the asset

Requirement 1. is essentially backwards compatibility- you cannot change existing behavior in a spec update.

For requirement 2.a a glTF 2.0 parser should still be able to read a 2.1 file and completely ignore any new features.

For example say glTF 2.1 adds lighting capability by:

Adding a new light node at root
Added a new light property under the nodes property

(This is a completely made up example to show how this will work)

"lights": [
    "directional" : {
        "color": [ 1, 1, 1 ]
    },
],
"nodes": [
    {
        "children": [ ],
        "light": 0,
    }
]

A 2.0 parser can ignore any additional properties it finds whereas a 2.1 parser can correctly interpret those additional parameters.

For requirement 2.b any new features are ignored but a fall back behavior to 2.0 should exist.
For example say Draco Mesh compression is added to core glTF 2.1. To stay compatible with 2.0 clients, the compressed mesh should be provided along with the uncompressed mesh to allow for a fallback.
(Example only, not meant to be exact)

"primitives": [
    {
        "attributes": {
            "POSITION": 11,
            "NORMAL": 12,
            "TEXCOORD_0": 13
        },
        "indices": 10,
        "mode": 4,
        "draco_mesh": {
            "bufferView": 5,
            "indexCount": 1000,
            "vertexCount": 500,
            "attributes": [ "POSITION", "NORMAL", "TEXCOORD_0" ],
            "version": "0.9.1"
        }
    }
]

A 2.1 client can read and understand the “draco_mesh” element. A 2.0 client can simply ignore it and use the uncompressed geometry.

Requirement 3. will technically break forwards compatibility, but asset creators may want to choose to explicitly opt out of compatibility and require a specific version. The draco mesh compression is a good example where someone could choose to require a minimum version. For a client-server type of scenario where a JSON file points to the bin files, you can have both the compressed mesh and uncompressed mesh and a client can just download the one it understands. However, for a self contained binary glTF file scenario, you may only want to keep the compressed version since the whole point was to reduce the file size. In this scenario an author could choose to explicitly require a minimum version of 2.1. The JSON for such a file must still contain the required elements so that it validates, but it could just point to an empty geometry which will never gets used.

Requirements 2.a and 2.b are satisfied by allowing additional properties in all nodes of the JSON.
Requirement 3. is satisfied by adding a minVersion property to the asset node.

Enums provide an interesting challenge and example below show how to update them in a forwards compatible manner :
Imagine SPLINE interpolation is added in glTF 2.1 (its actually part of 2.0 but just using it as an example). Say SPLINE is added such that you can specify a fallback to Linear interpolation.
To do this in a forwards compatible way a new additionalSamplers property will need to be added under the channels node.

"samplers" : [
    {
        "input": 2,
        "interpolation": "LINEAR",
        "output": 3
    },
    {
        "input": 4,
        "interpolation": "SPLINE",
        "output": 5
    }
], "channels" : [
    {
        "additionalSamplers": [ 1 ],
        "sampler": 0,
        "target": {
            "node": 0,
            "path": "rotation"
        }
    }
]

Only a client that understands glTF 2.1 will understand the additionalsamplers property and will read the sampler which uses spline interpolation. Older samplers should simply ignore the additionalSamplers property and read the 2.0 sampler property to use linear interpolation.

lexaknyazev · 2017-04-08T12:21:32Z

@sbtron @bghgary @pjcozzi
What should asset.version string look like? There could be two approaches:

Arbitrary string, order and values to be defined manually by each subsequent update ("2.0", "2.0a", "2.2.45").
Fixed format string value ("2.0", "2.1", "2.2", etc). In this case, a simple regex could be used to retrieve major/minor integer.

Same question about asset.minVersion.

pjcozzi · 2017-04-10T12:18:41Z

@lexaknyazev following Khronos versioning, the format for version and minVersion could be "major.minor.revision"

I don't think we will have other variations other than perhaps minor and revision being optional.

pjcozzi · 2017-04-10T12:19:40Z

specification/2.0/README.md

@@ -131,6 +132,14 @@ Version 2.0 of glTF does not define compression for geometry and other rich data

 > The 3D Formats Working Group is developing partnerships to define the codec options for geometry compression.  glTF defines the node hierarchy, materials, animations, and geometry, and will reference the external compression specs.

+## Versioning
+
+Any updates made to glTF in a minor version will be backwards and forwards compatible. Backwards compatibility will ensure that any client implementation that supports loading a glTF 2.x file will also be able to load a glTF 2.0 file. Forwards compatibility will allow a client implementation that only supports glTF 2.0 to load glTF 2.x files while gracefully ignoring any new features it does not understand.


Perhaps "minor or revision version"

pjcozzi · 2017-04-10T12:22:48Z

specification/2.0/README.md

@@ -131,6 +132,14 @@ Version 2.0 of glTF does not define compression for geometry and other rich data

 > The 3D Formats Working Group is developing partnerships to define the codec options for geometry compression.  glTF defines the node hierarchy, materials, animations, and geometry, and will reference the external compression specs.

+## Versioning
+
+Any updates made to glTF in a minor version will be backwards and forwards compatible. Backwards compatibility will ensure that any client implementation that supports loading a glTF 2.x file will also be able to load a glTF 2.0 file. Forwards compatibility will allow a client implementation that only supports glTF 2.0 to load glTF 2.x files while gracefully ignoring any new features it does not understand.


Throughout this section, replace "glTF 2.0 file" with "glTF 2.0 asset", which is more consistent with the rest of the spec. (Looks like the spec itself could use a tweak or two here as well if you do a quick search).

pjcozzi · 2017-04-10T12:25:29Z

specification/2.0/README.md

@@ -176,6 +185,9 @@ Each glTF asset must have an `asset` property. In fact, it's the only required t
 }
 ```

+> **Implementation Note:** Client implementations should first check whether a `minVersion` property is specified and ensure both major and minor versions can be supported. If no `minVersion` is specified, then clients should check the `Version` property and ensure the major version is supported. Clients that load [GLB format](GLB_FORMAT.md) should also check for the `minVersion` and `Version` properties in the JSON chunk as the version specified in the GLB header only refers to the GLB container version.


Throughout, Version -> version. Property names should be camelCase.

pjcozzi · 2017-04-10T12:26:32Z

+1 from me. Just trivial comments.

lexaknyazev · 2017-04-10T12:38:16Z

@lexaknyazev following Khronos versioning, the format for version and minVersion could be "major.minor.revision"

@pjcozzi
I'd make minor part required and maybe drop revision, because I don't think that file format needs it.
We can continue refining language of 2.0 spec without changing version string.

pjcozzi · 2017-04-10T12:42:39Z

OK with me, but let's confirm on the call today about dropping revision.

Fix casing on version property.

lexaknyazev · 2017-04-10T22:32:53Z

@sbtron @bghgary
Textures and bufferView conflicts resolved, please merge if it's ready.

emackey · 2017-04-11T13:08:08Z

specification/2.0/schema/animation.sampler.schema.json

                },
                {
-                    "enum": [ "STEP" ],
-                    "description": "When interpolation is `\"STEP\"`, animated value remains constant to the value of the first point of the timeframe, until the next timeframe."
+                    "enum": [ "STEP" ]


We should make a note to restore these once wetzel is upgraded to handle them. The whole point of my lobbying for the change from non-standard to anyOf was specifically to get these descriptions per-enum-value.

For example, here.

Agreed. Descriptions are handled, but long descriptions make the generated text hard to read. Since these didn't have descriptions initially, I just put them back to the original for now.

I opened #955 for this.

bghgary and others added 6 commits April 6, 2017 16:24

Add forward compatibility support

bdd2517

More schema changes for forward compatibility

0766858

Add versioning to readme and glb format

2d8b41b

Add descriptions for material alphamode and animation interpolation

0798ae6

cleanup versioning explanation

f539416

fix tense consistency

2bb2845

emackey reviewed Apr 7, 2017

View reviewed changes

pjcozzi reviewed Apr 10, 2017

View reviewed changes

lexaknyazev added 2.0 specification labels Apr 10, 2017

sbtron and others added 4 commits April 10, 2017 11:31

Use asset instead of file.

cb4afc6

Fix casing on version property.

Add pattern to asset version and minVersion

c34037d

Add spline interpolation to animation

9c019a0

Merge branch '2.0' into Versioning

a3ef0af

Remove long enum descriptions as wetzel doesn't handle it

c7e4309

sbtron merged commit b1574e9 into KhronosGroup:2.0 Apr 11, 2017

emackey reviewed Apr 11, 2017

View reviewed changes

robertlong mentioned this pull request May 4, 2017

Support additional properties KhronosGroup/UnityGLTF#18

Closed

sbtron deleted the Versioning branch June 4, 2017 21:23

bghgary mentioned this pull request Jul 17, 2017

How to handle backwards compatibility in future glTF versions #806

Closed

bghgary mentioned this pull request Aug 8, 2017

KHR_draco_mesh_compression #874

Merged

bghgary mentioned this pull request Apr 2, 2018

EXT_property_animation extension proposal #1301

Open

javagl mentioned this pull request Apr 20, 2022

Adding a KHR_animation2 extension #2033

Closed

hybridherbst mentioned this pull request Sep 26, 2023

KHR_animation_pointer #2147

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add versioning info #899

Add versioning info #899

sbtron commented Apr 7, 2017

emackey Apr 7, 2017

emackey Apr 7, 2017

emackey Apr 7, 2017

sbtron Apr 7, 2017

emackey Apr 7, 2017

sbtron Apr 8, 2017

sbtron commented Apr 8, 2017

lexaknyazev commented Apr 8, 2017

pjcozzi commented Apr 10, 2017

pjcozzi Apr 10, 2017

pjcozzi Apr 10, 2017

pjcozzi Apr 10, 2017

pjcozzi commented Apr 10, 2017

lexaknyazev commented Apr 10, 2017

pjcozzi commented Apr 10, 2017

lexaknyazev commented Apr 10, 2017

emackey Apr 11, 2017 •

edited

Loading

bghgary Apr 11, 2017

emackey May 14, 2017

Add versioning info #899

Add versioning info #899

Conversation

sbtron commented Apr 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sbtron commented Apr 8, 2017

lexaknyazev commented Apr 8, 2017

pjcozzi commented Apr 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pjcozzi commented Apr 10, 2017

lexaknyazev commented Apr 10, 2017

pjcozzi commented Apr 10, 2017

lexaknyazev commented Apr 10, 2017

emackey Apr 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emackey Apr 11, 2017 •

edited

Loading