Book of USD

Universal Scene Description (USD) is a novel way of defining and working with 3D-Scene data, developed by Pixar Animation Studios.

This book aims to be a companion document for the official documentation

Most images in this book are using the Animal Logic ALab USD Scene.

Motivation

Universal Scene Description (USD) is already making big waves in the VFX/Film and Games industries, with large players such as NVidia, Apple and Autodesk jumping on the technology. But as a newcomer; it can be an incredibly daunting and frustrating journey to venture into.

This book’s driving motivation is to offer a succinct, beginner-friendly and structured way of introducing USD, its concepts and terminology. At the moment this book focusses predominantly on terminology, but will be expanded upon with workflow examples in the future.

Jumping head-first into the official USD Glossary or Tutorials is a perfectly valid strategy; unfortunately, the reality is that USD is a very complex machine with many moving parts intertwined with one another. Simply trying out USD’s bundled applications like USDView can be quite involved if you’re not a software engineer.
Many concepts are also tied to the hip, as such it can be very easy to drown in terminology. This kind of “rabbit-hole-diving” method of learning can be incredibly confusing and overwhelming.

This book offers an alternative path to that.

So, what even is USD?

In short, USD is a way to describe 3D-Scene Hierarchies.

Generally speaking, hierarchies consist of entries (aka. nodes) that have parent/child/sibling relationships with other nodes.
In USD, these nodes can have “physicality” (think of Geometry, Animation data, etc…) or be more abstract like grouping items, materials, shaders, and even “settings” can be expressed as a node within a hierarchy.

Where USD differs greatly from other scene descriptions, is in its ability to combine hierarchies together with varying types of behavior (this is known as composition). Within USD you can non-destructively refer to- or graft other hierarchies together, re-define previously defined data, collaborate with many others on the same hierarchy, and much more.

But wait! There’s more!

Beyond non-destructively combining hierarchies, USD is built to be extensible.
For instance, extending USD with a plugin that can parse a bespoke or commercially available file format and use those files directly inside USD.

All in all, USD aims to be a portable interchange format by defining a shared “language” sort to speak to describe scene and 3D data.
This idea is not new, but USD takes this a step further by also offering a way to consistently draw/render/image scenes. This is made possible through Hydra, USD’s backend rendering technology.

What is it not?

Just a File Format

While the main “interface” of working with USD for many artists is through its file-on-disk representation, it’s important to consider USD more as an ecosystem than another file type on disk.
Given its abilities and what it can offer, calling it a file format would be a disservice to the technology.

USD can be molded to your needs or it can be used as-is. File-on-disk representations can be omitted altogether. The way you can refer to other USD scenes is extremely flexible. And you can even integrate any custom rendering engine via a simple plugin so it understands how to work with USD data, etc…

A Replacement for Content Creation

USD can do a lot of things, but it also cannot do quite a few other things. A major component of its architecture does not allow for interactive values. Meaning that values are resolved essentially “only once” and do not change unless the entire scene is “re-composed”. In reality the way values are computed is a bit more complex than the aforementioned, but it’s easier to think of it this way.

From a design point of view, USD was built with “low-memory footprint, higher-latency data access” in mind. Thus, in order to allow for low memory usage, data access is slower than in a “high-memory footprint, low-latency access to data” paradigm. The latter sacrifices memory footprint in favor of fast data access, allowing for dynamic evaluations.

Because of this design decision, USD cannot easily express “dynamic” systems like Rigging which relies on fast dynamically computed data access. It can however via its extensibility allow studios to define rigging concepts. But this is merely a specification, the rig itself would not be evaluated inside USD and will require the host software (for example Autodesk Maya) to take that information and translate it into a rig that it can understand.

Getting USD

USD is an amazing technology stack, but unfortunately that is also what makes it hard to get started with. It is a suite of libraries and tools that are all part of the larger ecosystem that makes up USD. And while third party tooling is getting better and better, just “grabbing USD” can prove to be quite challenging.

