<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "USDKit",
  "identifier" : "/documentation/USDKit/USDPrim/Spec",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "USDKit"
    ],
    "preciseIdentifier" : "s:6USDKit7USDPrimV4SpecV"
  },
  "title" : "USDPrim.Spec"
}
-->

# USDPrim.Spec

A handle to a prim definition stored in a layer.

```
struct Spec
```

## Overview

`USDPrim.Spec` is a struct but acts as a handle into data owned by a
[`USDLayer`](/documentation/USDKit/USDLayer), much like [`USDPrim`](/documentation/USDKit/USDPrim) is a handle into a [`USDStage`](/documentation/USDKit/USDStage).
Mutations write through to the layer rather than to the spec value
itself, so property setters and methods on this type are non-mutating.

## Topics

### Initializers

[`init()`](/documentation/USDKit/USDPrim/Spec/init())

Creates an empty (invalid) prim spec handle.

[`init(USDPrim.PseudoRootSpec)`](/documentation/USDKit/USDPrim/Spec/init(_:)-7yaap)

Widens a `USDPrim.PseudoRootSpec` into a generic `USDPrim.Spec`,
exposing the full prim-spec API (children, properties, metadata).

[`init?(USDLayer.Spec)`](/documentation/USDKit/USDPrim/Spec/init(_:)-9poa6)

Narrows an untyped [`USDLayer.Spec`](/documentation/USDKit/USDLayer/Spec) to a `USDPrim.Spec`.

[`init?(layer: USDLayer, primPath: USDLayer.Path)`](/documentation/USDKit/USDPrim/Spec/init(layer:primPath:))

Creates a prim spec at the given path in the layer, authoring
intermediate ancestor prim specs as `over`s where needed.

[`init?(parentLayer: USDLayer, name: USDToken, specifier: USDPrim.Specifier, typeName: String)`](/documentation/USDKit/USDPrim/Spec/init(parentLayer:name:specifier:typeName:))

Creates a new top-level prim spec under the given layer.

[`init?(parentPrimSpec: USDPrim.Spec, name: USDToken, specifier: USDPrim.Specifier, typeName: String)`](/documentation/USDKit/USDPrim/Spec/init(parentPrimSpec:name:specifier:typeName:))

Creates a new child prim spec under the given parent prim spec.

### Instance Properties

[`var assetInfo: Dictionary<String, USDValue>`](/documentation/USDKit/USDPrim/Spec/assetInfo)

The asset info dictionary authored on this prim.

[`var attributes: [USDPrim.Attribute.Spec]`](/documentation/USDKit/USDPrim/Spec/attributes)

All attribute specs on this prim.

[`var children: [USDPrim.Spec]`](/documentation/USDKit/USDPrim/Spec/children)

The child prim specs in authoring order.

[`var childrenOrder: [USDToken]?`](/documentation/USDKit/USDPrim/Spec/childrenOrder)

The authored override for child ordering, or `nil` if no order is
authored. When non-nil, this list controls the order in which child
prim specs appear during composition.

[`var comment: String?`](/documentation/USDKit/USDPrim/Spec/comment)

The authored user comment, or `nil` if not authored.

[`var customData: Dictionary<String, USDValue>`](/documentation/USDKit/USDPrim/Spec/customData)

The custom data dictionary authored on this prim.

[`var documentation: String?`](/documentation/USDKit/USDPrim/Spec/documentation)

The authored documentation, or `nil` if not authored.

[`var inherits: [USDLayer.Path]?`](/documentation/USDKit/USDPrim/Spec/inherits)

The authored inherit paths, or `nil` if none authored.

[`var isActive: Bool?`](/documentation/USDKit/USDPrim/Spec/isActive)

Whether this prim is active in composition, or `nil` if not authored.

[`var isInstanceable: Bool?`](/documentation/USDKit/USDPrim/Spec/isInstanceable)

Whether this prim is marked as an instance, or `nil` if not authored.

[`var kind: USDToken?`](/documentation/USDKit/USDPrim/Spec/kind)

The prim’s kind, or `nil` if not authored.

[`var name: USDToken`](/documentation/USDKit/USDPrim/Spec/name)

The prim’s local name.

[`var parent: USDPrim.Spec?`](/documentation/USDKit/USDPrim/Spec/parent)

The parent prim spec, or `nil` if this is a top-level prim spec.

