Azure Device Update for IoT Hub import manifest schema

Άρθρο
01/09/2025

When you import an update into Azure Device Update for Iot Hub, you also submit an associated JSON import manifest file that defines important information about the update. This article describes the schema used to create the JSON import manifest file.

To learn more about import manifest concepts and file structure, see Azure Device Update for IoT Hub import manifest. To learn how to create the file, see Prepare an update to import into Device Update for IoT Hub.

Schema

The import manifest JSON schema is hosted at SchemaStore.org and consists of the following properties. No other properties are allowed.

Property	Type	Description	Required
$schema	`string`	JSON schema reference.	No
updateId	`updateId`	Unique update identifier.	Yes
description	`string`	Optional update description. Maximum length 512 characters.	No
compatibility	`compatibility`	List of device property sets this update is compatible with.	Yes
instructions	`instructions`	Update installation instructions.	Yes
files	`file` `[0-10]`	List of update payload files. Sum of all file sizes can't exceed 2 GB. Can be empty or null if all instruction steps are reference steps.	No
manifestVersion	`string`	Import manifest schema version. Must be 5.0.	Yes
createdDateTime	`string`	Import manifest creation date and time in ISO 8601 format, for example `"2020-10-02T22:18:04.9446744Z"`.	Yes

Update object

The updateID object is a unique identifier for each update.

Property	Type	Description	Required
provider	`string`	Entity who is creating or directly responsible for the update. The provider can be a company name. Pattern: `^[a-zA-Z0-9.-]+$` Maximum length: 64 characters	Yes
name	`string`	Identifier for a class of update. The name can be a device class or model name. Pattern: `^[a-zA-Z0-9.-]+$` Maximum length: 64 characters	Yes
version	`string`	Two- to four-part dot-separated numerical version numbers. Each part must be a number between 0 and 2147483647, and leading zeroes are dropped. Pattern: `^\d+(?:\.\d+)+$` Examples: `"1.0"`, `"2021.11.8"`	Yes

No other properties are allowed.

For example:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Compatibility object

The compatibility object describes 1-5 properties of a device that this update is compatible with. Each property is a string type name-value pair. The name must be 1-32 characters long and the value must be 1-64 characters long. You can't use the same exact set of compatibility properties with more than one update provider and name combination.

For example:

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Instructions object

The instructions object provides the update installation instructions. The instructions object contains a list of steps to be performed. No other properties are allowed.

Steps can either be code to execute or pointers to other updates. A step object defaults to inline if no type value is provided.

Property	Type	Description	Required
steps	`array[1-10]`	Each element in the `steps` array must be either an inline step object or a reference step object.	Yes

For example:

{
  "instructions": {
    "steps": [
      {
        "type": "inline",
        ...
      },
      {
        "type": "reference",
        ...
      }
    ]
  }
}

Inline step object

An inline step object is an installation instruction step that performs code execution.

Property	Type	Description	Required
type	`string`	Instruction step type that performs code execution. Must be `inline`. Defaults to `inline` if no value is provided.	No
description	`string`	Optional instruction step description. Maximum length: 64 characters.	No
handler	`string`	Identity of the handler on the device that can execute this step. Pattern: `^\S+/\S+:\d{1,5}$` Minimum length: Five characters Maximum length: 32 characters Examples: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	Yes
files	`string` `[1-10]`	Names of update files defined as file objects that the agent passes to the handler. Each element length must be 1-255 characters.	Yes
handlerProperties	`inlineStepHandlerProperties`	JSON objects that the agent passes to the handler as arguments.	No

No other properties are allowed.

For example:

{
  "steps": [
    {
      "description": "pre-install script",
      "handler": "microsoft/script:1",
      "handlerProperties": {
        "arguments": "--pre-install"
      },
      "files": [
        "configure.sh"
      ]
    }
  ]
}

Reference step object

A reference step object is an installation instruction step to install another update.

Property	Type	Description	Required
type	`referenceStepType`	Instruction step type that installs another update. Must be `reference`.	Yes
description	`stepDescription`	Optional instruction step description. Maximum length: 64 characters.	No
updateId	`updateId`	Unique update identifier.	Yes

