<!--
{
  "availability" : [
    "iOS: 16.0.0 -",
    "iPadOS: 16.0.0 -",
    "macCatalyst: -",
    "macOS: 13.0.0 -",
    "tvOS: 16.0.0 -",
    "visionOS: -",
    "watchOS: 9.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppIntents",
  "identifier" : "/documentation/AppIntents/EntityIdentifier",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "App Intents"
    ],
    "preciseIdentifier" : "s:10AppIntents16EntityIdentifierV"
  },
  "title" : "EntityIdentifier"
}
-->

# EntityIdentifier

A type that uniquely identifies a specific instance of an app entity.

```
struct EntityIdentifier
```

## Overview

The value used should be unique across all entities of the given type. Entities which are
relevant across executions of the application should have stable identifiers that persist
across executions.

Entities, by default, conform to the `Identifiable` protocol. Use a type for
the `id` that conforms to [`EntityIdentifierConvertible`](/documentation/AppIntents/EntityIdentifierConvertible). Default implementations for
`String`, `UUID` and `Int` are provided.

For example:

```
struct Song: AppEntity {
    let id = UUID()
}
```

## Cross-Device Stable Identifiers

For entities that adopt `_SyncableEntity`, the framework automatically extracts stable identifiers
for cross-device session syncing:

- **Passthrough case**: If your entity’s ID is already stable across devices (like server UUIDs),
  just adopt `_SyncableEntity` with no other changes. The framework uses your ID as both
  the local and stable identifier.
- **Mapped case**: If your entity has different local and stable identifiers, use
  `_SyncableEntityIdentifier` as your ID type. The framework extracts the stable ID
  from the wrapper.
- **Custom identifier case**: If your entity uses a custom ID type that conforms to
  `_SyncableEntityIdentifierProviding`, the framework extracts the stable ID via the
  protocol’s `stableIdentifierString` property.

Apps never interact with `EntityIdentifier.stableIdentifier` directly - they work with their entity’s
ID type (plain types like `UUID`, `_SyncableEntityIdentifier` for mapped IDs, or custom types
conforming to `_SyncableEntityIdentifierProviding`).

The stable identifier is NOT used for equality or hashing - two `EntityIdentifier` instances are
equal if they have the same type and local identifier, regardless of stable identifier value.

## Topics

### Creating an entity identifier

[`init(for:)`](/documentation/AppIntents/EntityIdentifier/init(for:))

Creates an identifier for the specified entity.

[`init(for:identifier:)`](/documentation/AppIntents/EntityIdentifier/init(for:identifier:))

Creates an `EntityIdentifier` representing an instance of the specified entity type backed
by the specified identifier value.

[`init(activityIdentifier:)`](/documentation/AppIntents/EntityIdentifier/init(activityIdentifier:))

### Getting the identifier details

[`identifier`](/documentation/AppIntents/EntityIdentifier/identifier)

Value uniquely identifying the entity instance within its type.

[`entityType`](/documentation/AppIntents/EntityIdentifier/entityType)

The type of `AppEntity` represented by this identifier

[`valueMaximumLength`](/documentation/AppIntents/EntityIdentifier/valueMaximumLength)

Maximum allowed length for the `identifier` value.
This is a constraint imposed by the system and thus forces us to
truncate the identifier if it exceeds the maximum length.


---

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)