Pixar Animation Studios offers the source code on GitHub, and for developers that is generally the first point of entry to get started. They would clone the repository, bootstrap the right version of Python and their favorite C++ compiler and then take a long coffee break to get all the tools and libraries built for their system.

Suffice to say, this approach isn’t for everyone. Fortunately, it is also not the only way to get started with USD.

As a newcomer, there are generally two ways in how to get and use USD.

If you are new to USD, and you want to learn to construct and work with USD; it’s recommended to build USD compositions and layers through a Host Application. Each host does have its own learning curve and individual challenges and idiosyncrasies with regards to USD; but will likely get you going the fastest.

USD Terminology

With introductions out of the way, the following chapters will focus exclusively on the core terminology needed to be able to understand USD. It will be much easier to follow any tutorial on USD if you understand the fundamental jargon first.

It is recommended to read the pages within this chapter in order.

Prims

Short for Primitive, and a quintessential component of USD.
Prims are the nodes within a hierarchy and can thus have parent/child relationships with other prims; meaning that prims can have other prims as children or siblings, or have another prim as a parent.

In the image below, every node in the hierarchy is a prim.

The keen-eyed will notice that prims can have a type. Xform, Mesh, Scope and Material are specific prim types. These types come with default behavior and “data”, the mechanism of which is explained in a later chapter.

While Prims themselves indicate what “type” of scene element they are, they do not necessarily possess data themselves. However, they can be considered “containers” for named data, this data is generally expressed as Properties.

Properties

Prims can have Properties, which are essentially named and typed data.

A Property within USD is actually a collective term for two distinct types of Properties:

In the above, you can see that properties are made up from a name and a typed value

These property names can also be namespaced. A property name can have 1 or more namespace identifiers separated by :.
Looking closer at the relationship example, the property name material:binding is actually namespaced. The property’s name itself is binding and it is part of a material namespace.

Namespaces can be used to categorize or group properties together.

Path

Prims and properties are identified by unique paths inside the scene hierarchy. They are a textual representation of a hierarchy - similar to folder paths in most operating systems - where each prim is separated from its parent or child via the / delimiter.

Just like folders, paths can be relative or absolute. Absolute paths always start with /

In the example below, the highlighted path /root/remi/head_M_hrc/GEO/head_M_hrc/eyeScrew_L_geo is a path to a prim with the name eyeScrew_L_geo. Constructed from the following hierarchy: / → root → remi → head_M_hrc → GEO → head_M_hrc → eyeScrew_L_geo.

As for properties, taking the previous example, inspecting the points attribute yields the path /root/remi/head_M_hrc/GEO/head_M_hrc/eyeScrew_L_geo.points. Property paths are constructed by appending the property name to a prim path, delimited by a . character.

Layer

A Layer is a collection of Prims and their Properties that can be saved to/loaded from disk or memory. As such, it can be considered a “saveable hierarchy”.

Standard USD Layers can be represented on-disk via

Metadata

Prims, their properties and the layers they are part of can have metadata applied to them. This is additional static (as in, it can not change over time) data that USD or a user can read, use or define.

Metadata can be used to describe behavior, incur meaning, represent documentation, etc. USD comes bundled with an extensive suite of metadata out of the box.

Simple Metadata Examples

Layer Metadata

In the image above, the PseudoRoot at path / has been selected and the metadata panel in usdview has been highlighted. This root represents the entry.usda layer from Animal Logic ALab. entry.usda defines metadata that can be inspected and presents the following information to the user about itself:

• The linear units used are 0.01 meters (i.e. centimeters) → metersPerUnit = 0.01
• The scene’s up axis is Y → upAxis = Y
• Two layers contribute to the scene (more about this later in Local/Sublayer) → subLayers = [...]
• Animation is present between time code 1004.0 and 1057.0 with 24.0 frames and time codes per second.
  • startTimeCode = 1004.0
  • endTimeCode = 1057.0
  • framesPerSecond = 24.0
  • timeCodesPerSecond = 24.0

Prim Metadata

Metadata on Prims can infer a lot of information about the prim itself, how it is used in the scene (aka Composition), what kind of properties it has, etc.

