Rename g4mf_id to g4mf_index

Author: aaronfranke

specification/parts/core.md

@@ -4,15 +4,17 @@
 
 This file describes the core foundational data schemas underlying the Good 4D Model Format (G4MF). These structures are used generally everywhere in G4MF files, not just in specific parts.
 
-## IDs
+All schemas that start with `g4mf_` (underscore) are the basic core foundational data schemas, while `g4mf.` (dot) built on top of these to define more complex structures. All of these are part of the core G4MF specification, but the `g4mf_` schemas described here are the core of the core.
 
-The G4MF ID schema defines an integer used to refer to other items in the G4MF file by index in an array. Which array is being referenced is defined by the context in which the ID is used. For example, a node's `"mesh"` property is defined as referring to a mesh in the G4MF file's `"meshes"` array, so the ID is an index into that array.
+## Integer Index Identifiers
 
-If defined, the ID MUST be a valid index in the array it is referencing. The ID MUST NOT be out of bounds of the target array. The ID MUST be an integer, with no fractional part; values such as `1.5` are not valid IDs. The ID of `-1` is reserved as a placeholder value when the relevant field not defined, indicating the lack of pointing to anything, and may be thought of as equivalent to a `null` or `undefined` value. If an array of IDs is defined, sensitive to what slot the ID is in, and the schema allows it, the value `-1` MAY be used as a placeholder for that slot, indicating that the slot does not point to anything. For example, in a skeleton's `"joints"` array, `-1` may be used to indicate that there is no bone controlling that joint. However, in all other cases, such as for standalone properties like `"mesh"`, negative IDs MUST NOT be written to G4MF files. Valid IDs written into standalone properties in G4MF files MUST be integers greater than or equal to `0` and less than the length of the array they are referencing.
+The G4MF Integer Index Identifier schema (`g4mf_index`), or Index for short, defines an integer used to refer to other items in the G4MF file by index in an array. Which array is being referenced is defined by the context in which the Index is used. For example, a node's `"mesh"` property is defined as referring to a mesh in the G4MF file's `"meshes"` array, so the G4MF Integer Index Identifier is an index into that array.
+
+If defined, the Index MUST be a valid index in the array it is referencing. The Index MUST NOT be out of bounds of the target array. The Index MUST be an integer, with no fractional part; values such as `1.5` are not valid indices. The Index of `-1` is reserved as a placeholder value when the relevant field not defined, indicating the lack of pointing to anything, and may be thought of as equivalent to a `null` or `undefined` value. If an array of indices is defined, sensitive to what slot the Index is in, and the schema allows it, the value `-1` MAY be used as a placeholder for that slot, indicating that the slot does not point to anything. For example, in a skeleton's `"joints"` array, `-1` may be used to indicate that there is no bone controlling that joint. However, in other cases, such as for standalone properties like `"mesh"`, negative indices MUST NOT be written to G4MF files. Valid indices written into standalone properties in G4MF files MUST be integers greater than or equal to `0` and less than the length of the array they are referencing.
 
 ## Items
 
-Items are the base schema for all JSON objects in G4MF. All G4MF schemas of type `object` inherit the G4MF Item schema, or inherit a descendant schema. This includes the root object of the G4MF file itself, which is also an item. The only G4MF schema which does not inherit from the G4MF Item schema is G4MF ID, which is not an `object`, but rather an `integer`. Similarly, all valid user-defined G4MF extensions with schemas of type `object` MUST have G4MF Item schema as a base class, inheriting from it or a descendant schema.
+The G4MF Item schema (`g4mf_item`) is the base schema for all JSON objects in G4MF. All G4MF schemas of type `object` inherit the G4MF Item schema, or inherit a descendant schema. This includes the root object of the G4MF file itself, which is also an item. The only G4MF schema which does not inherit from the G4MF Item schema is G4MF Integer Index Identifier, which is not an `object`, but rather an `integer`. Similarly, all valid user-defined G4MF extensions with schemas of type `object` MUST have G4MF Item schema as a base class, inheriting from it or a descendant schema.
 
 ### Properties
 
