Eve library

ISIS v2 GLTF Output Schema and Metadata Contract

Guide

Revision 1

On this page

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