From the above we know that the prim at /root/alab_set01/lab_electronics01_0001/bench01/decor_paper_notej01_0001

• Is an Xform → typeName = Xform
• It is instanced (more about Instancing later) → instanceable = true
• Has two VariantSets (more about VariantSets later) → geo and geo_vis
• Is categorized as a component (more about the Kind metadatum later) → kind = component
• Etc.

Property Metadata

Lastly, there is property metadata. This data is meant to give fine grained information about the property itself. For example

• What type it is → typename = double3
• Whether it can change over time → variability = Sdf.VariabilityVarying
• Is it a custom “out-of-schema” (see Schemas later) property → custom = false

Layer Stack

Each layer internally keeps track of a “local” stack of layers that contribute to that layer. This stack is an ordered collection of layers used within this layer that contribute to its hierarchy and composition.

Composition

Roughly put, the act of combining layers and their prims, properties and metadata together through various means known as composition arcs.

While combining layers together could be considered “composing” them, what USD’s composition engine actually uses are the layer stacks of each layer.

Stage

The composed result of opening a layer. Think of it as a Photoshop canvas when opening a .PSD document. All the Photoshop layers interact with one another to produce a “final image”. The layers still exist, they can still be edited, deleted, replaced, etc… but what you see is the result, and that is the Stage in USD.

This composed result can be “flattened” and saved to a new layer, which would be similar to taking the aforementioned Photoshop document and exporting it to a JPEG.

Opinions

Circling back to properties, when you set a value on an attribute or metadatum or author a relationship within a layer, you are effectively expressing an opinion on that value. This is named an opinion because value assignments can always be changed by others! This is a very important concept for composition.

A different way of looking at this would be that “setting a value” implies that that action is final and the value itself becomes immutable; whereas with opinions you merely mean

If the value already existed before, you are essentially “overriding” it

Overrides

When expressing an opinion within a layer, it is possible to “redefine” a previously defined value of the property being edited. This mechanism is known as overrides because you are overriding what was there before. However, it is very important to note that the original data remains unchanged. The override only exists within the layer where you are defining it

This is by far the most important aspect to understand about USD. Opinions and their “value resolution” (resolving which value gets applied in the end) are key to the entire composition mechanism.

Below is a simple example of overriding a previously defined attribute’s opinion.

Stage Traversal

Generally a concept used when programming with USD, but it is important to understand for users too. Stage Traversal is essentially iterating over the scene graph of a layer opened in a stage. Traversal can be filtered via “rules” (or predicates), limited to sub-trees, parts of the hierarchy can be pruned during traversal, and so on.

By default, USD Stage Traversal will only consider prims that are active, defined, loaded and are not abstract. Depending on which tool is used, users may be able to change this behavior. Using the programming interface however, developers have full control over this behavior.

Kind

Kind is a prim-level metadatum that can be used to “categorize” prims and their descendants into higher level concepts than just their definitions (ex. Mesh, Sphere, Cube, etc…).

USD ships with a few different kinds that can be used to categorize prims

Using kind can greatly speed up finding the “right” types of prims you may be interested in during Stage Traversal. Kind annotations can be used to selectively prune entire prim child-trees for instance.

How kind can be used

Taking a look at the root layer of Animal Logic ALab, we can see that top-level prims can be annotated as assembly, this allows for easily identifying “assets” within the scene. In the example below, both lab_workbench01_0001 and its parent alab_set01 are annotated as assemblies.

An assembly annotated prim by itself can contain other prims with varying types of kinds. Looking deeper in the example above, we can see that the workbench itself at /root/alab_set01/lab_workbench01_0001/workbench01 is marked as a group.

And diving even deeper, /root/alab_set01/lab_workbench01_0001/workbench01/furniture_workbench01_0001 is a component. Component should not contain any other kind types that derive from model, but it can have subcomponent kinds.

These components can then be used for efficient discovery and instancing without having the need to dive deeper into their own hierarchies.

Purpose

Purpose is an attribute that can be used to give a prim and its descendants a high-level “visibility flag” in context of rendering.