@@ -51,15 +53,15 @@ If defined, this MUST be unique within the G4MF file, across all items, includin
 
 The name uniqueness requirement exists for all items within a file, but does not apply for names between files. Two G4MF files may have up to two nodes with the same name between them, such as a each having a node named `"Crate"`. If a G4MF file uses another G4MF file as a model (see [G4MF Model](model/model_file_ref.md)), this means that there may be multiple nodes or other items with the same name in the overall scene hierarchy. Therefore, names are not guaranteed to be globally unique across the entire scene hierarchy, but they are guaranteed to be unique within a single G4MF file.
 
-Names in G4MF may be thought of as serving the same purpose as `"id"` values in other formats. They serve as unique identifiers for items within a file, allowing for external systems to unambiguously refer to specific items by name. However, this property is named `"name"` rather than `"id"` to avoid confusion with other schemes, such as numeric IDs, numeric indices, UUIDs, URIs, or other ways to specify identifiers. The `"name"` property is intended to be a human-readable and meaningful unique identifier, meant for display in user interfaces, referencing externally, and conveying semantic meaning about the item it names, such as G4MF nodes named after bones in a character skeleton rig (see [G4MF Characters/Avatars](mesh/character_avatar.md)). Note that within a G4MF file, items are referred to by index in a specification-defined array (see [IDs](#ids)), ensuring that internal references are compact, efficient, and always refer to the correct data type. For example, this design makes it impossible for a mesh's `"material"` property to refer to a node, mesh, texture, or any other non-material item. However, indices are likely to change across file edits; therefore, unique names provide a way for external references to refer to items in a more stable way.
+Names in G4MF may be thought of as serving the same purpose as `"id"` values in other formats. They serve as unique identifiers for items within a file, allowing for external systems to unambiguously refer to specific items by name. However, this property is named `"name"` rather than `"id"` to avoid confusion with other schemes, such as numeric IDs, numeric indices, UUIDs, URIs, or other ways to specify identifiers. The `"name"` property is intended to be a human-readable and meaningful unique identifier, meant for display in user interfaces, referencing externally, and conveying semantic meaning about the item it names, such as G4MF nodes named after bones in a character skeleton rig (see [G4MF Characters/Avatars](mesh/character_avatar.md)). Note that within a G4MF file, items are referred to by index in a specification-defined array (see [Integer Index Identifiers](#integer-index-identifiers)), ensuring that internal references are compact, efficient, and always refer to the correct data type. For example, this design makes it impossible for a mesh's `"material"` property to refer to a node, mesh, texture, or any other non-material item. However, indices are likely to change across file edits; therefore, unique names provide a way for external references to refer to items in a more stable way.
 
 All names in a G4MF file MUST NOT contain the following characters: `"`, `.`, `:`, `@`, `{`, `}`, `[`, `]`, `/`, and literal `\`. The `\` character is reserved as the JSON escape character and may be used for escaping characters, but names MUST NOT contain literal backslashes as a standalone character in the decoded string. The characters `{}[]/` are reserved for use in JSON pointer paths, and the characters `".:@` are reserved for use in runtime-determined path syntaxes and selectors across many programming languages and contexts, so these characters are forbidden in names to avoid ambiguity and potential parsing issues when names are used in these contexts.
 
 Furthermore, names MUST NOT contain any control characters, even escaped control characters, including both ASCII control characters and the extended Unicode control characters, as is already required for the entire G4MF JSON structure, except that while the G4MF JSON allows newline and tab characters, names additionally MUST NOT contain newline or tab characters. Names are RECOMMENDED to not contain spaces and not contain other punctuation characters that can be interpreted as special characters in certain contexts, however, all other characters not explicitly forbidden are allowed.
 
 ## File References
 
-When G4MF files need to reference data that could be found in an external file, such as an image file, model file, audio file, or any other file, they use a G4MF File Reference. All file references are required to define the file's MIME type, and may refer to stored data either in a buffer view or an external file URI.
+When G4MF files need to reference data that could be found in an external file, such as an image file, model file, audio file, or any other file, they use a G4MF File Reference (`g4mf_file_ref`). All file references are required to define the file's MIME type, and may refer to stored data either in a buffer view or an external file URI.
 
 The only case where a G4MF File Reference is not used for referencing external data is in [G4MF Buffers](data.md#buffers) themselves. All G4MF File References are allowed to store data in buffer views, but buffer views reference data stored in buffers, therefore it would be a circular reference. Additionally, the `"mimeType"` property is not useful for buffers, since they are by definition unstructured blobs of binary data, which only have structure defined by the buffer views and accessors using them.
 

specification/parts/model/node_model_instance.md

@@ -37,7 +37,7 @@ Each model is a [G4MF File Reference](../core.md#file-references) which points t
 
 The `"nodeAdditionalChildren"` property is an object that allows appending host nodes as children of specific nodes within the referenced model. If not defined, the model instance uses only the children defined by the source model.
 
-Each key in the `"nodeAdditionalChildren"` object is the name of a node in the source model, and the value is an array of [G4MF IDs](../core.md#ids) indices referencing nodes in the host G4MF file. These nodes are appended to the end of the children list of the corresponding node during instantiation. This property is additive only and does not replace or remove the source model's children. To replace the children entirely, use `"nodeOverrides"` to set the `"children"` array. To remove only some child nodes from the instance, set that node's override to `null` in `"nodeOverrides"`.
+Each key in the `"nodeAdditionalChildren"` object is the name of a node in the source model, and the value is an array of [G4MF Integer Index Identifiers](../core.md#integer-index-identifiers) indices referencing nodes in the host G4MF file. These nodes are appended to the end of the children list of the corresponding node during instantiation. This property is additive only and does not replace or remove the source model's children. To replace the children entirely, use `"nodeOverrides"` to set the `"children"` array. To remove only some child nodes from the instance, set that node's override to `null` in `"nodeOverrides"`.
 
 ### Node Overrides
 
@@ -66,7 +66,7 @@ When override properties are merged, the resulting combined object MUST satisfy
 
 When merging override properties, the following rules apply:
 
-- All [G4MF IDs](../core.md#ids) (indices) in override properties refer to the document-level arrays of the host G4MF file, not the referenced model file. For example, if a model contains a mesh instance node, and the model instance overrides the material to use index `0`, then that refers to the first material in the host G4MF file's `"materials"` array, not the model file's materials.
+- All [G4MF Integer Index Identifiers](../core.md#integer-index-identifiers) (indices) in override properties refer to the document-level arrays of the host G4MF file, not the referenced model file. For example, if a model contains a mesh instance node, and the model instance overrides the material to use index `0`, then that refers to the first material in the host G4MF file's `"materials"` array, not the model file's materials.
 
 - All non-null object types have their items merged recursively. This includes the overridden object itself, implying that partial overrides are valid and expected. For example, if a model contains a node with `"physics": { "motion": { "type": "dynamic" } }`, and a model instance contains an override with `"physics": { "motion": { "mass": 5.0 } }`, then the resulting node will have `"physics": { "motion": { "type": "dynamic", "mass": 5.0 } }`.
 

specification/schema/g4mf.accessor.schema.json

@@ -7,7 +7,7 @@
 	"allOf": [{ "$ref": "g4mf_item.schema.json" }],
 	"properties": {
 		"bufferView": {
-			"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 			"description": "The index of the buffer view that contains the data for this accessor. This is a reference to a buffer view in the G4MF file's document-level `bufferViews` array."
 		},
 		"componentType": {

specification/schema/g4mf.bufferView.schema.json

@@ -7,7 +7,7 @@
 	"allOf": [{ "$ref": "g4mf_item.schema.json" }],
 	"properties": {
 		"buffer": {
-			"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 			"description": "The index of the buffer that contains the data for this buffer view. This is a reference to a buffer in the G4MF file's document-level `buffers` array.",
 			"default": 0
 		},

specification/schema/g4mf.node.model_instance.schema.json

@@ -14,7 +14,7 @@
 			}
 		},
 		"model": {
-			"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 			"description": "The index of the model that this node references. This is a reference to a model in the G4MF file's models array. This property is required for a model instance."
 		},
 		"nodeAdditionalChildren": {
@@ -23,7 +23,7 @@
 			"additionalProperties": {
 				"type": "array",
 				"items": {
-					"allOf": [{ "$ref": "g4mf_id.schema.json" }]
+					"allOf": [{ "$ref": "g4mf_index.schema.json" }]
 				}
 			}
 		},

specification/schema/g4mf.node.schema.json

@@ -23,14 +23,14 @@
 			"type": "array",
 			"description": "The indices of this node's children.",
 			"items": {
-				"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+				"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 				"minimum": 1
 			},
 			"uniqueItems": true,
 			"minItems": 1
 		},
 		"light": {
-			"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 			"description": "The index of the light that this node references. This is a reference to a light in the G4MF file's lights array. If not defined, this node is not a light source."
 		},
 		"meshInstance": {

specification/schema/g4mf_file_ref.schema.json

@@ -7,7 +7,7 @@
 	"allOf": [{ "$ref": "g4mf_item.schema.json" }],
 	"properties": {
 		"bufferView": {
-			"allOf": [{ "$ref": "g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "g4mf_index.schema.json" }],
 			"description": "The index of the buffer view that contains the file data. This is a reference to a buffer view in the G4MF file's buffer views array."
 		},
 		"mimeType": {

specification/schema/g4mf_id.schema.json …cification/schema/g4mf_index.schema.jsonspecification/schema/g4mf_id.schema.json renamed to specification/schema/g4mf_index.schema.json specification/schema/g4mf_id.schema.json renamed to specification/schema/g4mf_index.schema.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://json-schema.org/draft/2020-12/schema",
-	"$id": "g4mf_id.schema.json",
-	"title": "G4MF Identifier",
+	"$id": "g4mf_index.schema.json",
+	"title": "G4MF Integer Index Identifier",
 	"description": "An integer index used to identify an object in a G4MF file. This is used to reference objects in arrays, such as nodes, meshes, materials, and textures. When defined, the index MUST be valid in the range of the array it is referencing. An index of -1 MAY be used by extensions or parsers to indicate that a field does not point to an object by default, but this MUST NOT be written to a G4MF file.",
 	"type": "integer",
 	"minimum": 0

specification/schema/mesh/deformation/g4mf.mesh.blend.shape.target.schema.json

@@ -7,11 +7,11 @@
 	"allOf": [{ "$ref": "../../g4mf_item.schema.json" }],
 	"properties": {
 		"indices": {
-			"allOf": [{ "$ref": "../../g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "../../g4mf_index.schema.json" }],
 			"description": "The index of the accessor that contains the indices for the mesh deformation blend shape morph target."
 		},
 		"offsets": {
-			"allOf": [{ "$ref": "../../g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "../../g4mf_index.schema.json" }],
 			"description": "The index of the accessor that contains the offsets or displacements for the mesh deformation blend shape morph target."
 		}
 	},

specification/schema/mesh/deformation/g4mf.mesh.skin.schema.json

@@ -14,15 +14,15 @@
 			}
 		},
 		"groups": {
-			"allOf": [{ "$ref": "../../g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "../../g4mf_index.schema.json" }],
 			"description": "The index of the accessor that contains the group indices which influence the corresponding vertices. The size must match the number of indices in `vertices` and `weights`."
 		},
 		"vertices": {
-			"allOf": [{ "$ref": "../../g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "../../g4mf_index.schema.json" }],
 			"description": "The index of the accessor that contains the indices of skinned vertices, with multiple indices for each vertex if it is influenced by multiple groups. The size must match the number of indices in `groups` and `weights`."
 		},
 		"weights": {
-			"allOf": [{ "$ref": "../../g4mf_id.schema.json" }],
+			"allOf": [{ "$ref": "../../g4mf_index.schema.json" }],
 			"description": "The index of the accessor that contains the weights for how strongly each group influences the corresponding vertex. The size must match the number of indices in `groups` and `vertices`."
 		}
 	},