# Usd Reference Namespace Source

> Use this skill when implementing or verifying the first reference-composition namespace source backed by a base namespace source and already-opened referenced layers.

- Skill: `nvidia-omniverse/usd-reference-namespace-source` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nvidia-omniverse/usd-reference-namespace-source`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-omniverse/usd-reference-namespace-source/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/usd-reference-namespace-source

---


# usd-reference-namespace-source

Use this skill when implementing or verifying the first reference-composition
namespace source backed by a base namespace source and already-opened referenced
layers.

## Spec Sources

- `specification/composition/README.md` references and composition strength
- `specification/file_formats/README.md` `ReferencesMetadata` and
  `ReferenceListItem`
- `specification/document_data_model/README.md` `references:
  listop<Reference>` and `defaultPrim`
- `specification/stage_population/README.md` namespace source consumption

Pinned tag / commit: `v1.0.1`

## Provides

- A `NamespaceSource` capability with direct reference composition
- Direct reference discovery from the base source's exposed `references` field
- Path-only internal references within the base namespace source
- Reference target mapping from an external asset layer into the referring prim
- Asset-only reference target selection through the referenced layer
  `defaultPrim`
- Bounded recursive and chained reference expansion through supplied referenced
  layers
- Local opinions stronger than referenced opinions
- Same-reference-family ordering by namespace depth and source-visible sibling
  list order
- Reference-family-only prim/property opinion views, or equivalent separable
  provenance, for downstream composition consumers such as relocates
- Path-valued field contents such as relationship `targetPaths` and attribute
  `connectionPaths` remapped into the referring namespace
- Arc-local `layerRelocates` mappings authored in referenced layer stacks and
  carried by nested reference records
- Composed child and property names across local and referenced specs
- Diagnostics for missing referenced layers and missing target prims

## Contract

This skill owns `contracts/handles/reference-namespace-source.handle.json` and
implements the shared namespace-source capability described by
`contracts/capabilities/namespace-source.json`. It also follows
`contracts/capabilities/semantic-runtime-types.json`.

The first version is an in-memory bounded reference provider. It consumes a base
namespace source, such as `usd-layer-stack-namespace-source`, plus a map of
already-opened reference layers keyed by authored asset identifier. It does not
resolve asset identifiers, open files, evaluate payloads, or perform full value
resolution.

The source exposes capabilities:

- `mode`: `composed_namespace`
- `composition`: `partial`
- `value_resolution`: `partial`
- `payload_loading`: `absent`
- `instancing`: `absent`
- `schema_fallbacks`: `absent`
- `child_ordering`: `composed`
- `property_ordering`: `composed`

`partial` composition means external references, path-only internal references,
and bounded recursive references authored on supplied referenced target
subtrees. Reference target descendants are mapped under the referring prim, and
nested references compose their parent and child namespace mappings.

## Composition Rules

Reference arcs are read from the base source's source-visible `references`
field. This first contract consumes the source-exposed listOp value and
preserves `explicit` entries when present, otherwise `prepend` followed by
`append`. Cross-layer reference listOp composition remains deferred to a later
composition contract.

External reference arcs have an authored asset identifier. The referenced layer
is supplied by the caller or adapter. If an arc also has a target path, that
prim is the reference root. If the arc has only an asset, use the referenced
layer's `defaultPrim`; missing defaultPrim is a diagnostic. Path-only internal
references use the base namespace source as the referenced namespace and must
name an explicit target prim path.

The reference target prim maps to the referring prim path. Descendant prims and
properties below the target are mapped by replacing the target prefix with the
referring prim path.

Nested references authored inside supplied referenced target subtrees must be
expanded transitively while their authored asset layers are supplied. Compose
the accumulated namespace mapping at every hop: a nested target prim contributes
at the parent exposed prim plus the nested source suffix. Detect cycles by
authored asset identifier, referenced target path, referring prim path, and
mapping context. Cycles are diagnostics and must never recurse without bound or
crash generated implementations.

If the referenced layer stack that authors a nested reference also authors
`layerRelocates`, carry that relocate namespace mapping on the nested reference
record. The mapping must hide relocated source paths, expose relocated target
paths, suppress stale target collisions from the referenced target layer, map
remote-source reads back to the relocated source specs, prune deleted source
subtrees, and remap path-valued fields through the accumulated reference plus
relocate mapping.

Path-valued field contents authored under referenced specs are mapped the same
way before fields are emitted. Each ObjectPath under the referenced target
subtree is projected under the referring prim path. For `targetPaths` and
`connectionPaths`, ObjectPaths outside the referenced target subtree are pruned
by this bounded external-reference provider rather than emitted in
referenced-layer coordinates. For path-only internal references, ObjectPaths
outside the referenced target subtree remain in the shared composed namespace.

Local base-source opinions are stronger than referenced opinions. Stronger
`over` specs may override weaker referenced `def` specs without erasing the
effective definition.

Keep referenced-family opinions separable from local base-source opinions even
when the provider also exposes a flattened NamespaceSource view for stage
population tests. Downstream providers such as relocates must be able to consume
referenced opinions at a path without accidentally consuming local opinions
authored at that same path.

When multiple reference arcs contribute to the same exposed path, order
reference-family opinions strong-to-weak by namespace depth first: deeper
authored reference arcs are stronger than ancestor reference arcs. For sibling
reference arcs authored at the same prim, preserve the source-visible authored
list order.

Child prim names are composed from referenced contributors first, then local
base-source contributors, applying local ordering after local contribution.
Property names are the union of referenced and local properties, sorted with
`usd-paths` path-element ordering, then reordered by the strongest local
`propertyOrder` if present.

## Boundary Guards

Consume `usd-layer-stack-namespace-source` or another namespace source for base
opinions. Do not bypass the source boundary to read parser-local structures.

Reference source runtime records must retain referring prim paths, referenced
target paths, and mapped contributor paths as path handles/references. String
spellings are acceptable for asset identifiers, diagnostics, and adapter
summaries, but not as the authoritative identity for USD object paths.
Contributing source provenance must be stored as typed records containing a
source/layer identifier and a semantic spec path. Do not store or later parse
composite strings such as `asset.usda:/Prim` in domain logic; those are adapter
or diagnostic renderings only.

Consume `usd-document-model` for already-opened referenced layers. Do not store
or compose canonical layer dump JSON as durable state.

Consume `usd-paths` and `usd-tokens` for path and token identity. Adapter
strings are boundary inputs only.

Do not perform asset resolution, layer opening, payload loading, inherits,
specializes, variant composition, root-layer relocates, value clips, schema fallback
evaluation, stage population, model hierarchy traversal, instancing, or
attribute value interpolation.

## Test Obligations

- source capability declaration reports `composed_namespace`
- direct external references contribute prim, property, and child opinions
- local opinions remain stronger than referenced opinions
- namespace-deeper reference arcs are stronger than ancestor reference arcs
- sibling reference arcs preserve source-visible list order
- asset-only references use the referenced layer `defaultPrim`
- missing reference layers fail clearly
- nested/chained references expand when their layers are supplied
- nested references authored in layer stacks with relocates remap children,
  properties, targetPaths, and connectionPaths through that arc-local mapping
- recursive reference cycles are diagnosed without crashes
- all cases in
  `goldens/unit/usd-reference-namespace-source/reference-namespace-source.json`