For example, if a prim has its purpose attribute set to render, it will be excluded from being drawn in a renderer that only wants to draw proxy prims.

In some sense, setting purpose could be considered Stage Traversal but for rendering.

Currently, only 4 values are supported by the purpose attribute:

/root/GEO has its purpose set to render, it will only be drawn when the active renderer requests prims with a render purpose.

/root/GEO_PROXY has its purpose set to proxy, it will only be drawn when the active renderer requests prims with a proxy purpose.

Specifier

When defining a prim in the scene graph, there are three different ways of doing so.

def Xform "MyTransform"
{
  # ...
}

def "MyPrim" {
  # ...
}

over "SomethingThatAlreadyExists"
{
  # ...
}

class "_MyClass"
{
  # ...
}

Composition Arcs

USD’s composition engine utilizes a few different ways of composing, these are known as Composition Arcs. Simply put, they are a set of operators that determine how layer stacks and their opinions are combined together.

Let’s look in more depth about each different composition arc type.

Local/Sublayer

Layers can sublayer other layers, grafting multiple layer stacks together in order into one. Sublayering is in fact how Layer Stacks are made!

To emphasize how order matters, given a Cube prim at path /Foo in layer_a.usd and a Sphere prim at path /Foo in layer_b.usd; when sublayering both in layer_c.usd, the final type of /Foo will depend solely on the order in which layer_a.usd and layer_b.usd are brought in.

Reference

Layer References

Beyond sublayers, layers can also be grafted underneath prims. Using the example Cube and Sphere from Local/Sublayer, we can also create prims and have them point to these layers respectively.

Local References

While the general use-case is to use layers when referencing, it is not required to do so. It is entirely possible to add a reference to a prim within the same layer. This is known as a local reference

You would merely need to add a reference to the target prim and its entire hierarchy will be grafted underneath:

def "ReferenceToFoo"(
        prepend references=</foo>
) {
}

Layer Prim References

But, this goes even further! Remember, composition acts on layer stacks, not individual layers; so it is also possible to reference specific prims from another layer’s layer stack. Even if these prims themselves are the composed result from the target layer’s layer stack

def "ReferenceToPrim"(
    prepend references= @./several_prims.usd@</A_Capsule>
) {
    float3 xformOp:translate = (3, 0, 0)
    uniform token[] xformOpOrder = ["xformOp:translate"]
}

VariantSet

VariantSets and variants allow for authoring a “switchable” state of a prim within a layer. In the example below, a top level prim with the name Implicits is authored which defines a VariantSet named Shape. This VariantSet defines a few different entries (aka variants ) that each do something different.

When changing the active variant, USD will inject anything that is defined within that variant into the current composition. In our example, each variant adds a child to Implicits with differing types. One is a capsule, another a cube, a sphere, and so on.

Within variant definitions, you are essentially free to do whatever you want. If you wish to define a complete hierarchy in a variant, you can. Add references to other layers? You can. Expressing opinions on values or metadata, you can. However.

Payload

Payloads are lazily loaded references. When a prim uses a payload, USD can be told to opt out of loading these layers unless the user requests to do so.

When a referenced layer is heavy due to the amount of data or hierarchy complexity, it is often beneficial to have the user manually load those in after opening the layer in a stage. Generally speaking, non-important layers should be behind payloads. If they’re not loaded, they also cannot be traversed and should not contain anything considered “important”.
The definition of “important” depends entirely on the use case of course.

Example → Putting a high res model behind a payload

With unloaded payloads, the resulting hierarchy looks like this

However, the payload can be toggled on/off after the stage has been loaded.

As a result, the full hierarchy is loaded

#usda 1.0
(
    defaultPrim = "Asset"
)
 
def Scope "Asset"
{
    def Xform "Geometry"
    (
        prepend payload=@./highres_model.usd@
    )
    {
    }
}

Inherits

Very similar to the concept of “inheritance” in programming. Prims can “inherit” other prims (concrete or abstract), meaning that they reflect the hierarchy and properties defined in the prim that they are inheriting from. This also means that if a change is authored on the base prim or its hierarchy, any prims that inherit it immediately get those changes applied to them.

