# Usd Payload Namespace Source

> Use this skill when implementing or verifying the first direct loaded payload opinion source backed by supplied payload arc sites and already-opened payload layers.

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

---


# usd-payload-namespace-source

Use this skill when implementing or verifying the first direct loaded payload
opinion source backed by supplied payload arc sites and already-opened payload
layers.

## Spec Sources

- `specification/composition/README.md` payloads and composition strength
- `specification/file_formats/README.md` `PayloadMetadata` and `PayloadList`
- `specification/document_data_model/README.md` `payload: listOp<Payload>`
- `specification/stage_population/README.md` optional payload population flag

Pinned tag / commit: `v1.0.1`

## Provides

- A payload arc opinion source that can expose mapped payload opinions through
  the `NamespaceSource` shape for conformance tests
- Direct payload discovery from supplied payload arc sites
- Path-only internal payloads within the payload arc layer namespace
- Payload target mapping from an external asset layer into the payload-bearing
  prim
- Asset-only payload target selection through the payload layer `defaultPrim`
- Payload-contributed prim and property opinions in composed scene coordinates
- Path-valued field contents such as relationship `targetPaths` and attribute
  `connectionPaths` remapped into the payload-bearing namespace
- Bounded references authored inside loaded payload target subtrees while
  their referenced layers are already supplied
- Arc-local `layerRelocates` mappings authored in loaded payload layer stacks
  and carried by nested reference records
- Diagnostics for missing payload layers and missing target prims

## Contract

This skill owns `contracts/handles/payload-namespace-source.handle.json` and
implements the shared namespace-source shape described by
`contracts/capabilities/namespace-source.json` and the arc-source split in
`contracts/capabilities/composition-opinion-source.json`. It also follows
`contracts/capabilities/semantic-runtime-types.json`.

The first version is an in-memory direct loaded-payload opinion source. It
consumes payload-bearing prim paths and their source-visible payload listOp
values, plus a map of already-opened payload layers keyed by authored asset
identifier. It does not resolve asset identifiers, open files, recurse through
payload arcs, implement load policy, merge with local/reference opinions, or
perform full value resolution. Optional runtime direct payload asset opening
for the adapter payload inclusion scenario is owned by
`usd-composed-stage-open`.

The payload source is not the LIVERPS composition arbitrator. Generated domain
constructors must not require `ReferenceNamespaceSource` or another concrete
prior composition provider. `usd-composition-arbitrator` should consume local,
reference, payload, and other arc opinion sources and produce the final
composed namespace source for stage population.

The source exposes capabilities:

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

`partial` payload loading means the source composes direct external payload
arcs from supplied layers and direct path-only internal payloads as loaded.
Explicit unloaded state, load rules, population load masks, and payload asset
opening are outside this source; optional bounded runtime asset opening lives in
`usd-composed-stage-open`.

## Composition Rules

Payload arcs are read from supplied payload arc sites. Each site carries the
payload-bearing prim path and the source-visible `payload` listOp value. This
first contract consumes that supplied listOp value and preserves `explicit`
entries when present, otherwise `prepend` followed by `append`. Cross-layer
payload listOp composition before arc-site construction remains a later
composition contract.

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

The payload target prim maps to the payload-bearing prim path. Descendant prims
and properties below the target are mapped by replacing the target prefix with
the payload-bearing prim path.

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

References authored inside a loaded payload target subtree are expanded while
their referenced layers are already supplied. Treat these nested opinions as
payload-family contributions because the payload arc introduced that loaded
layer stack into the composed stage. If the loaded payload layer stack authors
`layerRelocates`, carry that relocate namespace mapping on the nested record:
hide relocated source paths, expose relocated target paths, suppress stale
target collisions, prune deleted sources, and remap path-valued fields through
the accumulated payload/reference plus relocate mapping.

This source returns only payload-contributed opinions. Base-source opinions are
stronger than payload opinions in full composition, but that arbitration belongs
to `usd-composition-arbitrator`. Stronger local/reference `over` specs
overriding weaker payload `def` specs is not evaluated by this payload source.

Child prim names and property names come from mapped payload specs only.

## Boundary Guards

Consume supplied payload arc sites and supplied already-opened payload layers.
Do not consume `usd-reference-namespace-source` or another concrete prior
composition provider in the payload source constructor.

Payload source runtime records must retain payload-bearing prim paths, payload
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 payload layers and field values
on supplied arc sites. 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, recursive payload-arc
expansion, payload load policy, local/reference/payload LIVERPS merging,
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 payloads contribute prim, property, and child opinions
- asset-only payloads use the payload layer `defaultPrim`
- missing payload layers fail clearly
- references inside loaded payload layers expand when their layers are supplied
- nested payload arcs inside payload layers remain deferred
- composition-arbitrator tests, not payload-source tests, should prove local or
  reference opinions remain stronger than payload opinions
- all cases in
  `goldens/unit/usd-payload-namespace-source/payload-namespace-source.json`