# Usda Spec Parser > Use this skill when implementing or verifying the USDA single-layer parser. - Skill: `nvidia-omniverse/usda-spec-parser` (Agent Skill) - Install (CLI): `npx skillmds@latest add nvidia-omniverse/usda-spec-parser` - Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-omniverse/usda-spec-parser/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: NVIDIA-Omniverse (https://skillmd.com/u/nvidia-omniverse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nvidia-omniverse/usda-spec-parser --- # usda-spec-parser Use this skill when implementing or verifying the USDA single-layer parser. ## Spec Sources - `specification/file_formats/README.md` sections `Layer`, `Prim Specs`, `Attribute Specs`, `Relationship Specs`, `Common Metadata`, and variant statements - `specification/document_data_model/README.md` Pinned tag / commit: `v1.0.1` The pinned specification is normative. This skill, its contracts, and its goldens exist to decompose that specification and add representation, diagnostic, API, and performance constraints needed for a usable generated library. They must not relax the grammar or make document-model storage fields stand in for grammar productions. ## Provides - Parse a USDA layer into the document model - Map layer metadata to layer fields - Map standalone layer doc strings to the layer documentation field - Map prim declarations to prim specs - Map authored prim metadata, including references, payloads, inherits, specializes, variants, and variantSets, to stored fields without evaluating composition - Map attribute declarations and values to attribute specs - Map relationship declarations and targets to relationship specs - Map variant set and variant declarations to stored specs - Map sublayer and relocate metadata to stored layer fields without loading or applying dependent layers - Maintain child list fields - Map `reorder rootPrims`, `reorder nameChildren`, and `reorder properties` - Return the populated document-model `Layer` - Support canonical layer dump JSON only through an adapter boundary ## Contract This skill owns `contracts/handles/usda-spec-parser.handle.json` and provides the `usda_spec_parser` capability consumed by USDA layer opening. It consumes lexical parsing, value parsing, document-model storage, and path construction from graph dependencies instead of owning alternate versions of those systems. It also follows `contracts/capabilities/semantic-runtime-types.json`. Production-family obligations are factored into: - `contracts/spec-coverage/usda-single-layer.coverage.json` - `contracts/usda-productions/common-metadata.contract.json` - `contracts/usda-productions/layer-structure.contract.json` - `contracts/usda-productions/layer-metadata.contract.json` - `contracts/usda-productions/prim-specs.contract.json` - `contracts/usda-productions/attribute-specs.contract.json` - `contracts/usda-productions/relationship-specs.contract.json` - `contracts/usda-productions/variant-specs.contract.json` - `contracts/usda-productions/parser-diagnostics.contract.json` The parser accepts one USDA file and emits the canonical dump described in `harness/dump_contract.md` only through an adapter. The domain parser result is a target-native result containing either a populated document-model `Layer` or diagnostics. It must not be a `Json`, Python `dict`, tagged JSON, or canonical dump tree. Parsing is grammar-first and storage-second. Match a production valid for the current parser context, then map the result to document-model fields. Do not parse metadata by accepting an arbitrary key, looking up a core field token, and then deciding what value grammar to use. Field names are storage labels; they do not authorize syntax. Every created spec must be stored through `usd-document-model`. All spec paths must be constructed by `usd-paths`; do not keep a parser-local path type. Field keys, child/property names, type names, variant set names, and selected variant names that flow into document-model or composition-facing records must be converted to target-native token/name identity before durable storage. JSON materialization is allowed only when a validation adapter or dump command serializes the returned `Layer`. Metadata parsing helpers should either mutate the document-model `Layer` directly or return target-native field assignments keyed by document-model field tokens. They must not return `map`, Python `dict`, tagged JSON, or any other serialized object tree. Attribute and relationship field assembly follows the same rule: build `FieldValue`-style typed values, not adapter JSON that is immediately converted back into storage. Known document-model fields must use the core field tokens provided by `usd-document-model`; do not route known names like `propertyOrder`, `primOrder`, `payload`, `references`, `defaultPrim`, `documentation`, `targetPaths`, or `typeName` through extension-field string lookup. Metadata key dispatch must classify the authored USDA spelling once at the parser boundary with the current metadata context before selecting storage or value typing. The generic `KeyValueMetadata` and `ListOpMetadata` productions use `Identifier`, which excludes USDA keywords. Keywords such as `payload`, `references`, `inherits`, `specializes`, `variantSets`, `variants`, `kind`, `subLayers`, and `relocates` are legal only through the context-specific productions that mention them. Do not accept a prim-only keyword as generic attribute or relationship metadata simply because the document model has a core field token with that spelling. Only unknown non-keyword extension metadata may use extension-field token lookup. Layer metadata blocks may contain a standalone documentation string. Parse that as document-model `documentation`; do not route it through the generic identifier-based metadata entry path. The metadata context must distinguish at least layer, prim, attribute, and relationship metadata. A boolean `layer`/`non-layer` split is not sufficient: it accepts prim-only keyword productions on attributes and relationships. For variant statements, use the prim metadata production family for grammar dispatch, then store the fields on the variant spec. Reference and payload metadata must store `listOp` and `listOp` using native arc-record items. Do not store those items as parser dictionaries, bare asset strings, or bare path strings; convert them to adapter JSON only during dump/validation serialization. Schema metadata must preserve the field's specified listOp element type. `apiSchemas` applies to prim specs and stores authored applied-schema identifiers as `listOp`. This is distinct from `variantSetNames`, which is `listOp`. The parser records these fields as inert authored data and must not inject schema fallback properties or evaluate applied-schema semantics. Other specialized document-model values must also stay native when parsed: `specifier`, `variability`, `Retiming[]`, `Relocates`, `TimeSamples`, and `Spline`. Their canonical dump shapes may contain strings and objects, but the parser/domain boundary must pass enum/domain values, path references, numeric-time maps, and spline records rather than plain strings or dictionary payloads. Layer `relocates` metadata accepts both path-to-path entries and path-to-None entries. `None` is the deleted-relocate target sentinel for composition providers and must not be rejected by the parser or stored as a string literal. Property parsing must handle shared listOp prefixes explicitly. The USDA grammar allows both `ListOpRelationship` and `ListOpConnect`; after greedily consuming an optional listOp and optional `custom`, dispatch on the following declaration tokens so `append rel target = ...` and `append float attr.connect = ...` are both accepted without parser backtracking. A listOp prefix alone must not imply the property is a relationship. Composition fields may be parsed as inert metadata only if needed by a golden, and the production contracts now treat their authored storage as in scope. This skill must not implement composition semantics, but it must not drop authored composition arc fields simply because composition itself is deferred. ## Boundary Guards Defer identifiers to `usd-identifiers-and-names`. Defer values to `usda-value-parser`. Defer paths to `usd-paths`. Defer listOps to `usd-listops-authored`. Defer storage to `usd-document-model`. Do not implement sublayer loading, reference/payload resolution, inherit or specialize composition, variant selection composition, asset resolution, value resolution, or stage population. ## Test Obligations - all cases in `goldens/integration/usda-single-layer/basic.json` - all production entries marked `implemented` in `contracts/spec-coverage/usda-single-layer.coverage.json` - positive and negative goldens for context-sensitive grammar decisions, especially metadata keywords and shared-prefix productions - parser domain API returns a document-model `Layer`, not JSON - duplicate spec path halts processing - last authored order field wins - child lists reflect parsed specs - inactive prims remain present in the layer - authored composition arc metadata is stored as layer data without evaluation - variant set and variant specs are stored without performing variant selection - sublayer and relocate metadata are stored without loading or applying dependent layers - standalone layer doc strings parse as documentation metadata