Within context of a singular layer, inherits does not offer a noticeable difference between it and a local reference. However, when using inheritance in a multi-layer composition environment, it does differ. References tend to become fully encapsulated within the layer stack they’re referenced. Meaning that references loose any sense of “connectivity” to their referred layers outside of their layer stack. Inherits on the other hand are always live, no matter how deeply nested within a composition, or how many redefinitions of its base. A prim is always able to backtrack to its original “base”, regardless of composition depth!

Example → Simple inherits

SomeScope, SomeMesh and SomeTransform are defined prims of differing types, but all inherit from an abstract class prim named _Base . This class prim defines two Xform children, Foo and Bar.
Due to _Base being a class, it does not automatically show up in the hierarchy as class prims are not taken into account in default Stage Traversal. So we have to explicitly tell USDView to also display Abstract Prims

Inheriting from _Base results in having its hierarchy grafted underneath each prim that inherits it.

Modifying _Base would be reflected immediately on all prims that inherit from it, without having to do anything to these prims. In this case, a new child prim was added under /_Base/Bar called Baz

Specializes

Specializing is taking a base definition of a prim (and its hierarchy) and further refining it into a specialized version of itself. For example taking a Metal material and specializing certain properties to make a CorrodedMetal material. This specialization could refine certain material properties, redefine or add shaders, textures, etc… It is not dissimilar from inherits, however with one key difference.

If you try to express an opinion on a specialized property, your opinion will essentially be discarded. This is not the case however with inherits.

Example → Corroded Material specialization

There are two layers, robot.usd and world.usd.

Robot.usd

robot.usd defines a Robot prim and three Material prims, Metal, CorrodedMetal and InheritedMetal. Metal defines two attributes, inputs:diffuseGain and inputs:specularRoughness.

CorrodedMetal is a specialization of Metal where inputs:specularRoughness is the specialized attribute, we say it always has a value of 0.2.

def Material "CorrodedMetal" (
    specializes = </Robot/Materials/Metal>
)
{
    # specialize roughness...
    float inputs:specularRoughness = 0.2
}

Whereas InheritedMetal is merely an inherits arc to Metal . You will notice that regardless of inherits or specializes, the result is the same. Both CorrodedMetal and InheritedMetal take over the base properties of Metal, but have an opinion on the inputs:specularRoughness attribute.

world.usd

world.usda references robot.usda and expresses and opinion on the base Metal prim. It says that inputs:diffuseGain and inputs:specularRoughness are to be 0.3 and 0.1 respectively.

#usda 1.0
 
def Xform "World"
{
    def "RosieTheRobot" (
        references = @./robot.usda@</Robot>
    )
    {
        over "Materials"
        {
            over "Metal"
            {
                    float inputs:diffuseGain = 0.3
                    float inputs:specularRoughness = 0.1
            }
        }
    }
}

Difference between Inherits and Specializes

When inspecting the resolved opinions in world.usd, notice that the overridden values for inputs:diffuseGain and inputs:specularRoughness on the base Metal propagate fully to InheritedMaterial, but not to our specialized CorrodedMaterial.

Base Metal Override	Result on InheritedMaterial	Result on CorrodedMaterial
over “Metal” {     float inputs:diffuseGain = 0.3     float inputs:specularRoughness = 0.1 }

As seen above, even when we have a stronger opinion on the base Metal definition for both properties, specializations always win.

Strength Ordering (LIVRPS)

Composition and opinion value resolution go hand in hand, and in order to remain sane; there are rules. Each composition arc has a “strength” assigned to it. Meaning that if for example opinions targeting a property are authored on 3 different composition arcs within the same layer stack, the composition arc that is the “strongest” wins. This is where the acronym LIVRPS (Liver Peas) comes into play.

It stands for

• Local
• Inherits
• Variants
• References
• Payloads
• Specializes

