Manifest roots and composition
Behavior and constraints
A single-file root supplies id, name, version, optional author/description and options/resources/programs/passes. The namespaced id is an author identity, the directory names an external source selection and version is author text; these are different domains. shaderRoot defaults to shaders. Files and includes freeze within their source owner. settings is a pack-relative JSON path resolved separately from shaderRoot.
A composition root declares both sourceFormatVersion=1 and an explicit fragments array. Metadata, settings, frameTarget, sceneAbiVersion and expectedCatalogSha256 belong to the root. Definition arrays and sceneCategories belong to fragments; v5 also permits materials/customData. materialsFragment requires abiVersion, while the composed materials object still needs its complete fallback/definitions contract. Fragments cannot recursively include fragments. The older v3-only composition guide is not the v5 field whitelist.
Reject absolute paths, drive names, empty/dot/parent segments, self-inclusion, normalized duplicates, directories and links escaping the pack. Preserve fragment order and each definition array's local order. Resolve references after composition, including forward references; duplicate IDs are errors rather than replacements. Any file failure rejects the whole candidate. Diagnostics retain authored filenames and local pointers.
The Loader permits comments and trailing commas but rejects duplicate keys, unknown fields and invalid combinations. Editor Schema validation cannot replace it. The canonical manifest hash excludes physical filenames, fragment boundaries, whitespace and comments while retaining logical declarations and array order. ZIP, source inventory, UI, generation and driver hashes identify other domains. expectedCatalogSha256 checks Catalog identity; it does not approve a release.
v4/v5 use explicit Scene ABI versions and routes for ownership. Compatibility documents v3's legacy behavior separately.
Generated v5 structure
Required applies to the displayed object/branch. Absence of a Schema default does not establish a runtime default. Conditional rules remain in the complete definition below; Loader validation also resolves IDs, ownership, budgets and device limits.
manifest · v5
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
author | optional here | type="string" |
customData | optional here | $ref="#/$defs/customData" |
description | optional here | type="string" |
expectedCatalogSha256 | optional here | type="string"; pattern="^[0-9a-f]{64}$" |
frameTarget | optional here | $ref="#/$defs/frameTarget" |
id | required | $ref="#/$defs/identifier" |
manifestVersion | required | const=5 |
materials | optional here | $ref="#/$defs/materials" |
name | required | $ref="#/$defs/nonEmptyString" |
options | required | type="array"; items=#/$defs/option |
passes | optional here | type="array"; items=#/$defs/pass |
programs | optional here | type="array"; items=#/$defs/program |
resources | required | type="array"; items=#/$defs/resource |
sceneAbiVersion | required | const=2 |
sceneCategories | required | type="array"; items=#/$defs/sceneRoute |
settings | optional here | $ref="#/$defs/relativePath" |
shaderRoot | optional here | $ref="#/$defs/relativePath" |
version | required | $ref="#/$defs/nonEmptyString" |
Full structural rule: #/$defs/manifest
{
"additionalProperties": false,
"properties": {
"author": {
"type": "string"
},
"customData": {
"$ref": "#/$defs/customData"
},
"description": {
"type": "string"
},
"expectedCatalogSha256": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"frameTarget": {
"$ref": "#/$defs/frameTarget"
},
"id": {
"$ref": "#/$defs/identifier"
},
"manifestVersion": {
"const": 5
},
"materials": {
"$ref": "#/$defs/materials"
},
"name": {
"$ref": "#/$defs/nonEmptyString"
},
"options": {
"items": {
"$ref": "#/$defs/option"
},
"type": "array"
},
"passes": {
"items": {
"$ref": "#/$defs/pass"
},
"type": "array"
},
"programs": {
"items": {
"$ref": "#/$defs/program"
},
"type": "array"
},
"resources": {
"items": {
"$ref": "#/$defs/resource"
},
"type": "array"
},
"sceneAbiVersion": {
"const": 2
},
"sceneCategories": {
"items": {
"$ref": "#/$defs/sceneRoute"
},
"type": "array"
},
"settings": {
"$ref": "#/$defs/relativePath"
},
"shaderRoot": {
"$ref": "#/$defs/relativePath"
},
"version": {
"$ref": "#/$defs/nonEmptyString"
}
},
"required": [
"manifestVersion",
"id",
"name",
"version",
"options",
"resources",
"sceneAbiVersion",
"sceneCategories"
],
"type": "object"
}sourceManifest · v5
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
author | optional here | type="string" |
description | optional here | type="string" |
expectedCatalogSha256 | optional here | type="string"; pattern="^[0-9a-f]{64}$" |
fragments | required | type="array"; minItems=1; uniqueItems=true; items=#/$defs/relativePath |
frameTarget | optional here | $ref="#/$defs/frameTarget" |
id | required | $ref="#/$defs/identifier" |
manifestVersion | required | const=5 |
name | required | $ref="#/$defs/nonEmptyString" |
sceneAbiVersion | required | const=2 |
settings | optional here | $ref="#/$defs/relativePath" |
shaderRoot | optional here | $ref="#/$defs/relativePath" |
sourceFormatVersion | required | const=1 |
version | required | $ref="#/$defs/nonEmptyString" |
Full structural rule: #/$defs/sourceManifest
{
"additionalProperties": false,
"properties": {
"author": {
"type": "string"
},
"description": {
"type": "string"
},
"expectedCatalogSha256": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"fragments": {
"items": {
"$ref": "#/$defs/relativePath"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"frameTarget": {
"$ref": "#/$defs/frameTarget"
},
"id": {
"$ref": "#/$defs/identifier"
},
"manifestVersion": {
"const": 5
},
"name": {
"$ref": "#/$defs/nonEmptyString"
},
"sceneAbiVersion": {
"const": 2
},
"settings": {
"$ref": "#/$defs/relativePath"
},
"shaderRoot": {
"$ref": "#/$defs/relativePath"
},
"sourceFormatVersion": {
"const": 1
},
"version": {
"$ref": "#/$defs/nonEmptyString"
}
},
"required": [
"sourceFormatVersion",
"manifestVersion",
"id",
"name",
"version",
"fragments",
"sceneAbiVersion"
],
"type": "object"
}fragment · v5
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
customData | optional here | $ref="#/$defs/customData" |
materials | optional here | $ref="#/$defs/materialsFragment" |
options | optional here | type="array"; items=#/$defs/option |
passes | optional here | type="array"; items=#/$defs/pass |
programs | optional here | type="array"; items=#/$defs/program |
resources | optional here | type="array"; items=#/$defs/resource |
sceneCategories | optional here | type="array"; items=#/$defs/sceneRoute |
Full structural rule: #/$defs/fragment
{
"additionalProperties": false,
"properties": {
"customData": {
"$ref": "#/$defs/customData"
},
"materials": {
"$ref": "#/$defs/materialsFragment"
},
"options": {
"items": {
"$ref": "#/$defs/option"
},
"type": "array"
},
"passes": {
"items": {
"$ref": "#/$defs/pass"
},
"type": "array"
},
"programs": {
"items": {
"$ref": "#/$defs/program"
},
"type": "array"
},
"resources": {
"items": {
"$ref": "#/$defs/resource"
},
"type": "array"
},
"sceneCategories": {
"items": {
"$ref": "#/$defs/sceneRoute"
},
"type": "array"
}
},
"type": "object"
}identifier · v5
type="string"; pattern="^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$"
Full structural rule: #/$defs/identifier
{
"pattern": "^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$",
"type": "string"
}relativePath · v5
type="string"; minLength=1
Full structural rule: #/$defs/relativePath
{
"minLength": 1,
"type": "string"
}nonEmptyString · v5
type="string"; minLength=1
Full structural rule: #/$defs/nonEmptyString
{
"minLength": 1,
"type": "string"
}positiveVersion · v5
type="integer"; minimum=1
Full structural rule: #/$defs/positiveVersion
{
"minimum": 1,
"type": "integer"
}Complete examples
Sources and machine records
Coverage inventory · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·