---
title: li-unique-id
description: "Unique IDs and handles."
---
Added in: [`release-2024-11`](/operations/releases/release-2024-11/)

## Supported Features

| Feature | Supported |
| ------- | :-------: |
| Document | ✔ |
| Media | ✗ |
| Include | ✗ |
| Document Creation Flow | ✔ |
| Push Message | ✗ |
| Usage Log | ✗ |
| Table Dashboard | ✔ |
| Display Filter | ✗ |
| Search Indexing | ✔ |
| System Metadata | ✗ |
| Planning System | ✗ |
| Webhook Conditions | ✔ |

## Description

The `li-unique-id` plugin is ideal for managing user-defined IDs or handles where uniqueness among values is required. The user interface is similar to an [`li-text`](/reference/document/metadata/plugins/li-text/llms.txt) field, but it includes additional validation properties:

- **Uniqueness**: Ensures uniqueness among values within the same `uniquenessScope` per project.
  > [!WARNING]
> The `uniquenessScope` must not be updated, as doing so would break the uniqueness validation for new values. Changing it requires a manual database migration.
- **Format**: Enforces the accepted input format using a regular expression.
- **Required**: Ensures that a value is provided.

These validations are enforced only when publishing a document, meaning that uniqueness is guaranteed only for published values.

> [!NOTE]
> Scheduled publishing may fail if another document has claimed the unique value in the meantime. Use scheduled publishing with `li-unique-id` properties carefully to avoid conflicts.

### Fetch Documents by `li-unique-id`

Deliveries can query the public API to find documents using their `li-unique-id` metadata property. Unlike document IDs, this approach allows the same identifier to be used across different environments (e.g., staging, production). When querying with the key `metadata.<handle>.id` and the value `<uniquenessScope>.<uniqueId>`, the `li-unique-id` metadata plugin ensures a single matching result.

```js
const filters = JSON.stringify([
  {key: 'metadata.name.id', term: 'menu:main'}
])
const response = await fetch(`api/2026-05/publications/search?filters=${filters}`)
```


## Storage Format

```js
<String>
```

## Content Type Config

```js
{
  handle: 'myContentType',
  // ...
  metadata: [
    {
      handle: 'name'
      type: 'li-unique-id',
      config: {
        index: true,                // default: false
        hideFromForm: false,        // default: false
        required: true,             // default: false
        requiredErrorMessage: '',   // default: "The field '{label}' is required"
        // Regular expression the value must match
        regex: '^[a-zA-Z0-9\\-]+$', // default: undefined
        regexErrorMessage: '',      // default: "{label} does not match the required format"
        // Defines the scope within which the value must be unique. Uniqueness
        // is enforced across all values sharing the same uniquenessScope
        uniquenessScope: 'menu'     // required, must not be updated
      },
      ui: {
        label: 'Name',              // default: "{handle}"
        config: {
          placeholder: 'Name',      // default: "{label}"
          readOnly: true            // default: false
        }
      }
    }
    // ...
  ]
}
```