This list acts as top-down stack. When USD needs to resolve an opinion for a property or metadatum, it will look for opinions via these composition arcs in this exact order. If an opinion has been found, any subsequent searches down the stack are immediately aborted and the opinion is resolved. If no authored opinion has been found, USD will fall back to the property/metadatum’s default value.

All composition arcs besides Local will trigger a recursive LIVRP(S) evaluation. However, within this recursive evaluation, S(pecializes) is ignored except for the Specializes composition arc. It triggers a full LIVRPS evaluation if encountered.

The following diagram visualizes the decision tree of when and where opinion values are fetched

Default Prim

When authoring a layer, it is possible to also define a “default prim” for it. This is a layer metadatum that contains the name of the prim that should be used automatically when the layer is used in a reference or payload composition arc without an explicit prim path.

This name must point to a root level prim, meaning a direct child of the PseudoRoot. Therefore, it is not allowed to point to a path.

#usda 1.0
(
    defaultPrim = "PrimName"  
)

def "PrimName" {}

#usda 1.0
(
    defaultPrim = "PrimName/NestedPrim"  
)

def "PrimName" {
    def "NestedPrim" {}
}

If defaultPrim has not been explicitly authored, USD will trigger a “unresolved reference prim path” warning and the target layer will not compose correctly.

Warning: ... In </reference>: Unresolved reference prim path @.../defaultPrim.usda@<defaultPrim> ...

Example

Let’s take a look at a very simple example case. There are two layers, one that defines multiple prims at its root (defaultPrim.usda), and one that references it (reference.usda).

#usda 1.0
(
    defaultPrim = "CubePrim"  
)

def Cube "CubePrim" {}
def Sphere "SpherePrim" {}
def Cone "ConePrim" {}

Do note that reference.usda only references the layer itself and does not specify a particular prim to reference in from defaultPrim.usda

#usda 1.0

def "reference"(
    prepend references= @defaultPrim.usda@
) {
}

When opening the reference.usda layer inside a usdview stage, we see that only one prim is brought into its Layer Stack, and that is the Cube.

When changing the default prim metadatum to for example defaultPrim = "SpherePrim", the Sphere will now be referenced in instead.

Removing the defaultPrim metadatum altogether will yield an empty reference arc. The layer itself is still referenced, but none of the prims in it are composed.

List-Editing

List editing is a feature within USD that allows for non-destructively editing list-typed elements within a scenegraph. You can append, prepend or delete items from a list during composition. Or even explicitly override the entire list. This is generally referring to references, relationships, custom metadata, inherits, specializations and variantsets. Attributes of a list-type cannot be list-edited.

In the example below, we override the list of references on a prim to also prepend a new reference to another layer. This results in the prim referring to two layers (assuming the original definition only points to a single layer).

#usda 1.0
 
over "World"
{
    over "Foo"
    {
        # Override "Bar" to also reference baz.usd in addition to its original references
        over "Bar" (
            prepend references = @./baz.usd@
        )
        {
        }
    }
}

EditTarget

When opening a layer in a stage, and you make edits to the scene graph, these edits are by default recorded onto the “Root Layer” (the layer used to create the stage).

In the scenario of a complex composition consisting out of many layers and composition arcs, it is not out of the ordinary to want to make edits to one of those layers. Rather than opening said layer individually and applying the edits there, USD offers something called an EditTarget. This EditTarget allows you, as the user, to specify to USD which layer edits should get recorded to (edits being: overrides, hierarchy changes, etc…).

With this mechanism users can work in a fully composed scene, yet still be able to record edits to individual layers used in this composition. Think of it as changing the active layer in a Photoshop document.

Instancing

Instancing is a mechanism in USD where layers can be designed to save memory and composition complexity. When a layer is for example referenced onto a prim, USD will re-compose the entire hierarchy for each reference in that layer, even if all references point to the same layer.

With instancing however, USD will create a “Prototype” of this reference’s composed result behind the scenes, and every reference to this layer is replaced by a local-reference to this prototype prim instead. Enabling USD to compose the referenced layer’s layer stack only once.

