KhronosGroup / KhronosGroup/glTF

[glTF 2.1] Unique IDs

Open
#2,597 0 comments 0 reactions 0 assignees View on GitHub
2.1
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.