[`var payloads: [USDPrim.Payload]?`](/documentation/USDKit/USDPrim/Spec/payloads)

The authored payloads on this prim, or `nil` if none authored.

[`var permission: USDLayer.Permission`](/documentation/USDKit/USDPrim/Spec/permission)

The prim’s permission level (public, restricted, private).

[`var prefix: String?`](/documentation/USDKit/USDPrim/Spec/prefix)

The authored prefix, or `nil` if not authored.

[`var prefixSubstitutions: Dictionary<String, USDValue>`](/documentation/USDKit/USDPrim/Spec/prefixSubstitutions)

The prefix substitutions dictionary.

[`var properties: [USDPrim.Property.Spec]`](/documentation/USDKit/USDPrim/Spec/properties)

All property specs (attributes and relationships) on this prim.

[`var propertyOrder: [USDToken]?`](/documentation/USDKit/USDPrim/Spec/propertyOrder)

The authored override for property ordering, or `nil` if no order is
authored.

[`var pseudoRoot: USDPrim.Spec?`](/documentation/USDKit/USDPrim/Spec/pseudoRoot)

The pseudo-root prim spec at `/` in this spec’s layer.

[`var references: [USDPrim.Reference]?`](/documentation/USDKit/USDPrim/Spec/references)

The authored references on this prim, or `nil` if none authored.

[`var relationships: [USDPrim.Relationship.Spec]`](/documentation/USDKit/USDPrim/Spec/relationships)

All relationship specs on this prim.

[`var relocates: USDLayer.RelocatesMap?`](/documentation/USDKit/USDPrim/Spec/relocates)

The relocates map authored on this prim, or `nil` if none authored.

[`var specializes: [USDLayer.Path]?`](/documentation/USDKit/USDPrim/Spec/specializes)

The authored specializes paths, or `nil` if none authored.

[`var specifier: USDPrim.Specifier`](/documentation/USDKit/USDPrim/Spec/specifier)

How this prim definition composes — `def`, `over`, or `class`.

[`var suffix: String?`](/documentation/USDKit/USDPrim/Spec/suffix)

The authored suffix, or `nil` if not authored.

[`var suffixSubstitutions: Dictionary<String, USDValue>`](/documentation/USDKit/USDPrim/Spec/suffixSubstitutions)

The suffix substitutions dictionary.

[`var symmetricPeer: String?`](/documentation/USDKit/USDPrim/Spec/symmetricPeer)

The symmetric peer path, or `nil` if not authored.

[`var symmetryArguments: Dictionary<String, USDValue>`](/documentation/USDKit/USDPrim/Spec/symmetryArguments)

The symmetry arguments dictionary authored on this prim.

[`var symmetryFunction: USDToken?`](/documentation/USDKit/USDPrim/Spec/symmetryFunction)

The symmetry function token, or `nil` if not authored.

[`var typeName: USDToken`](/documentation/USDKit/USDPrim/Spec/typeName)

The prim’s type name.

[`var variantSelections: [USDToken : USDToken]`](/documentation/USDKit/USDPrim/Spec/variantSelections)

All authored variant selections, keyed by variant set name.

[`var variantSetNames: [USDToken]`](/documentation/USDKit/USDPrim/Spec/variantSetNames)

The names of variant sets defined on this prim.

[`var variantSets: [USDToken : USDPrim.VariantSetSpec]`](/documentation/USDKit/USDPrim/Spec/variantSets)

The variant sets authored on this prim, keyed by name.

### Instance Methods

[`func appendChild(USDPrim.Spec)`](/documentation/USDKit/USDPrim/Spec/appendChild(_:))

Appends `child` to the end of the children list.

[`func attribute(at: USDLayer.Path) -> USDPrim.Attribute.Spec?`](/documentation/USDKit/USDPrim/Spec/attribute(at:))

Returns the attribute spec at the given path within this prim.

[`func blockVariantSelection(for: USDToken)`](/documentation/USDKit/USDPrim/Spec/blockVariantSelection(for:))

Authors an explicit “no selection” for the given variant set.

[`func clearAssetInfo(String)`](/documentation/USDKit/USDPrim/Spec/clearAssetInfo(_:))

Removes `key` from the asset info dictionary.

[`func clearCustomData(String)`](/documentation/USDKit/USDPrim/Spec/clearCustomData(_:))

Removes `key` from the custom data dictionary.

[`func clearInherits()`](/documentation/USDKit/USDPrim/Spec/clearInherits())

