Skip to main content
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.
For background on declarations, see Apple’s declarative device management documentation.

​
Create a Custom Declarations Library Item

Have the declaration JSON ready before you start. To deploy a .mobileconfig profile instead, use a Custom Profile. 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.
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.
Custom Declarations Settings with Upload file selected. Drag a declaration JSON onto the page or choose a file.
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.
Custom Declarations Settings with Manual entry selected. Enter JSON on the left and review Validation on the right.
8

Review validation

Review the findings in Validation and fix anything marked Error. See 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:
  • 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, 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

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.
Custom Declarations only deploys declarations. To deploy a .mobileconfig file, use a Custom Profile.
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.
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.
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.
When you edit one declaration, Iru resends only that declaration. Reordering or editing other entries does not change the rest.
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.
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.
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

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.
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.
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.
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.
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.
Possible causes:
  • The file is a .mobileconfig profile, not declaration JSON.
Solutions:

Library Overview

Curate, create, and manage Library Items and add them to Blueprints

Custom Profiles Overview

Deploy a .mobileconfig profile when a declaration is not the right payload

Configuring Blueprints

Assign Library Items to devices with a Blueprint

Global Variables

Insert device and assigned user values into a declaration