<!--
{
  "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/Relationship/Spec",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "USDKit"
    ],
    "preciseIdentifier" : "s:6USDKit7USDPrimV12RelationshipV4SpecV"
  },
  "title" : "USDPrim.Relationship.Spec"
}
-->

# USDPrim.Relationship.Spec

A handle to a relationship definition stored in a layer.

```
struct Spec
```

## Overview

Relationships store connections to other prims (target paths) rather
than typed values. Used for scene linkages like material bindings,
collection membership, and proxy references.

## Topics

### Initializers

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

Creates an empty (invalid) relationship spec handle.

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

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

[`init?(layer: USDLayer, relationshipPath: USDLayer.Path, variability: USDPrim.Property.Variability, isCustom: Bool)`](/documentation/USDKit/USDPrim/Relationship/Spec/init(layer:relationshipPath:variability:isCustom:))

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

[`init?(owner: USDPrim.Spec, name: USDToken, variability: USDPrim.Property.Variability, isCustom: Bool)`](/documentation/USDKit/USDPrim/Relationship/Spec/init(owner:name:variability:isCustom:))

Creates a new relationship spec under the given prim spec.

### Instance Properties

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

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

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

The custom data dictionary authored on this relationship.

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

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

[`var isCustom: Bool`](/documentation/USDKit/USDPrim/Relationship/Spec/isCustom)

Whether this relationship was authored as `custom`.

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

The relationship’s local name.

[`var noLoadHint: Bool`](/documentation/USDKit/USDPrim/Relationship/Spec/noLoadHint)

Hint to the runtime to skip loading payloads on targeted prims.
Default: `false`.

[`var owner: USDLayer.Spec?`](/documentation/USDKit/USDPrim/Relationship/Spec/owner)

The spec that contains this relationship.

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

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

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

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

### Instance Methods

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

Removes `key` from the asset info dictionary.

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

Removes `key` from the custom data dictionary.

[`func clearTargetPaths()`](/documentation/USDKit/USDPrim/Relationship/Spec/clearTargetPaths())

Clears all authored target paths on this relationship.

[`func removeTarget(USDLayer.Path, preservingOrder: Bool)`](/documentation/USDKit/USDPrim/Relationship/Spec/removeTarget(_:preservingOrder:))

Removes an authored target path.

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

Sets the relationship’s name.

[`func replaceTarget(USDLayer.Path, with: USDLayer.Path)`](/documentation/USDKit/USDPrim/Relationship/Spec/replaceTarget(_:with:))

Replaces an authored target path with a new path.

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

Sets `key` in the asset info dictionary to `value`. Read the
full dictionary via `field("assetInfo")` from FieldCollection.

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

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

## Relationships

### Conforms To

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

[`SymmetryCollection`](/documentation/USDKit/USDPrim/Property/Spec/SymmetryCollection)

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

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

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

[`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)