Clears all authored inherit paths on this prim.

[`func clearPayloads()`](/documentation/USDKit/USDPrim/Spec/clearPayloads())

Clears all authored payloads on this prim.

[`func clearReferences()`](/documentation/USDKit/USDPrim/Spec/clearReferences())

Clears all authored references on this prim.

[`func clearRelocates()`](/documentation/USDKit/USDPrim/Spec/clearRelocates())

Clears all authored relocates on this prim.

[`func clearSpecializes()`](/documentation/USDKit/USDPrim/Spec/clearSpecializes())

Clears all authored specializes paths on this prim.

[`func clearSymmetryArgument(String)`](/documentation/USDKit/USDPrim/Spec/clearSymmetryArgument(_:))

Removes `name` from the symmetry arguments dictionary.

[`func clearVariantSelection(for: USDToken)`](/documentation/USDKit/USDPrim/Spec/clearVariantSelection(for:))

Clears the variant selection for the given variant set.

[`func insertChild(USDPrim.Spec, at: Int)`](/documentation/USDKit/USDPrim/Spec/insertChild(_:at:))

Inserts `child` into the children list at `index`.

[`func prim(at: USDLayer.Path) -> USDPrim.Spec?`](/documentation/USDKit/USDPrim/Spec/prim(at:))

Returns the prim spec at the given path within this prim.

[`func property(at: USDLayer.Path) -> USDPrim.Property.Spec?`](/documentation/USDKit/USDPrim/Spec/property(at:))

Returns the property spec at the given path within this prim.

[`func relationship(at: USDLayer.Path) -> USDPrim.Relationship.Spec?`](/documentation/USDKit/USDPrim/Spec/relationship(at:))

Returns the relationship spec at the given path within this prim.

[`func removeChild(USDPrim.Spec)`](/documentation/USDKit/USDPrim/Spec/removeChild(_:))

Removes `child` from the children list. No-op if `child` is not a
child of this spec.

[`func removeProperty(USDPrim.Property.Spec)`](/documentation/USDKit/USDPrim/Spec/removeProperty(_:))

Removes the given property spec from this prim.

[`func removeVariantSet(USDToken)`](/documentation/USDKit/USDPrim/Spec/removeVariantSet(_:))

Removes the variant set with the given name.

[`func rename(to: USDToken) throws`](/documentation/USDKit/USDPrim/Spec/rename(to:))

Sets the prim’s name.

[`func setAssetInfo(String, to: USDValue)`](/documentation/USDKit/USDPrim/Spec/setAssetInfo(_:to:))

Sets `key` in the asset info dictionary to `value`.

[`func setCustomData(String, to: USDValue)`](/documentation/USDKit/USDPrim/Spec/setCustomData(_:to:))

Sets `key` in the custom data dictionary to `value`.

[`func setSymmetryArgument(String, to: USDValue)`](/documentation/USDKit/USDPrim/Spec/setSymmetryArgument(_:to:))

Sets `name` in the symmetry arguments dictionary to `value`.

[`func setVariantSelection(for: USDToken, to: USDToken)`](/documentation/USDKit/USDPrim/Spec/setVariantSelection(for:to:))

Sets the variant selection for the given variant set.

[`func spec(at: USDLayer.Path) -> USDLayer.Spec?`](/documentation/USDKit/USDPrim/Spec/spec(at:))

Returns the spec at the given path within this prim.

[`func variantNames(in: USDToken) -> [USDToken]`](/documentation/USDKit/USDPrim/Spec/variantNames(in:))

Returns the variant names available in the given variant set.

[`func variantSelection(for: USDToken) -> USDToken?`](/documentation/USDKit/USDPrim/Spec/variantSelection(for:))

Returns the authored variant selection for the given variant set.

### Type Methods

[`static func isValidName(USDToken) -> Bool`](/documentation/USDKit/USDPrim/Spec/isValidName(_:))

Returns a Boolean value that indicates whether `name` is a valid
prim name.

## Relationships

### Conforms To

[`Copyable`](/documentation/Swift/Copyable)

[`Equatable`](/documentation/Swift/Equatable)

[`Escapable`](/documentation/Swift/Escapable)

[`MetadataCollection`](/documentation/USDKit/USDLayer/Spec/MetadataCollection)

[`FieldCollection`](/documentation/USDKit/USDLayer/Spec/FieldCollection)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)