No other properties are allowed.

For example:

{
  "steps": [
    {
      "type": "reference",
      "updateId": {
        "provider": "Contoso",
        "name": "Toaster.HeatingElement",
        "version": "1.0"
      }
    }
  ]
}

Files object

Each files object is an update payload file, such as a binary, firmware, or script file, that must be unique within an update.

Property	Type	Description	Required
filename	`string`	Update payload file name. Maximum length: 255 characters	Yes
sizeInBytes	`number`	File size in number of bytes. Maximum size: 2147483648 bytes	Yes
hashes	`fileHashes`	Base64-encoded file hashes with algorithm name as key. At least SHA-256 algorithm must be specified, and additional algorithms may be specified if supported by agent. See Hashes object for details on how to calculate the hash.	Yes
relatedFiles	`relatedFile[0-4]`	Collection of files related to one or more primary payload files. For more information, see relatedFiles object.	No
downloadHandler	`downloadHandler`	Specifies how to process any related files.	Yes, if using `relatedFiles`. For more information, see downloadHandler object.

No other properties are allowed.

For example:

{
  "files": [
    {  
      "fileName": "full-image-file-name",
      "sizeInBytes": 12345,
      "hashes": {...},
      "relatedFiles": [
        {
          "fileName": "delta-from-v1-file-name",
          "sizeInBytes": 1234,
          "hashes": {
            "SHA256": "delta-from-v1-file-hash"
          },
          "properties": {...}
        }  
      ],
      "downloadHandler": {
        "id": "microsoft/delta:1"
        }
    }
  ]
}

Hashes object

The hashes object contains base64-encoded file hashes with the algorithm names as keys. At least the SHA-256 algorithm must be specified, and other algorithms may be specified if supported by the agent. For an example of how to calculate the hash correctly, see the Get-AduFileHashes function in the AduUpdate.psm1 script.

Property	Type	Description	Required
sha256	`string`	Base64-encoded file hash value using SHA-256 algorithm.	Yes

Other properties are allowed.

For example:

{
  "hashes": {
    "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
  }
}

relatedFiles object

The relatedFiles object contains a collection of files that are related to one or more primary payload files. For more information, see Use the related files feature to reference multiple update files.

Property	Type	Description	Required
filename	`string`	List of related files associated with a primary payload file.	Yes
sizeInBytes	`number`	File size in number of bytes. Maximum size: 2147483648 bytes.	Yes
hashes	`fileHashes`	Base64-encoded file hashes with algorithm name as key. For more information, see Hashes object.	Yes
properties	`relatedFilesProperties` `[0-5]`	Up to five key-value pairs, where the key is limited to 64 ASCII characters and the value is a JObject with up to 256 ASCII characters.	No

Other properties are allowed.

For example:

"relatedFiles": [
  {
    "filename": "in1_in2_deltaupdate.dat",
    "sizeInBytes": 102910752,
    "hashes": {
      "sha256": "2MIldV8LkdKenjJasgTHuYi+apgtNQ9FeL2xsV3ikHY="
    },
    "properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "YmFYwnEUddq2nZsBAn5v7gCRKdHx+TUntMz5tLwU+24="
    }
  }
],

downloadHandler object

The downloadHandler object specifies how to process any related files.

Property	Type	Description	Required
id	`string`	Identifier for `downloadHandler`. Limit of 64 ASCII characters.	Yes, if using `relatedFiles`

No other properties are allowed.

For example:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Κοινή χρήση μέσω

Azure Device Update for IoT Hub import manifest schema

Schema

Update object

Compatibility object

Instructions object

Inline step object

Reference step object

Files object

Hashes object

relatedFiles object

downloadHandler object

Σχόλια

Πρόσθετοι πόροι

Κοινή χρήση μέσω

Azure Device Update for IoT Hub import manifest schema

Schema

Update object

Compatibility object

Instructions object

Inline step object

Reference step object

Files object

Hashes object

relatedFiles object

downloadHandler object

Related content

Σχόλια

Πρόσθετοι πόροι