Add note about attribute name disambiguation

[javagl]

Fixes #2111 :

As discussed in the issue and during the 3D Formats calls, the disambiguation between attribute semantic names that are defined by different extensions should happen by prefixing the attribute name with the full name of the extension, followed by a : colon.

This PR adds the corresponding information to extension development process

_Updated:

Based on the review feedback, and considering the pending task to describe the extension development process more clearly in general, I moved the part that describes the extension development into a dedicated document. Here's a direct link to new ExtensionDevelopment.md. (The part that this PR originally aimed at is the "New attributes" section).

The main extensions/README.md now only serves as an "entry point": It contains the "Extensions Registry" (i.e. the list of extensions and PRs), and links to the development description in the first paragraph.

[lexaknyazev]

texture mime types

Should be "media types"

In all Khronos (KHR) extensions, and as best practice for vendor extensions, these feature additions are designed

This sounds not quite right. We cannot say "are designed" (a fact of now that may not hold true in the future) in relation to "best practice for vendor extensions" (merely a suggestion). Please rephrase.

---

Please also add a short "Extension naming" section before "Extension mechanics" stating that an extension name consists of the uppercase prefix followed by an underscore and the feature name spelled with snake case convention (with a note that some old extensions may not follow this rule for historical reasons); also that section should state that extension names should not have special characters beyond underscore for splitting words, and in particular, they must not contain a colon symbol as it's used for disambiguating extension-defined vertex attributes.

[javagl]

That part of the text was taken from the current state, which also already contains most of the information about the extension naming at https://github.com/KhronosGroup/glTF/blob/65f4ed6b1b78d61991a9f14e25e9e817867d04bc/extensions/README.md#naming

Moving that further to the top probably makes (as well as adding the hint about the : there). And I'll try to come up with a rewording for the original text part...

[lexaknyazev]

Good catch. The current naming section should certainly be moved higher and btw all links in it are broken.

[javagl]

Rather as a note to myself: There are other broken in-document links at https://github.com/KhronosGroup/glTF/blob/65f4ed6b1b78d61991a9f14e25e9e817867d04bc/extensions/README.md#adding-additional-features-to-gltf

I'll probably do a broader cleanup here, and move that information into some dedicated 'ExtensionDevelopment.md' or so.

[javagl]

The "media types" part was updated as part of the larger refactoring, including moving the "naming" section closer to the top of th technical part and mentioning the additional constraints.

The weasel-words that related to fallback behavior have been omitted here. More specific statements are in the last paragraph of https://github.com/javagl/glTF/blob/disambiguate-extension-attribute-names/extensions/ExtensionDevelopment.md#extension-declarations (taken from the current state). Claiming that it is a "best practice" to offer some form of fallback is too broad. (It wouldn't make sense to put compressed and uncompressed data into one file "just to have a fallback"...)

[lexaknyazev]

It wouldn't make sense to put compressed and uncompressed data into one file "just to have a fallback"

Even that case may be reasonable in certain deployments. For example, a fast and large on-prem storage used with different apps.

[donmccurdy]

Just anecdotally: The idea here was good, but ... in hindsight I can't recall seeing extension fallback mechanisms used in production applications. There are enough situations that benefit from different versions of the same glTF asset (e.g. scene.mobile.glb vs scene.desktop.glb) and it is simpler to handle fallbacks for texture formats similarly.

Not suggesting we discourage fallbacks now — consistency with existing extensions is important too! — but if a hypothetical major revision of glTF happened someday, I think there would be a fair case for omitting the fallbacks. Particularly with Draco and Meshopt, the fallbacks create some wrinkles in implementation IMHO.

[javagl]

There is so much variety in the nature of the extension, the resulting possibilities for fallbacks, and the specific ways of handling fallbacks in the application that I'd say that it's always an engineering decision on the side of the extension author and the users. For example: Storing the same geometry as Draco+Uncompressed will (sometimes, but) rarely make sense. Things like the fallback from 'gaussian splats' to 'point clouds' seem to be reasonable (but eventually, clients may choose to not use that fallback).

[javagl]

I tried to address some of the points that have been brought up in the review. These are, in some sense, parts of the considerations that we've been pondering with for years now, namely, to describe the extension development process more clearly. Although I recently closed #2225 because ... ... ... eventually, nobody really cares, right? ... ... I now moved some of these points into a dedicated ExtensionDevelopment.md. This is at least "complete", so it could, in theory, be merged. I'll update the initial post here accordingly.

[javagl]

I took the libertry to mark the pure wording/formatting tweaks as "resolved".

