Un-deprecation of 3DTILES_content_gltf results in 'extensionsUsed', but not found warning

[bjornblissing]

The 3DTILES_content_gltf extension have been un-deprecated in 3D Tiles 1.1, per: CesiumGS/3d-tiles#810

According to my interpretation this would make the following tileset valid.

{
  "asset" : {
    "version" : "1.1"
  },
  "extensionsUsed": [
    "3DTILES_content_gltf"
  ],
  "geometricError" : 2.0,
  "root" : {
    "refine": "REPLACE",
    "boundingVolume" : {
      "box" : [ 0.5, 0.5, 0.5, 0.5, 0.0, 0.0, 0.0, 0.5, 0.0, 0.0, 0.0, 0.5 ]
    },
    "geometricError" : 1.0,
    "content": {
      "uri": "tiles/glTF/Triangle/Triangle.gltf"
    }
  }
}

However, it currently results in the following output:

Validation result:

{
  "date": "2025-09-01T06:56:36.129Z",
  "numErrors": 0,
  "numWarnings": 1,
  "numInfos": 0,
  "issues": [
    {
      "type": "EXTENSION_USED_BUT_NOT_FOUND",
      "path": "/extensionsUsed",
      "message": "The extension '3DTILES_content_gltf' was declared in 'extensionsUsed', but not found",
      "severity": "WARNING"
    }
  ]
}

One could argue that this tileset definition would be redundant in 3D Tiles 1.1 since glTF content is part of the core behavior and no glTF extensions are specified. However, I see nothing in the current spec if the 3DTILES_content_gltf which states that this is formally incorrect.

[bjornblissing]

In the pull request: #336

The following statement can be found for 1.1:

When it is declared as extensionUsed, but no extension object is found, then a warning will be emitted

I understand the rationale for this paragraph, but this requirement is not stated in the extension description.

[javagl]

However, I see nothing in the current spec if the 3DTILES_content_gltf which states that this is formally incorrect.

It is not "incorrect" (which means: It does not cause an ERROR). And there is no specific mention of what causes the WARNING here, because this WARNING is just a generic warning that would be emitted for every extension that is listed in extensionsUsed, but not found in the tileset.

I think the key point of the confusion (and what causes a few quirks for the validation) is that this extension serves two rather "distinct" purposes:

• Allowing a new content type (only applicable to 1.0)
• Allowing to list the glTF extensions (applicable to 1.0 and 1.1)

It could probably make sense to clarify or elaborate the 3DTILES_content_gltf main README.md in this regard. It currently says

For a 3D Tiles 1.1 tileset, this extension is optional, meaning that it can be placed in the extensionsUsed list of the tileset JSON.

Maybe this should be written roughly like this:

For a 3D Tiles 1.1 tileset, this extension is optional. It is not necessary to declare this extension in extensionsUsed when the tileset (~only?) refers to glTF content. (~But?) it is (~only?) necessary to declare the extension in extensionsUsed when there is an actual 3DTILES_content_gltf extension object contained in the tileset.

I'll nitpick about the exact wording (the ~(....?) parts) to make it unambiguous. But do you think that something like this could clarify it?

[bjornblissing]

Questions that need to be addressed:
Should it be optional or mandatory to add the 3DTILES_content_gltf when the any of the glTF content have extensions specified in their extensionsUsed section? Should it be optional or mandatory to provide a list of glTF extensions used?

So the output from the validator would depend on the linked glTF content.

tileset.json	glTF content with extensions	glTF content without extensions
no 3DTILES_content_gltf extension	ERROR/WARNING?	OK
3DTILES_content_gltf only	ERROR/WARNING?	OK
3DTILES_content_gltf with glTF-extension list	OK	WARNING

(Above table refer to 3D Tiles 1.1 tilesets only)

[javagl]

On the one hand, the extension description is pretty clear in that regard:

If the glTF asset uses or requires certain glTF extensions, then these extensions must also be listed in the 3DTILES_content_gltf object.

So the validator should indeed create an ERROR in the ERROR/WARNING? cases from your table.

But ...

(and that's a huge 'but') this has be be releaxed or clarified. You can use a glTF with an extension in 3D Tiles 1.1, and this does not require anything to be declared. So strictly speaking, this statement currently turns tilesets that are valid based on the core specification into invalid ones! An extension can simply not do this.

What it could or should say: If and only if the extension object is present, then it MUST list the extensions that are actually used/required by the glTFs.

Translated to the table, this would mean:

tileset.json	glTF content with extensions	glTF content without extensions
no 3DTILES_content_gltf extension	OK (must be, as of core spec)	OK (trivially)
3DTILES_content_gltf only	ERROR	EDIT: WARNING
3DTILES_content_gltf with glTF-extension list	OK (if complete)	WARNING

The (if complete) refers to the validity of the extension object itself: Right now, the validator is not checking that the glTF extensions that are listed in the extension object properly reflect the extensions that are actually used/required by the glTFs.

It could (and should) do this: During the validation of the glTFs, it can inspect the glTFs and collect their extensionsUsed/extensionsRequired in some allGltfExtensionsUsed/Required (Set<string>), and finally check if the 3DTILES_content_gltf declaration matches these sets.

I'll have to check a few details here: Where exactly should these sets be stored? It first has to check all contents, and then (finally) the extension object. And there are some options for omitting the content validation (e.g. flags like the validateContentData:boolean or the included/excluded content types). When the validator was asked to not validate the content data, then it cannot collect these sets. It could probably emit some
"INFO: The content data validation was disabled. The 3DTILES_content_gltf declarations are not be validated"
in this case.

[bjornblissing]

Yes, this makes sense. Thus the table will be coherent between versions.

tileset.json	glTF content with extensions	glTF content without extensions
3D Tiles 1.0 - no 3DTILES_content_gltf extension	ERROR	ERROR
3D Tiles 1.1 - no 3DTILES_content_gltf extension	OK (must be, as of core spec)	OK (trivially)
3D Tiles 1.0 & 1.1 - 3DTILES_content_gltf only	ERROR	WARNING
3D Tiles 1.0 & 1.1 - 3DTILES_content_gltf with glTF-extension list	OK (if complete)	WARNING

[javagl]

Unless you disagree, I'll probably add a table like this in the 3DTILES_content_gltf specification text (along with some of the clarifications above).

Technically, the validation of the "(if complete)" part may require some thought. There may be some overlap (conceptually, and in the affected code paths) with the pending #348 - I'll try to keep this in mind, and maybe draft a PR on top of that to see where/how the "(if complete)" part could be integrated.

[javagl]

@bjornblissing I opened a PR for a clarification of 3DTILES_content_gltf at CesiumGS/3d-tiles#824

I decided to not integrate the table, but instead, tried to clarify the existing text accordingly. This involves elaborating the requirements for declaring the extension in extensionsUsed and extensionsRequired. One important part of what is reflected by the table is now referring to the actual extension object, and the statement
"When it is defined, then it must list all extensions that are used or required by any glTF content that the tileset refers to,..."

Maybe you want to have a look and share your thoughts.