KhronosGroup / KhronosGroup/glTF
[glTF 2.1] Unique IDs
- Dominant language
- HTML
- Stars
- 7.8k
- Forks
- 1.2k
- Avg merge
- 17h 26m
- Merged PRs (30d)
- 5
Description
# Unique IDs for glTF objects
glTF 2.1 allows top-level objects (`glTFChildOfRootProperty.schema.json`) to define file-unique IDs (UIDs) with the `uid` string property.
If present, these must be unique throughout the entire file, and must not share a value with any other `uid` or `name` in the file. Unique IDs will have a restricted character set, and are recommended to contain alphanumeric characters.
## Use cases
Unique IDs may be used for externally referencing objects in glTF files in a stable and unambiguous way, such as from a game engine. Additionally, if the `name` property conforms to all of the requirements of UIDs (uniqueness and character set), then the `name` property may be used as a fallback when the requested `uid` does not exist in the file, for the use case of external referencing. This allows glTF 2.0 files to have their objects referred to externally, as well as glTF 2.1+ files generated without UIDs.
## Example
> [!NOTE]
> Examples are illustrative and not exhaustive.
```json
{
"nodes": [
{
"uid": "Crate"
}
]
}
```
If the above node is contained in `crate.gltf`, then an external referencing system could combine the file path and the UID to refer to it, with any syntax or mechanism the external referencing system chooses. Additionally, if there is a need to refer to instances of the node inside of instances of the file, an external referencing system could combine a reference to that instance of the file, with the node's UID, to find that instance of the node (and similarly for non-node objects with UIDs).
glTF 2.1 does not define a specific syntax or mechanism for external referencing. Regardless of the syntax used, the UID is required to be file-unique and unambiguous, so that the external referencing system can reliably find the correct object given the UID plus a way to reference the file or an instance of the file.
## Why this design
Changing the existing `name` property to be a unique identifier was considered. The `name` property is currently an extremely loosely defined string with no uniqueness or character set requirements. Changing it to be a unique identifier would be a breaking change and may be undesired for some use cases, so a separate `uid` property was added instead.
Using only `uid` without the `name` fallback for file-unique identification was considered, but it would result in complications for glTF 2.0 files. There may also be glTF 2.1+ files generated without UIDs, especially in applications that do not have a separate unique identifier system. Allowing `name` to be used as a fallback for external referencing allows glTF 2.0 files to have their parts externally referenced, allows glTF 2.1+ files without UIDs to have their parts externally referenced, and allows users to more easily author content that is compatible with external referencing without needing to have UIDs implemented in their content authoring pipeline.
The set of prohibited characters in UIDs will be chosen to avoid conflicts with various engines, ID systems, path syntaxes, and so on.
Contributor guide
Research direction
Start with glTFChildOfRootProperty.schema.json and the definitions for top-level objects. Review how a file-wide uid and its relationship to name would be represented, then determine the remaining specification decisions, including the restricted character set. Done means the glTF 2.1 proposal is resolved and its schema and explanatory examples consistently define the behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- computer-graphics
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100