> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Custom Declarations Library Item

> Configure the Custom Declarations Library Item in Iru Endpoint. Deploy Apple declarative device management configurations that do not have a built-in Library Item.

This Library Item is available for Mac computers, iPhone, iPad, Apple TV, and Apple Vision Pro

When Apple releases a new declarative device management (DDM) configuration, you can deploy it with the **Custom Declarations** Library Item in place of a dedicated Library Item. Add the declaration JSON, choose where it installs, and assign the Library Item with a Blueprint. Iru checks the JSON against Apple's schemas, delivers it to devices, and shows the status of each declaration. If Iru later adds a dedicated Library Item for the same configuration, a **Recommendation** finding in the validation panel links to it.

Iru validates the structure of your declarations. It does not test how Apple's software behaves when a device applies them. Test every declaration on a pilot device before you assign it widely.

> [!NOTE]
>
> For background on declarations, see Apple's [declarative device management documentation](https://developer.apple.com/documentation/devicemanagement/declarative-management).

## Create a Custom Declarations Library Item

Have the declaration JSON ready before you start. To deploy a `.mobileconfig` profile instead, use a [Custom Profile](https://docs.iru.com/en/endpoint/library/library-items-profiles/custom-profiles-overview.md).

**Upload file** and **Manual entry** are alternatives. Use one option to add the declaration JSON, not both.

**1. Open the Library**

Go to **Library**.

**2. Add the Library Item**

Select **Add Library Item**, then select **Custom Declarations**.

**3. Set the Library Item title**

Enter a title for the Library Item.

**4. Select Installs on**

Under **Installs on**, select the platforms this Library Item applies to. Iru sends each declaration only to the selected platforms that support its type.

**5. Assign Assignment Maps**

Assign the Assignment Maps that should receive this Library Item. See [Configuring Blueprints](https://docs.iru.com/en/endpoint/getting-started/blueprints-and-library/configuring-blueprints.md).

**6. Option 1: Upload file**

Use this option if your declaration is saved as a `.json` file. Under **Settings**, select **Upload file**. Drag the file onto the page, or select **choose file**. Iru loads the file into the editor and checks it the same way. The file itself is not stored. See [Declaration JSON](#declaration-json).

![Custom Declarations Settings with Upload file selected. Drag a declaration JSON onto the page or choose a file.](https://mintcdn.com/iru/EIZIDeW6fQDKik27/assets/media/images/iru-custom-declarations-upload-file.jpg?fit=max\&auto=format\&n=EIZIDeW6fQDKik27\&q=85\&s=98ee1608c139da55421624e8865d62bf)

**7. Option 2: Manual entry**

Use this option to paste the JSON yourself. Under **Settings**, select **Manual entry**, then paste the JSON into **Enter JSON**. **Validation** updates as you type. See [Declaration JSON](#declaration-json).

![Custom Declarations Settings with Manual entry selected. Enter JSON on the left and review Validation on the right.](https://mintcdn.com/iru/EIZIDeW6fQDKik27/assets/media/images/iru-custom-declarations-manual-entry.jpg?fit=max\&auto=format\&n=EIZIDeW6fQDKik27\&q=85\&s=b19cb9b90b5c784f5b92797e14b06fc4)

**8. Review validation**

Review the findings in **Validation** and fix anything marked **Error**. See [Validation findings](#validation-findings).

**9. Save**

Select **Save**.

## Settings

### Declaration JSON

Paste or upload one or more Apple configuration declarations. Each declaration needs a `Type` and a `Payload`. You can add a single declaration or a list. This example is a list with one Safari bookmarks declaration:

```json theme={null}
[
  {
    "Type": "com.apple.configuration.safari.bookmarks",
    "Payload": {
      "ManagedBookmarks": [
        {
          "Title": "Iru Resources",
          "Bookmarks": [
            {
              "URL": "https://www.iru.com",
              "Title": "Iru"
            },
            {
              "URL": "https://www.iru.com/updates/all",
              "Title": "Product Updates"
            },
            {
              "URL": "https://www.iru.com/legal",
              "Title": "Legal and Privacy"
            }
          ],
          "GroupIdentifier": "Group1"
        }
      ]
    },
    "Identifier": "EB13EE2B-5D63-4EBA-810F-5B81D07F5019"
  }
]
```

* One Library Item holds 1 to 100 declarations, up to 128 KB in total.
* Each declaration gets its own activation, so one failure does not block the others.
* Iru accepts configuration declarations (`com.apple.configuration.*`). It does not accept activations or management declarations.
* `Identifier` is optional. If you leave it out, Iru assigns one. Each `Identifier` must be unique within the Library Item.
* If you include a `ServerToken`, Iru removes it on save and computes its own.
* You can use [global variables](https://docs.iru.com/en/endpoint/library/library-items-profiles/global-variables.md), such as `$EMAIL` or `$ASSET_TAG`. Iru resolves them for each device. A variable with no value becomes empty text.

### Channel

Iru chooses the device or user channel for each declaration from Apple's schema. Only Mac computers and Shared iPad have a user channel.

### Validation findings

Iru checks your declarations as you edit, shortly after you stop typing, and again when you save. Findings appear in **Validation**, tied to the line they affect. During an Apple beta cycle, the panel also shows a beta tab.

Each finding has a severity:

* **Error**: Apple would reject the declaration. For example, a value has the wrong type, or a required key is missing.
* **Warning**: The declaration may still work, but Iru cannot confirm it. For example, a key or type is unknown, or it is not supported on every selected platform.
* **Info**: Iru changes or holds something. For example, Iru removes a `ServerToken`, or does not deliver an asset.
* **Recommendation**: Iru has a built-in Library Item for this declaration type. The finding links to it.

Findings do not block a save, because Iru's copy of Apple's schemas can lag behind new releases. These problems do block a save:

* Invalid JSON
* A declaration with no `Type` or `Payload`
* A declaration kind Iru does not support
* A duplicate `Identifier`
* No platform selected under **Installs on**
* More than 100 declarations, or more than 128 KB

## Considerations

> [accordion] Assets are not delivered
>
> You can save asset declarations (`com.apple.asset.*`), but Iru does not deliver them. A configuration that references one of those assets is not delivered either. Both show as **Incompatible** on the device. Support for DDM assets will be added in a future release.

> [accordion] Profiles are not accepted
>
> Custom Declarations only deploys declarations. To deploy a `.mobileconfig` file, use a [Custom Profile](https://docs.iru.com/en/endpoint/library/library-items-profiles/custom-profiles-overview.md).

> [accordion] Some declarations show Incompatible
>
> If a device cannot take a declaration, Iru does not send it and marks it **Incompatible** with a reason. Reasons include an unsupported OS or platform, an asset, and a type that Apple does not allow on Shared iPad. Iru delivers the declaration once the device can take it.

> [accordion] Status appears for each declaration
>
> Open a device's status to see each declaration listed by its `Identifier`. The Library Item's overall status follows one rule: if any declaration has an **Error**, the item shows **Error**. Otherwise, if any is **Pending**, the item shows **Pending**. Otherwise, it shows **Pass**. When a declaration fails, Iru shows Apple's error text.

> [accordion] A valid declaration can stay Pending
>
> A declaration that Apple accepts but marks inactive shows **Pending**, with Apple's reasons. If the reason is an `Error.*` code, the declaration shows **Error**.

> [accordion] Editing resends only what changed
>
> When you edit one declaration, Iru resends only that declaration. Reordering or editing other entries does not change the rest.

> [accordion] Setup Assistant
>
> During Automated Device Enrollment, Setup Assistant waits until all declarations are active, or until any one fails. It does not wait on **Incompatible** declarations. Devices whose OS cannot run declarative device management receive the Library Item over MDM instead.

> [accordion] Removing a declaration removes it from devices
>
> Removing a declaration, or unassigning the Library Item, removes it from devices. Iru asks you to confirm. On very large tenants, removal runs in batches, so devices can take several minutes to clear.

> [accordion] Identifier collisions across Library Items
>
> Iru checks that each `Identifier` is unique within a Library Item. It does not detect the same `Identifier` on another Library Item. Keep Identifiers distinct between Library Items.

## Best practices

**1. Test on a pilot device**

Iru checks structure, not how Apple's software behaves. Test every declaration on a pilot device before you assign it widely.

**2. Use a built-in Library Item**

When a **Recommendation** finding links to a built-in Library Item for the same configuration, use that Library Item.

**3. Use clear Identifiers**

Iru labels status by `Identifier`. Descriptive names make troubleshooting faster.

**4. Group related declarations**

Put declarations that belong together in one Library Item, up to 100.

**5. Fix Error findings before you assign**

Findings do not block a save, but an **Error** usually means a device will reject the declaration.

**6. Check status after you assign**

Open the device status and confirm each declaration shows **Pass**.

## Troubleshooting

> [accordion] A declaration shows Incompatible
>
> Iru did not send the declaration. Open the device status and read the reason.
>
> **Possible causes:**
>
> * The device OS or platform does not support the declaration type.
> * The declaration is an asset, or a configuration references an asset.
> * The type is not allowed on Shared iPad.
>
> **Solutions:**
>
> * Update the device to a supported OS, or remove the declaration from the Library Item.
> * Remove asset references.

> [accordion] The Library Item stays Pending
>
> **Possible causes:**
>
> * The device has not checked in or reported status yet.
> * Apple accepted the declaration and marked it inactive.
>
> **Solutions:**
>
> * Confirm the device is online and has checked in.
> * Open the device status and read Apple's reasons for the declaration.

> [accordion] The Library Item shows Error
>
> **Possible causes:**
>
> * A declaration has a wrong value, a missing key, or a value outside Apple's allowed range.
> * Apple reported an `Error.*` reason.
>
> **Solutions:**
>
> * Open the device status, find the declaration by `Identifier`, and read Apple's error text.
> * Fix the declaration and save. Iru resends only what changed.

> [accordion] You cannot save the Library Item
>
> **Possible causes:**
>
> * The JSON is invalid.
> * A declaration has no `Type` or `Payload`.
> * Two declarations share an `Identifier`.
> * No platform is selected under **Installs on**.
> * The Library Item has more than 100 declarations or is larger than 128 KB.
> * The text is larger than 2 MB.
>
> **Solutions:**
>
> * Read the message in **Validation** and fix the line it points to.
> * If the text is larger than 2 MB, reduce it below the limit. Iru refuses it immediately and shows its size.

> [accordion] Validation could not check the declarations
>
> **Possible causes:**
>
> * The validation check did not complete.
>
> **Solutions:**
>
> * Wait a moment and edit the JSON again to run the check.
> * If the declarations are valid, you can still save.

> [accordion] A .mobileconfig file is not accepted
>
> **Possible causes:**
>
> * The file is a `.mobileconfig` profile, not declaration JSON.
>
> **Solutions:**
>
> * Deploy the profile with a [Custom Profile](https://docs.iru.com/en/endpoint/library/library-items-profiles/custom-profiles-overview.md).

## Related Articles

> [card] [Library Overview](https://docs.iru.com/en/endpoint/library/library-items-profiles/library-overview.md)
>
> Curate, create, and manage Library Items and add them to Blueprints

> [card] [Custom Profiles Overview](https://docs.iru.com/en/endpoint/library/library-items-profiles/custom-profiles-overview.md)
>
> Deploy a .mobileconfig profile when a declaration is not the right payload

> [card] [Configuring Blueprints](https://docs.iru.com/en/endpoint/getting-started/blueprints-and-library/configuring-blueprints.md)
>
> Assign Library Items to devices with a Blueprint

> [card] [Global Variables](https://docs.iru.com/en/endpoint/library/library-items-profiles/global-variables.md)
>
> Insert device and assigned user values into a declaration


## Related topics

- [Custom Profiles Overview](https://docs.iru.com/en/endpoint/library/library-items-profiles/custom-profiles-overview.md)
- [Managing Library](https://docs.iru.com/en/endpoint/getting-started/blueprints-and-library/managing-library.md)
- [Global Variables](https://docs.iru.com/en/endpoint/library/library-items-profiles/global-variables.md)