How the Khronos glTF Validator Inspects Assets

The official Khronos glTF Validator is an open-source tool designed to ensure 3D assets conform strictly to the glTF (GL Transmission Format) 2.0 specification. Written in Dart and compiled for both command-line interfaces and web environments, it recursively inspects the asset’s JSON hierarchy, binary payloads, external dependencies, and mathematical constructs. By systematically checking everything from buffer alignments to texture formats, the validator outputs categorized reports that identify syntax errors, logical inconsistencies, and non-standard practices.

1. JSON Schema and Structural Validation

The validation process begins with the structural parsing of the .gltf JSON text or the JSON chunk embedded inside a binary .glb container. The engine checks this against the core glTF 2.0 JSON schema. This stage ensures that:

  • All property names are recognized and types match their schema definitions (e.g., arrays, numbers, objects).
  • Required attributes are present (such as asset.version).
  • References to IDs, indices, and extensions are well-formed and do not reference non-existent elements.
  • Any declared glTF extensions are listed under extensionsUsed or extensionsRequired.

2. Binary Chunk and Buffer Layout Inspection

For .glb containers, the validator checks the header (magic number 0x46546C67, version, and file length) and evaluates the chunk boundaries. Once the binary chunks or external .bin files are read, the validator inspects the buffer memory layout:

  • Byte Offsets and Alignments: Ensures that offsets for bufferView and accessor elements align strictly to component size boundaries (e.g., 4-byte boundaries for 32-bit floats and integers).
  • Buffer Bounds: Confirms that no buffer view or accessor references memory beyond the total length of the assigned buffer.
  • Byte Stride: Validates that interleaved vertex attributes adhere to the allowed multiples of 4 and do not exceed the 252-byte limit.

3. Accessor and Data Integrity Checks

The validator decodes the binary arrays via accessor definitions to verify semantic and numerical correctness:

  • Bounding Boxes (min and max): Accessors must declare accurate minimum and maximum values for their components. The validator recalculates these values directly from the binary data and flags discrepancies.
  • Component Types: Validates that attributes use appropriate data types (e.g., indices must be unsigned bytes, unsigned shorts, or unsigned integers; weights must be normalized floats or unsigned integers).
  • Sparse Accessors: Ensures that sparse accessor indices are sorted, within range, and correctly override the base buffer data.

4. Geometry and Mesh Topology

Mesh validation focuses on the integrity of primitives, indices, and vertex attributes:

  • Index Range: Verifies that index values do not reference vertex indices outside the valid range defined by the primitive's vertex attributes.
  • Attribute Requirements: Checks that primitives provide necessary companion data. For example, if normal maps are used, the mesh must supply valid tangents, or if skinning is enabled, both JOINTS_0 and WEIGHTS_0 must be present.
  • Degenerate Geometry: Identifies issues such as zero-area triangles, duplicate vertex positions, or unnormalized normals.

5. Node Hierarchy and Scene Graph

The validator reconstructs the scene graph to prevent structural rendering bugs:

  • Acyclic Structure: Ensures the node hierarchy contains no circular references or parent-child loops.
  • Transformations: Confirms that nodes define transformations using either a valid 4x4 matrix or separate Translation, Rotation, and Scale (TRS) properties, but not both. Rotation quaternions are verified for unit-length normalization.
  • Skins and Skeletons: Validates that joint node hierarchies match inverse bind matrices and that referenced joint indices exist within the node tree.

6. Animations and Morph Targets

Animation tracks and morph targets undergo chronological and interpolation checks:

  • Time Keys: Checks that animation input accessors have strictly increasing, non-negative floating-point values.
  • Interpolation Compatibility: Verifies that output accessor component counts match the selected interpolation method (LINEAR, STEP, or CUBICSPLINE).
  • Morph Weights: Ensures that target counts match the weights defined in meshes and nodes.

7. Material and Texture Conformance

The validator checks PBR (Physically Based Rendering) parameters and associated image assets:

  • Color and Texture Coordinates: Checks that texture coordinate sets (e.g., TEXCOORD_0, TEXCOORD_1) referenced by materials exist in the corresponding mesh primitives.
  • Image Formats: Verifies that embedded or external images adhere to standard formats (PNG, JPEG) or valid extension formats (such as KTX2 via KHR_texture_basisu), and that image dimensions meet format requirements.

Reporting System

Upon completing the inspection, the validator issues a detailed report with issues grouped into four severity tiers:

  • Errors: Severe violations of the glTF specification that will prevent the asset from rendering reliably.
  • Warnings: Issues that do not strictly break the specification but represent bad practices, optimization issues, or potential visual defects.
  • Information: Notable characteristics of the asset, such as active extensions or generator metadata.
  • Hints: Optimization suggestions, such as removing unused accessors or consolidating duplicate material definitions.