NCP-OUSD: Schema System and Schema Development

This domain covers how USD defines types and how studios extend them safely without breaking consumers.

Two kinds of schema

• IsA (typed) schemas define a prim's type: UsdGeomMesh, UsdGeomXform, UsdShadeMaterial. A prim has exactly one type name and one IsA chain.
• Applied API schemas attach capabilities: MaterialBindingAPI, CollectionAPI, SkelBindingAPI. A prim may carry many, listed in apiSchemas metadata. Multiple-apply schemas carry an instance name, e.g. collection:geo and collection:lights.

Authoring a schema

Write schema.usda (or apiSchema.usda for APIs), then run usdGenSchema. The generator emits C++/Python classes, generatedSchema.usda with fallback values and fallback prim types, and a plugInfo.json. Register the plugin directory on PXR_PLUGINPATH_NAME; UsdSchemaRegistry reads it when a stage opens. Attributes must be declared in the schema file - you cannot invent them in hand-edited generated code.

Rules that matter

• fallbackPrimTypes decide what an untyped prim becomes; Xform is the usual default.
• Auto-applied API schemas (autoApply = true) appear on every matching prim: convenient for cross-cutting data, costly at scale.
• customData on schema properties is the documented place for tooling hints; doc is for humans.
• Never rename shipped schema properties. Add new ones and bump pluginVersion/libraryVersion metadata.

Worked example

To track a studio ID on any asset, define MyStudioAssetAPI as a single-apply API in apiSchema.usda with a string assetId attribute, run usdGenSchema, register the plugin path, then prim.ApplyAPI('MyStudioAssetAPI') and author prim.GetAttribute('assetId').Set('A-1042').

Traps

Hand-editing generated files; forgetting the plugin path so the prim loads as plain Typed; and trying to attach an IsA schema with ApplyAPI instead of SetTypeName.