Broader points:

I don't know some formal details about the ratification process. And for contributors, the role of the EXT prefix can be confusing. Every extension can be ratified. Everybody can propose EXT-extensions. Strictly speaking, there is not even a need for vendors to reserve their own prefix. Considerations around #2478 (comment) , about BENTLEY->EXT->KHR suggest that this can be decided rather ad-hoc, on a case-by-case basis. If there are specific details about IPs and copyright that may be added (something like the points from #2517 (comment) ), then this could be done here. (In the hope that it will not cause further confusion).

About "must -> MUST" and other wording tweaks: Part of the text had been taken from the current state of the extensions README. Others have been taken from the now-closed #2225. Other parts have been reworded or written from scratch. So it may be a bit of a Frankentext. But I wondered whether this text should try to consistently use RFC2119 style (maybe also to set an example for the 'normative language' that is mentioned as one requirement for the actual specification text). If this is intended, I can do another pass.

[lexaknyazev]

Frankentext

That's the issue. Since this document is not truly normative (yet), there's no strict need to adhere to BCP 14. That said, having two different spellings of normative terms in the same document (if not the same sentence) is quite confusing.

[weegeekps]

The EXT_primitive_voxels extension proposal relies on application-specific attribute semantics (e.g. _TEMPERATURE). I'm wondering if we should have extensions such as this to also require namespacing the attribute names?

In that case, a _TEMPERATURE semantic would instead be EXT_primitive_voxels:_TEMPERATURE with the voxel extension. We'd still include the _ to indicate that it's an application defined value, but it makes it clear that the attribute semantic is intended to be used with the voxels extension.

@javagl, @lexaknyazev, what do you think? Is this idea overkill or is it something we should consider?

[javagl]

The original issue brought up the seemingly philosophical question of what constitutes "application-specific" (which was the term used for the ones to be prefixed with "_"). It may not seem to be so philosophical after all...

What is currently suggested in this PR completely ignores that question. It only applies to extension-specific attributes, so to speak. This is crucial for being able to use two extensions in a single asset without risking name clashes, and I think that it is resolved sensibly with the prefixing here.

---

Whether there should anything be done for truly application-specific attributes has not yet been discussed. The term sounds like something that is rather "short-lived" or ~"only used internally", in some specific content processing workflow. But eventually, all this should end up in actual assets, and these assets should be as portable as possible. The example of the _TEMPERATURE attribute could also appear in EXT_structural_metadata. If someone wanted to combine voxels with metadata, this could cause a name clash. One could make a case that this is the responsibility of the author, but I'm not sure if it's that easy.

