# ISIS v2 GLTF Output Schema and Metadata Contract

Generated: 2026-03-06T09:25:49.115Z Checklist: `MXD-0045` (ISIS2-01235) Format:
`gltf` (model/gltf+json) Phase: Phase 4 | Milestone: M3 Launch (2026-07-27 to
2026-10-30)

## Objective

Define a canonical schema and metadata contract for glTF JSON outputs with
scene-graph coverage, external-resource signaling, deterministic manifest
metadata, and workflow provenance suitable for engine-ready mesh, rig, and scene
handoff.

## Canonical Schema

- Schema ID: `isis.v2.output.gltf.package`
- Schema Version: `1.0.0`
- Binary signature: `22 61 73 73 65 74 22`
- Required top-level fields:
  - `schemaVersion`
  - `format`
  - `assetVersion`
  - `sceneCount`
  - `nodeCount`
  - `meshCount`
  - `materialCount`
  - `textureCount`
  - `imageCount`
  - `bufferCount`
  - `animationCount`
  - `skinCount`
  - `hasEmbeddedBuffers`
  - `externalResourceCount`
  - `extensionsUsed`
  - `upAxis`
  - `artifactRole`
  - `manifest`
- Manifest fields:
  - `filename`
  - `mimeType`
  - `checksumAlgorithm`
  - `checksum`
  - `generatedAt`
  - `provenance`
- Provenance fields:
  - `assetFamilyId`
  - `workflowId`
  - `workflowVariant`
  - `promptFingerprint`
  - `seed`
  - `modelId`
  - `dependencyManifestRef`

## Supported Package Classes

| Package Class  | Storage Tier | Required Artifacts                                          |
| -------------- | ------------ | ----------------------------------------------------------- |
| `mesh-package` | WARM         | `mesh/main.{obj,fbx,gltf,glb}`, `mesh/topology-report.json` |

## Supported Output Classes

| Output Class   | Package Classes |
| -------------- | --------------- |
| `mesh_package` | `mesh-package`  |

## Applicable Asset Families

| Asset Family | Output Classes | Naming Rules |
| ------------ | -------------- | ------------ |

## Validation Invariants

- defaultSceneIndex, when provided, must resolve to a declared glTF scene.
- Animation-cache glTF outputs require at least one animation.
- Rig-source glTF outputs require at least one skin.
- Mesh-source glTF outputs require at least one mesh.
- Embedded-buffer glTF outputs require at least one buffer.
- Non-embedded glTF buffers require external resource coverage.
- glTF outputs with textures require at least one image.
- glTF extensionsUsed values must be unique.
- RegisterOutputRequest mimeType must be model/gltf+json, type must be 3d-model,
  and storage.key must end with .gltf when gltfPackage is supplied.
- glTF manifest checksum uses sha256 and must preserve workflow/dependency
  provenance linkage.

## Verification Commands

- `pnpm --filter @isis/output-registry exec vitest run src/schemas/output.schema.spec.ts`
- `node scripts/isis/validate-v2-gltf-output-schema-metadata-contract.mjs`

## Acceptance Criteria

- Output registry accepts first-class glTF package metadata with strict
  validation over scene selection, mesh and rig signaling, resource embedding
  semantics, and manifest checksum fields.
- Canonical glTF contract enumerates the package classes and output classes that
  legitimately emit glTF artifacts under the shared output taxonomy.
- glTF manifest provenance preserves workflow-variant and dependency-manifest
  linkage needed for deterministic downstream ingest of engine-ready scene
  interchange artifacts.
- Validator and schema tests catch invalid glTF registrations and enforce the
  canonical metadata surface.

## Traceability

- Checklist item: `MXD-0045`
- Ticket key: `ISIS2-01235`
- Source references:
  - `docs/domains/isis/remediation-v2/ISIS_REMEDIATION_V2_TICKETS.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_OUTPUT_PACKAGE_TAXONOMY.json`
  - `apps/isis/output-registry/src/schemas/output.schema.ts`
  - `apps/isis/output-registry/src/schemas/output.schema.spec.ts`
  - `apps/isis/output-registry/src/services/output.service.ts`
  - `apps/isis/output-registry/src/types.ts`
  - `ISIS_TODOS_2.md`
