identity

identity

A unique constraint on a combination of fields within a store resource. Identities enforce that no two records can have the same values for the specified field set. Compiles to a unique index in the underlying database and an Ash Framework identity at runtime.

When to use

Use identity when you need to:

• Enforce uniqueness on a single field (e.g., email addresses)
• Enforce uniqueness on a combination of fields (e.g., one entry per user per day)
• Create lookup keys for upsert operations
• Prevent duplicate records from being inserted

If your resource has a natural key (a field or combination of fields that uniquely identifies a record besides the primary key), declare it as an identity.

Syntax

resource <resource_name>
  identity <identity_name>: [<field1>, <field2>, ...]

Parameters

Parameter	Required	Description
identity_name	Yes	Bare identifier naming this constraint. Used in error messages and upsert references.
fields	Yes	List of field names that together must be unique.

Examples

Single-field uniqueness

resource user
  id as uuid, is primary_key
  email as text, is required
  username as text, is required
  timestamps

  identity unique_email: [email]
  identity unique_username: [username]

Each identity creates a separate uniqueness constraint. If a create or update action would result in a duplicate email or duplicate username, the action fails with a validation error.

Composite uniqueness

resource daily_metric
  id as uuid, is primary_key
  metric_name as text, is required
  date as date, is required
  value as decimal
  timestamps

  identity one_per_day: [metric_name, date]

The one_per_day identity ensures that no two records share the same metric_name and date combination. This prevents duplicate data points for the same metric on the same day.

Uniqueness across relationships

resource membership
  id as uuid, is primary_key
  user_id as uuid, is required
  org_id as uuid, is required
  role as text, default: "member"
  timestamps

  belongs_to user: user
  belongs_to org: organization
  identity one_membership: [user_id, org_id]

A user can only have one membership per organization. Attempting to create a second membership for the same user-org pair fails.

Governance

Identity constraints are structural declarations and do not involve runtime governance checks. They are enforced at the database level. If a create or update action violates an identity constraint, the action returns a validation error. The failed attempt is still recorded in the behavioral ledger.

Translations

Language	Keyword
English	identity
Spanish	identidad
French	identite
German	Eindeutigkeit
Japanese	一意性
Chinese	唯一性
Korean	식별

See also

• resource - Resource declarations
• create - Create actions (identities prevent duplicate inserts)
• update - Update actions (identities prevent duplicate values)
• field types - Field type reference