JSON schema cleanup for EXT_mesh_features

[lilleyse]

Merge #27 first

• Switched from JSON schema draft-4 to JSON schema 2020-12
• Formatted the schema files with the built-in VSCode JSON formatter
  • This makes certain sections harder to read so I'm open to reverting some of those changes
• Removed enum arrays in favor of glTF-style enums (example)
• Every object now extends glTFProperty.schema.json
• Updated the revision history in the main README
• min/max are now allowed for MATN types
• Miscellaneous fixes in the schema

TODO:

• Rename gltf.EXT_mesh_features.schema.json to glTF.EXT_mesh_features.schema.json after EXT_mesh_features: Fixes and tightening of JSON schema. #27 is merged

[javagl]

(I hope it's OK to drop two points here that might be unrelated to the PR itself, but might possibly be included here: )

• The links to the "glTF textureInfo" in the main README are pointing to
  https://github.com/CesiumGS/glTF/blob/specification/2.0/schema/textureInfo.schema.json but should point to
  https://github.com/CesiumGS/glTF/blob/main/specification/2.0/schema/textureInfo.schema.json

• Do the objects that extend the textureInfo (namely, featureIdTexture and propertyTexture) have to repeat the index and texCoord properties?

[donmccurdy]

Do the objects that extend the textureInfo (namely, featureIdTexture and propertyTexture) have to repeat the index and texCoord properties?

I'm not sure why it's there, but I'd copied this from material.normalTextureInfo.schema.json

[lilleyse]

The links to the "glTF textureInfo" in the main README are pointing to
https://github.com/CesiumGS/glTF/blob/specification/2.0/schema/textureInfo.schema.json but should point to
https://github.com/CesiumGS/glTF/blob/main/specification/2.0/schema/textureInfo.schema.json

Thanks for pointing this out, I fixed all the broken links. I forgot to update some of them when I removed the landing pages in 173fba2

[lilleyse]

Do the objects that extend the textureInfo (namely, featureIdTexture and propertyTexture) have to repeat the index and texCoord properties?

I'm not sure why it's there, but I'd copied this from material.normalTextureInfo.schema.json

Related to KhronosGroup#2062? Same applies to the empty extensions and extras objects I'm guessing.

[javagl]

The original question there was rather a syntactical one (whether that odd allOf could be replaced with ref), but according to the first answer, it should be possible to omit them now.

(It's probably not critical, and iff (or when?) we do this, it should probably be one, dedicated cleanup pass of (maybe replacing the allOfs with ref and) removing these properties as well as the extensions/extras. Even though it's not real inheritance, as people tend to insist, it's pretty close conceptually).

To have a "trace" of how I stumbled over this:

• I saw featureId.index be mentioned at https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features#specifying-feature-ids and didn't know where the index came from (EDIT: It's mentioned there for the first time, FWIW...)
• Looking at the featureIdTexture.schema.json revealed it, but without documentation
• Looking at the "inheritance" led me to (...the broken links :-D and then) the textureInfo

I considered to add hints to the linked bullet points, like

---

Each feature ID definition may include only a single source, so the following are mutually exclusive:

• featureId.attribute (for a Feature ID Attribute)
• featureId.offset and featureId.repeat (for a Feature ID Attribute)
• featureId.index (for a Feature ID Texture)

---

Or maybe even more elaborate, like

• The featureId.index that specifies the index of the texture to use, as defined in textureInfo for a featureIdTexture

But I'm afraid that at some point, this detail would rather be confusing than helpful...

[javagl]

Oh dear.
I shouldn't dive too deeply into this.
I just tried out this schema (assembled from the relevant parts of featureIdTexture, featureIdAttribute and primitive.EXT_mesh_features)

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {
    "featureIdAttribute": {
      "type": "object",
      "properties": {
        "attribute": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        },
        "repeat": {
          "type": "integer",
          "minimum": 1
        }
      },
      "oneOf": [
        {
          "required": [
            "attribute"
          ],
          "not": {
            "anyOf": [
              {
                "required": [
                  "offset"
                ]
              },
              {
                "required": [
                  "repeat"
                ]
              }
            ]
          }
        },
        {
          "not": {
            "required": [
              "attribute"
            ]
          }
        }
      ]
    },
    "featureIdTexture": {
      "type": "object",
      "properties": {
        "index": {},
        "texCoord": {},
        "propertyTable": {
          "type": "string"
        },
        "channel": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "propertyTable",
        "channel"
      ]
    }
  },
  "type": "object",
  "properties": {
    "featureIds": {
      "type": "array",
      "description": "",
      "items": {
        "oneOf": [
          {
            "$ref": "#/definitions/featureIdAttribute"
          },
          {
            "$ref": "#/definitions/featureIdTexture"
          }
        ]
      },
      "minItems": 1
    }
  }
}

And pasted it in https://www.jsonschemavalidator.net/

And this object validates against that schema:

{
  "featureIds": [
    {
      "index": 0,
      "propertyTable": 0,
      "channel": 0,
      "offset": 0,
    }
  ]
}

Specifically this part from https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features/schema/primitive.EXT_mesh_features.schema.json#L11 :

    "oneOf": [ 
        { "$ref": "#/definitions/featureIdAttribute" },
        {  "$ref": "#/definitions/featureIdTexture"   }

causes the JSON snippet to validate against both, a Feature ID Attribute and a Feature ID Texture. And at this point, it is not clear which type of object that is.

One could probably avoid this, with some trickery involving not { featureIdTextue } near https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features/schema/featureIdAttribute.schema.json#L32 (and conversely, add a not { featureIdAttribute } in featureIdTexture).
But that would probably be a pain in the back...

Not worth the effort, I guess...?

[lilleyse]

I considered to add hints to the linked bullet points, like

---

Each feature ID definition may include only a single source, so the following are mutually exclusive:

• featureId.attribute (for a Feature ID Attribute)
• featureId.offset and featureId.repeat (for a Feature ID Attribute)
• featureId.index (for a Feature ID Texture)

I think this is helpful, I pushed a commit with that change.

[lilleyse]

Not sure what to suggest for the validation issue, but maybe let's leave that for another PR?

[javagl]

Sure. The spec text already established that constraint, and modeling it via the schema itself may be difficult and cumbersome. (I'm not absolutely sure that it is possible at all, but might give it a try at some point...)

[ptrgags]

@lilleyse a couple small comments

[ptrgags]

Merged, thanks @lilleyse!