Skip to content

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 / branchPresence in this objectStructural constraints
authoroptional heretype="string"
customDataoptional here$ref="#/$defs/customData"
descriptionoptional heretype="string"
expectedCatalogSha256optional heretype="string"; pattern="^[0-9a-f]{64}$"
frameTargetoptional here$ref="#/$defs/frameTarget"
idrequired$ref="#/$defs/identifier"
manifestVersionrequiredconst=5
materialsoptional here$ref="#/$defs/materials"
namerequired$ref="#/$defs/nonEmptyString"
optionsrequiredtype="array"; items=#/$defs/option
passesoptional heretype="array"; items=#/$defs/pass
programsoptional heretype="array"; items=#/$defs/program
resourcesrequiredtype="array"; items=#/$defs/resource
sceneAbiVersionrequiredconst=2
sceneCategoriesrequiredtype="array"; items=#/$defs/sceneRoute
settingsoptional here$ref="#/$defs/relativePath"
shaderRootoptional here$ref="#/$defs/relativePath"
versionrequired$ref="#/$defs/nonEmptyString"
Full structural rule: #/$defs/manifest
json
{
  "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 / branchPresence in this objectStructural constraints
authoroptional heretype="string"
descriptionoptional heretype="string"
expectedCatalogSha256optional heretype="string"; pattern="^[0-9a-f]{64}$"
fragmentsrequiredtype="array"; minItems=1; uniqueItems=true; items=#/$defs/relativePath
frameTargetoptional here$ref="#/$defs/frameTarget"
idrequired$ref="#/$defs/identifier"
manifestVersionrequiredconst=5
namerequired$ref="#/$defs/nonEmptyString"
sceneAbiVersionrequiredconst=2
settingsoptional here$ref="#/$defs/relativePath"
shaderRootoptional here$ref="#/$defs/relativePath"
sourceFormatVersionrequiredconst=1
versionrequired$ref="#/$defs/nonEmptyString"
Full structural rule: #/$defs/sourceManifest
json
{
  "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 / branchPresence in this objectStructural constraints
customDataoptional here$ref="#/$defs/customData"
materialsoptional here$ref="#/$defs/materialsFragment"
optionsoptional heretype="array"; items=#/$defs/option
passesoptional heretype="array"; items=#/$defs/pass
programsoptional heretype="array"; items=#/$defs/program
resourcesoptional heretype="array"; items=#/$defs/resource
sceneCategoriesoptional heretype="array"; items=#/$defs/sceneRoute
Full structural rule: #/$defs/fragment
json
{
  "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
json
{
  "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
json
{
  "minLength": 1,
  "type": "string"
}

nonEmptyString · v5 ​

type="string"; minLength=1

Full structural rule: #/$defs/nonEmptyString
json
{
  "minLength": 1,
  "type": "string"
}

positiveVersion · v5 ​

type="integer"; minimum=1

Full structural rule: #/$defs/positiveVersion
json
{
  "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 ·

ShaderPackManifestLoader.cs · ShaderPackManifestComposer.cs

Author documentation · Manifest v5 / Scene ABI v2