All selected prims in the example above reference chemistry_bottle01.usda, but are also marked as instanceable via the instanceable = true metadatum. This metadatum tells USD that it should only compose the chemistry_bottle01.usda once in a __Prototype prim. When having done so, all references internally to chemistry_bottle01.usda are actually local prim references to the prototype prim (in this case __Prototype_37).

Schemas

Schemas are the “descriptions” of Prims, properties, metadata, etc… Schemas allow USD to have “knowledge” of what a Prim or its attributes mean. USD can be extended with new schemas via Plugins to define custom sets of properties, whole new prim types, metadata, and more.

Schemas are built by authoring the schema definition itself in the .usda file format syntax, which can be used to generate the necessary source code and plugin files.
Without diving into the particulars, USD’s default prims and properties are in fact Schemas that Pixar has provided in the source code.

Generally there are two types of schemas users can author.

IsA (Typed) Schema

“Is A prim this”-kind of schema. Essentially the schema definition that defines the “type” of prim.

In the image above, the Type column lists which IsA Schema the prim subscribes to.

When looking at the USD “code”, the keyword between def and the name of the prim signifies which IsA Schema the prim should subscribe to.

def Xform "MyTransform" {}  # MyTransform subscribes to the Xform IsA Schema
def Cube "MyCube" {}  # MyCube subscribes to the Cube IsA Schema
def "EmptySpec" {}  # EmptySpec is a valid prim, it simply has no default set of properties attached to it. It could literally be anything.

IsA Schema Example -> UsdGeomCube

In the example below you can see the schema definition for our favorite Cube. It defines that Cube inherits from Gprim (a base for all drawable prims), metadata for the type (like documentation string) and two attributes. size and extent.

class Cube "Cube" (
    inherits = </Gprim>
    doc = """Defines a primitive rectilinear cube centered at the origin.
    
    The fallback values for Cube, Sphere, Cone, and Cylinder are set so that
    they all pack into the same volume/bounds."""
    customData = {
        dictionary extraPlugInfo = {
            bool implementsComputeExtent = true
        }
    }
) {
    double size = 2.0 (
        doc = """Indicates the length of each edge of the cube.  If you
        author \\em size you must also author \\em extent.
        
        \\sa GetExtentAttr()"""
    )

    float3[] extent = [(-1.0, -1.0, -1.0), (1.0, 1.0, 1.0)] (
        doc = """Extent is re-defined on Cube only to provide a fallback value.
        \\sa UsdGeomGprim::GetExtentAttr()."""
    )

}

Creating new prim types can be as easy as the above, or as complex as defining an entire Mesh.

API Schemas

API Schemas offer a way to contribute to a prim’s “definition” by defining sets of predefined properties and metadata or offer a way to extract that information for you.

Generally speaking, API Schemas come in two different flavors, Non-applied API Schemas and Single or Multiple-applied API Schemas.

Non-Applied Schemas

These schemas helps the developer by offering a high level abstraction for fetching properties and metadata.

These kinds of schemas usually do not define properties themselves, only ways to fetch them.

# Python example to set the Kind type on a prim via the UsdModelAPI, a non-applied API schema
Usd.ModelAPI(prim).SetKind(Kind.Tokens.subcomponent)

Single or Multiple-applied API Schemas

These are the kinds of schemas users will interact with implicitly.
Applied API Schemas define the default properties that will be added to a prim’s definition when it is applied.

For example if an applied schema (let’s call it FooAPI) defines a float attribute named foo, when that schema is applied to a prim, the foo property will be available for users to express opinions on. If the user does not express an opinion on it, foo will fall back to its default value.

In a more concrete example, let’s look at the MaterialBindingAPI which is responsible for defining properties on prims that need a binding to a material.
The prim at path /Sphere/Mesh has the MaterialBindingAPI applied to it through the prim’s apiSchemas metadata (this a List-Editable metadatum btw, so users can also override which API Schemas are applied to a prim)

This allows for editing the material:binding property on this prim now. The important thing to note here is the custom metadatum on the property. This indicates that the property is known to USD and that it belongs to a schema. Generally speaking, if custom is authored as True, it is considered an inert, out-of-schema property.