USD Specification

Draft specification: This specification is version 1.0 and subject to change. Based on Pixar USD 23.x / OpenUSD 24.x.

The Miris USD Specification defines the standardized subset of OpenUSD accepted for rendering and streaming. Compliant files may contain geometry, materials, scene assembly, animation, and lighting. Simulation, physics, and renderer-specific extensions are not supported.

Scope

Accepted Formats

Required Metadata

Every compliant USD file must include the following stage-level metadata:

#usda 1.0
(
    metersPerUnit = 1
    upAxis = "Y"
    defaultPrim = "Root"
)

Note: Timing metadata (startTimeCode, endTimeCode, timeCodesPerSecond) is only required for animated files. See Animation.

Default Prim

Each compliant file must define a defaultPrim at the root of the scene hierarchy. All geometry, lights, and cameras must be organized under this prim. Materials are an exception — they live at the top level under a separate /Materials scope (see Materials).

Scene Structure

Note: Detailed documentation for this section is coming soon.

Composition Arcs

references, sublayers, and variants are all supported. All referenced files must also conform to this specification.

def Xform "Character" (
    prepend references = @./Character/character_geo.usd@
)

Geometry

Supported Schemas

Caution: Procedural and volumetric prims are not supported. They will be ignored or cause validation errors on import.

Materials

All materials must be defined under a /Materials scope at the top level of the file — not nested under the defaultPrim.

def Scope "Materials"
{
    def Material "Wood"
    {
        token outputs:surface.connect = </Materials/Wood/PreviewSurface.outputs:surface>

        def Shader "PreviewSurface"
        {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor.connect = </Materials/Wood/BaseColorTex.outputs:rgb>
            float inputs:roughness = 0.4
            token outputs:surface
        }

        def Shader "BaseColorTex"
        {
            uniform token info:id = "UsdUVTexture"
            asset inputs:file = @./Textures/wood_basecolor.png@
            token inputs:sourceColorSpace = "sRGB"
            float2 inputs:st.connect = </Materials/Wood/TexCoordReader.outputs:result>
            float3 outputs:rgb
        }

        def Shader "TexCoordReader"
        {
            uniform token info:id = "UsdPrimvarReader_float2"
            string inputs:varname = "st"
            float2 outputs:result
        }
    }
}

Supported Shader Types

Texture Rules

• All texture paths must be relative (e.g. @./Textures/basecolor.png@)
• Supported texture channels: BaseColor, Roughness, Metallic, Normal, Emission

Scene Assembly

Note: Detailed documentation for this section is coming soon.

Variants

Miris currently uses the default variant for each variant set.

Note: Detailed documentation for this section is coming soon.

Lighting

Compliant files must include at least one light. All lights must use UsdLux schemas.

Supported Light Types

Light Attributes

Animation

Transform Animation

def Xform "Cube"
{
    double3 xformOp:translate.timeSamples = {
        0: (0, 0, 0),
        24: (10, 0, 0)
    }
    uniform token[] xformOpOrder = ["xformOp:translate"]
}

Attribute Animation

Any numeric or color attribute may use timeSamples for animation.

Skeletal Animation

The following schemas are supported for skeletal animation:

• UsdSkelRoot
• UsdSkeleton
• UsdSkelAnimation
• UsdSkelBindingAPI — applied to skinned mesh prims to define joint weights and indices

Timing Metadata

Animated files must include the following stage-level metadata:

Supported Metadata

Unsupported Metadata

The following metadata is ignored or will cause validation errors:

• Renderer-specific settings (renderSettings:*)
• Physics data (physx:*, rigidBody:*)
• Simulation metadata

Conformance

A USD file is compliant with this specification if it:

• Defines a single root prim named in defaultPrim
• Contains only prims and attributes listed in this specification
• Uses relative paths for all asset references (textures, sublayers, references)
• Includes at least one light using a supported UsdLux schema
• Uses only supported USD schemas

Validation

Validate your file before uploading using usdchecker:

usdchecker yourfile.usd

Appendix A — Complete Example

#usda 1.0
(
    metersPerUnit = 1
    upAxis = "Y"
    defaultPrim = "Root"
)

def Xform "Root"
{
    def Mesh "Cube"
    {
        point3f[] points = [
            (0,0,0), (1,0,0), (1,1,0), (0,1,0),
            (0,0,1), (1,0,1), (1,1,1), (0,1,1)
        ]
        int[] faceVertexCounts = [4, 4, 4, 4, 4, 4]
        int[] faceVertexIndices = [
            0, 3, 2, 1,
            4, 5, 6, 7,
            0, 1, 5, 4,
            1, 2, 6, 5,
            2, 3, 7, 6,
            3, 0, 4, 7
        ]
        rel material:binding = </Materials/Gray>
    }

    def Scope "Cameras"
    {
        def Camera "MainCam"
        {
            float focalLength = 35
            float horizontalAperture = 36
            float verticalAperture = 24
            matrix4d xformOp:transform = ( (1,0,0,0), (0,1,0,0), (0,0,1,0), (0,2,5,1) )
            uniform token[] xformOpOrder = ["xformOp:transform"]
        }
    }

    def Scope "Lights"
    {
        def DistantLight "KeyLight"
        {
            color3f inputs:color = (1, 0.9, 0.8)
            float inputs:intensity = 3.0
        }
        def DomeLight "SkyLight"
        {
            asset inputs:texture:file = @./Textures/sky.exr@
            float inputs:intensity = 0.5
        }
    }
}

def Scope "Materials"
{
    def Material "Gray"
    {
        token outputs:surface.connect = </Materials/Gray/Shader.outputs:surface>
        def Shader "Shader"
        {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor = (0.5, 0.5, 0.5)
            token outputs:surface
        }
    }
}

Further Reading

This specification describes the subset of OpenUSD accepted by Miris. For the full OpenUSD specification and schema reference, see the official documentation at openusd.org:

• OpenUSD Introduction — Overview of the USD format and core concepts
• USD Glossary — Definitions for prims, schemas, composition arcs, and other USD terminology
• UsdPreviewSurface Specification — Full reference for UsdPreviewSurface, UsdUVTexture, and UsdPrimvarReader
• UsdSkel Schema — Skeletal animation schemas in detail
• UsdLux Schema — Light schema reference
• usdchecker Tool — Command-line validation tool

Updated on: 21/04/2026