High-level thoughts (I haven't thought through all cases of the given extensions, and even less possible corner cases) :

• It could ~"hardly do any harm" to require that prefix. Even the hypothetical case where a single accessor should be used for both EXT_primitive_voxels and EXT_structural_metadata, it wouldn't be a problem to just say
  EXT_primitive_voxels:_TEMPERATURE: 123
EXT_structural_metadata:_TEMPERATURE: 123
  using the same accessor index for both (no need to duplicate actual data)
• Whether the prefix should be required might, to some extent, depend on whether the extension mentions the attribute names explicitly anywhere. When the extension contains something like
  attributesMappedToColor: [ "_TEMPERATURE", "_VELOCITY" ]
  then one could probably get away with not requiring the prefix. A mixed case would be where the extension only defines a pattern, like the name pattern of _FEATURE_ID_{n} in EXT_mesh_features ...

[weegeekps]

I think the case you mention is plausible and we should provide some guidance here for authors. I'm actually a fan of namespacing both with their own semantic and point them towards the same accessor index as demonstrated in your first bullet point. It seems like an elegant solution for preventing namespace clashes from user defined semantics in extensions that allow such behavior.

[lexaknyazev]

@javagl Is this PR ready for another review? Are there any open concerns?

[javagl]

@lexaknyazev The points from the first pass should have been addressed. The point from #2514 (comment) could either be integrated here, or tracked in its own issue/PR.

My understanding/summary of that open question is: When an extension does not specify certain attribute names, but just allows (application-specific) attributes, should these application-specific attributes also be prefixed with the extension name?

I think that this could make sense. Applications can trivially "ignore" these prefixes, but it would still be a way to make clear which extension it is that is expected to be able to do something with these attributes.

[lexaknyazev]

Application-specific attributes are already allowed by the base spec; extensions do not affect them at all. I suppose the question is

Could an application-specific attribute that starts with an underscore be also prefixed with an extension name?

Given that underscore-prefixed attributes are basically ignored by the base spec, I think the same logic could apply here, i.e., underscore-prefixed attributes may be prefixed with an extension name but they would still be ignored from the spec point of view.

[javagl]

The original issue revolved around the exact meaning of "application-specific". An attempt to describe the remaining question more precisely:

When a certain extension allows to define arbitrary vertex attributes (within the constraints of the spec), should these attribute names be prefixed with the name of the extension based on which they have been defined?

The specific example of the EXT_structural_metadata extension: It allows adding arbitrary metadata with arbitrary attribute names, e.g. a _TEMPERATURE attribute that defines the temperature of each vertex, or a _VELOCITY for some points in a point cloud. The specific attributes could be referred to as "application-specific" in some way. And maybe the underscore is enough. But I think that it could make sense to require them to be prefixed with the extension name, to provide context. Two extensions could define _ID and _TEMPERATURE, and it could make sense to make clear that the first one belongs to the EXT_example_id_extension, and the other one the EXT_structural_metadata.

[lexaknyazev]

I think there are two interpretations here:

1. An extension fully owns its scope, i.e., everything after the colon character is defined by the extension spec.
2. An extension owns its scope except for attributes that start with an underscore. Underscore-prefixed attributes may exist in any scope (global or extension) and they are never specified or constrained. The closest analogy is having something in the extra property of an extension object.

The second interpretation effectively reserves the leading underscore as a universal way of adding app-specific attributes to the base spec and to extensions and also implies that attributes used in the EXT_structural_metadata extension should not use the leading underscore if/when scoped with the extension name.

[javagl]

I think that the main reasoning behind the prefixes - namely, disambiguation - is still applicable. The EXT_structural_metadata extension could add a _TEMPERATURE attribute. Another KHR_binary_metadata extension could add a _TEMPERATURE attribute. Even when these names are not part of the extension specification itself, the reasoning for requiring a prefix would remain the same.

[lexaknyazev]

I think I strongly disagree with the "extension could add a _* attribute" part because:

• an extension cannot say anything about attributes with leading underscores that are not prepended with the extension name and a colon, e.g., an extension cannot allow/define/enable/refer to something like _TEMPERATURE at all; pre-existing extensions that do that should be seen as unfortunate quirks rather than examples to rely on.
• an extension can allow/define/enable/refer to an attribute with a leading underscore that is also prepended with the extension name and a colon, e.g., something like EXT_structural_metadata:_TEMPERATURE. However, that means that extensions fully own their corresponding namespaces and thus every extension spec has to define separately if and how it handles leading leading underscores.

That said, my preference would be to explicitly exclude attributes with leading underscores (whether prepended by extension names or not) from all specifications so they are always application-specific. This would allow adding custom attributes to all scopes without breaking anything.

An extension like EXT_structural_metadata that is intended to work with content-specific attributes should instead say that it allows any attribute names but only under its scope; that implies that such attributes don't even need leading underscores.

[javagl]

This may have been a misunderstanding. I've not been talking about a _ to be inserted between the extension name prefix and the attribute name. Specifically:

An extension like EXT_structural_metadata that is intended to work with content-specific attributes should instead say that it allows any attribute names but only under its scope;

That's exactly what I wanted to make clear. When an extension allows defining new attributes, then the names still have to be prefixed with that extension name. (Whether there's some _ after the extension name prefix or not does not matter).

I'll try to come up with some wording for that - maybe as a new sub-point/section near the "New Attributes" section, saying roughly : ~"When an extension allows defining new attributes, then the names of the attributes that are defined in the scope of this extension have to be prefixed".

The latter affects affects at least EXT_structural_metadata.

The more general point of the disambiguation affects EXT_mesh_features (an open PR).

[lexaknyazev]

the names of the attributes that are defined in the scope of this extension have to be prefixed

Sounds good. I'd suggest adding another note about underscores, specifically saying that an underscore-prefixed attribute inside the extension scope, i.e., following the EXT_name:_ATTR pattern, is still considered out-of-spec-scope and application-specific.

[javagl]

I tried to add the respective clarifications at https://github.com/javagl/glTF/blob/disambiguate-extension-attribute-names/extensions/ExtensionDevelopment.md#new-attributes

[javagl]

If there is something "fundamentally wrong" in the current state, then it could be added as a comment here.
If there is something missing or "not perfect" (specifically in the part that wasn't touched by this PR), it could be added as a comment, or tracked in a new issue.
If this PR makes things "significantly better" (at least in the sense of "more complete"), then maybe someone could approve it.