extensionsUsed vs extensionsRequired in glTF

In glTF 2.0, extensions allow creators to introduce advanced features, shaders, and compression methods beyond the core specification. The critical distinction between extensionsUsed and extensionsRequired governs how a 3D runtime handles missing capabilities: extensionsUsed declares optional enhancements that a viewer can safely ignore if unsupported, whereas extensionsRequired declares mandatory features that force a viewer to terminate loading if it cannot process them.

What is extensionsUsed?

The extensionsUsed array lives at the root level of a glTF document and catalogs every extension utilized anywhere in the asset. Its primary purpose is discovery.

  • Optional Processing: It informs the engine which features are present. If the engine supports a listed extension, it activates the relevant code path.
  • Graceful Degradation: If an engine does not recognize an extension listed only in extensionsUsed, it simply ignores the extension object and renders the model using core glTF fallbacks.
  • Asset Continuity: Parsing and rendering continue without interruption, ensuring broad compatibility across diverse software.

What is extensionsRequired?

The extensionsRequired array also sits at the glTF root, containing a subset of the extensions declared in extensionsUsed. It identifies extensions that fundamentally alter the asset's data structure or essential visual output.

  • Mandatory Processing: An engine must implement every extension listed in extensionsRequired to proceed.
  • Strict Failure: If an engine encounters an unrecognized or unsupported entry in extensionsRequired, the glTF specification mandates that the loader must abort parsing immediately and fail to load the model.
  • Data Integrity: This prevents broken geometry, missing textures, or crashes from occurring when an engine tries to parse data it cannot interpret.

The Core Differences

The separation between these two arrays boils down to three primary factors:

  1. Parser Behavior on Unsupported Extensions:
    • extensionsUsed: Non-fatal. The engine skips the extension data and displays standard fallback data.
    • extensionsRequired: Fatal. The engine halts execution and rejects the asset.
  2. Nature of the Feature:
    • Purely additive visual enhancements—such as clearcoat layers (KHR_materials_clearcoat) or analytical lights (KHR_lights_punctual)—typically belong only in extensionsUsed. The model still renders meaningfully without them.
    • Structural, behavioral, or compression alterations—such as Draco geometry compression (KHR_draco_mesh_compression) or procedural instancing (EXT_mesh_gpu_instancing)—belong in extensionsRequired. A standard parser cannot extract vertex buffers or scene hierarchies without supporting these extensions.
  3. Specification Dependency:
    • Every extension listed in extensionsRequired must also be declared in extensionsUsed.
    • An extension in extensionsUsed does not need to be declared in extensionsRequired.