The Software Package file format describes a standard format to share files for the software update. This enables Update Clients to use software from different vendors (i.e., it supports identification of the package, compatibility with the device, storage of the deployment and of supplementary files).

The Software Package is shared as a single ZIP file with all the content described in this section. The recommended file extension is “.uadipkg”. In some cases, parts of the ZIP file can be removed. For example, to retrieve just a lean metadata-only package with information about available updates without having to download many full Software Packages. Another example is removing the SUPPLEMENT folder to make the package smaller if the entire Software Package is deployed to the device.

On the root level, the Software Package can have the following folders:

The optional CONTENT folder holds the files or folders that are transferred to the device. The content of this folder is defined by the author of the Software Package. For Cached-Loading and Direct-Loading, this folder can contain a single file that shall be transferred to the device. Alternatively, it can contain multiple files, if the entire Software Package is sent to the device (see use case 8.2.2.14).

The mandatory META folder holds the Software Package’s metadata. It shall at least have the file package_metadata.json. This file describes what’s in the Software Package and to which components it is compatible (see use case 8.2.2.16).

The optional SUPPLEMENT folder can contain supplementary documents for use by the Update Client. These can include license details, release notes, or manuals related to the software. An Update Client can present them to the user as part of the software update (see use case 8.2.2.19).

The optional META-INF folder contains the digital signatures of the Software Package (see 8.7.4 8.2.2.20, 8.2.2.21).

In case of a Solution Package the optional SUBPACKAGES folder contains the content of the Software Packages that belong to the solution (see use case 8.2.2.22).

The package metadata file describes the identity of the Software Package, the target for the installation, the compatibility to the device and optionally the usage of individual files within the Software Package. The package_metadata.json is stored in the META folder.

The JSON schema for the package_metadata.json file associated with this version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/&v=1.05.0

The JSON schema associated with the latest version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/

The JSON schema follows the conventions for the Compact DataEncoding defined in OPC 10000-6.

The elements of the JSON schema are described in Table 120, Table 124, Table 126, Table 128, Table 130, Table 132, Table 134, Table 136, Table 138 and Table 140.

A Software Package is uniquely defined with the ManufacturerUri, PackageType, TargetProductCodes, PackageRevision and Name.

The PackageMetadata structure and all contained types are encoded using the JSON VerboseEncoding.

Note: The following tables describe the package_metadata.json with structures and enumerations as a separate OPC UA namespace. These types typically do not show up in the AddressSpace of an OPC UA Server.

Table 120 – PackageMetadata structure

Name	Type	Description	Optional
PackageMetadata	0:Structure
Name	0:String	Names the package (the package file name can be changed)	False
Description	0:String	Description of the content of the Software Package.	True
ManufacturerUri	0:String	Identification of the manufacturer of the package (used with PackageType and SoftwareRevision to uniquely identify the package)	False
Manufacturer	0:String	Manufacturer of the package (for display purposes)	False
PackageRevision	0:String	Version of the software package	False
PackageType	2:PackageType	Type of the Software Package.Other values are reserved for future use.	False
SoftwareSubClass	0:String	Name of the application (in case of SoftwareClass Application)	True
DeployCompletePackage	0:Boolean	If true the complete package shall be sent to the device. Otherwise only the contained files that are marked as DeploymentItem are deployed (default: false).	True
SoftwareRevision	0:String	Version of the software in the package. Optional for solution packages.	True
ReleaseDate	0:DateTime	Additional information for the user	True
TargetManufacturerUri	0:String	Identification of the target Node on the device. Used to find suitable Software Packages for a device.	True
TargetManufacturer	0:String	Manufacturer of the target (for display purposes). Used to find suitable Software Packages for a device.	True
UpdateTargets[]	2:UpdateTarget	Identification of the target Node on the deviceUsed to find suitable Software Packages for a device.Optional for solution packages.	True
Files[]	2:FileDescriptor	Describes the files that require special treatment by the update client.	True
Compatibilities[]	2:CompatibilityOption	List of options: At least one of them must match to be compatible.	True
Assignments[]	2:Assignment	Assignments of Software Packages to components that support SoftwareUpdate Only for solution packages (see 8.7.5)	True

Table 121 – PackageMetadata definition

Attribute		Value
BrowseName		2:PackageMetadata
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 122 – UpdateTarget structure

Name	Type	Description	Optional
UpdateTarget	0:Structure
ProductCode	0:String	ProductCode of the target Node on the device.	False
Model	0:String	Model of the target Node on the device.	False

Table 123 – UpdateTarget definition

Attribute		Value
BrowseName		2:UpdateTarget
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 124 – FileDescriptor structure

Name	Type	Description	Optional
FileDescriptor	0:Structure
FileType	2:FileType	Describes how the client shall use the file.	False
FileName	0:String	Relative path and file name to the file in the ZIP package	False
MimeType	0:String	Machine understandable type of file (default: “application/octet-stream”)	True
Language	0:String	Used to support multiple languages of the same document	True

Table 125 – FileDescriptor definition

Attribute		Value
BrowseName		2:FileDescriptor
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 126 – CompatibilityOption structure

Name	Type	Description	Optional
CompatibilityOption	0:Structure	One set of compatibility requirements
CompatibilityRequirements[]	2:CompatibilityRequirement	List of requirements: All of them must match to be compatible	False

Table 127 – CompatibilityOption definition

Attribute		Value
BrowseName		2:CompatibilityOption
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 128 – CompatibilityRequirement structure

Name	Type	Description	Optional
CompatibilityRequirement	0:Structure
Variable	0:String	Path to a variable to compare with Examples: variable of a component or its Identification functional group or its parent device or an application on that device…	False
Values[]	0:BaseDataType	Comparison values (zero, one or more values depending on the comparison operator). Can be any Integer or String type.	False
Operation	2:ComparisonOperation	Operation that is used to compare Variable and Values.	False

Table 129 – CompatibilityRequirement definition

Attribute		Value
BrowseName		2:CompatibilityRequirement
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 130 – PackageType Items

Name	Value	Description
Firmware	0	The Software Package contains the firmware of a physical device.
Application	1	The Software Package contains an executable software.
Configuration	2	The Software Package contains the configuration of a device or application.
Solution	3	The Software Package contains a solution with several software package.

Table 131 – PackageType definition

Attribute		Value
BrowseName		2:PackageType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

Table 132 – FileType Items

Name	Value	Description
DeploymentItem	0	This file shall be deployed to the device. If Cached-Loading or Direct-Loading is used at most one file can be marked as DeploymentItem. If File System based Loading is used all files that are marked as DeploymentItem shall be copied to the server using the same file name. If the complete Software Package is deployed to the device the individual files are not marked explicitly.
ReleaseNotes	1	E.g. link for user to open the document
LicenseInfo	2	E.g. link for user to open the document
PreInstallNote	3	Text that shall be shown to the user at least once before installation

Table 133 – FileType definition

Attribute		Value
BrowseName		2:FileType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

Table 134 – ComparisonOperation Items

Name	Value	Description
EqualTo	0	Value[0] = Variable
GreaterThan	1	Value[0] > Variable (proper comparison for SemanticVersionString shall be supported)
GreaterEqual	2	Value[0] >= Variable (proper comparison for SemanticVersionString shall be supported)
LessThen	3	Value[0] < Variable (proper comparison for SemanticVersionString shall be supported)
LessEqual	4	Value[0] <= Variable (proper comparison for SemanticVersionString shall be supported)
RegularExpression	5	Value[0] contains a regular expression which must match the value of the Variable
OneOf	6	The Values array must contain the value of the Variable
Exist	7	The Node that is described by the Variable must exist. The Values array shall be empty.

Table 135 – ComparisonOperation definition

Attribute		Value
BrowseName		2:ComparisonOperation
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

The compatibility declaration describes the compatibility of a Software Package with a component on the server that supports the SoftwareUpdate AddIn.

This can be simple terms like a minimum SoftwareRevision or a specific HardwareRevision of the component. Or relations to other objects in the AddressSpace e.g. to describe the existence and version of an attached hardware or to restrict the use of an application to a specific firmware version of a device.

Typically, the compatibility declaration outlines the relationship between variables and the corresponding component on the server. However, certain compatibilities can only be articulated through associated components e.g. the device hosting the application or a necessarily attached hardware. For those cases the compatibility declaration can incorporate paths following the UpdateParentReferenceType references (see 8.6.1).

The UpdateParentReferenceType enables the definition of a tree of object on the server which is utilized to describe compatibility. Parent objects are referenced as “..” while child objects are indicated by the BrowseName of the node being referenced. The elements within this path are interconnected using a slash (“/”).

Examples:

“ManufacturerUri”, “ProductCode”, “SoftwareRevision” identify properties of the component that should be updated.

“../ManufacturerUri” and “../ProductCode” identify a specific parent component (e.g. the device that hosts the application).

“../ProfinetExtension/SoftwareRevision” can identify the firmware version of a hardware which is connected to the parent.

To prove authenticity and integrity the Software Packages can be signed.

Initially the Software Package should be signed by the author (e.g., the manufacturer signs a firmware for its devices when it is created). This signature proves that it is really from that author (authenticity) and that is not altered on the way to the client (integrity) (see use case 8.2.2.20).

The verification of these signatures can be done by the Update Client or by the device if the whole update package is deployed.

Typically, a PKI with a certificate hierarchy is used. In this case, the entire certificate chain shall be stored in the signature. Consequently, only the root certificate is required for verification.

Additional signatures can be added by machine builders or plant operators to approve a Software Package for use in a specific plant. With this in place the Update Client and OPC UA servers can be configured to only allow updates of Software Packages with an approval signature of a specific certificate hierarchy (see use case 8.2.2.21).

To create a signed Software Package, it is stored as a standard ASiC-E (Associated Signature Container) container and signed with a CAdES (CMS Advanced Electronic Signatures) signature.

Note: These *AdES signatures are commonly used for advanced digital signatures in engineering environments. Examples are FDI, Profinet or OPC UA FX descriptors. To be easier usable on constrained devices the Software Packages use the binary CAdES persistence instead of the XML based XAdES. ASiC-E is a minimalistic ZIP container from the same family of standards.

With ASiC-E the folder structure of the ZIP file does not change. ASiC-E adds one additional folder “META-INF” with the signature information and a mimetype file in the root folder. These signatures also remain intact if individual files are removed or if the folders are unzipped.

Depending on the industry and environment where the devices are used there are different requirements to the level of security of the signatures. Therefore, the CAdES signatures support different levels which all can be used for the Software Packages. The more advanced options extend the basic option so that all packages remain compatible and usable with any update client.

For the verification of the signature, all certificates up to the root certificate are required. To ensure ease of handling, the entire certificate chain should therefore be incorporated within the CAdES signature.

All security relevant details are described in the publicly available ETSI standards (see ASiC-E, CAdES).

Note: If the complete Software Package is transferred to the device the verification also shall be done on the device. For this case certificates are distributed and updated on all device in the plant. Solutions for certificate distribution are covered in detail in OPC 10000-12 and OPC 10000-21.

Note: To create and maintain keys and certificates for the signatures, a PKI (public key infrastructure) should be used. Since this has no impact on the singing and verification described in this document, it is out of scope of this specification.

A Solution Package can be used to combine several Software Packages. This can have several reasons:

1. Easier distribution of multiple Software Packages as a single file (e.g., a complete machine with several devices or one device with several updateable components).
2. Only a specific combination of Software Packages shall be installed (could be verified using a signature at the Solution Package).
3. A combination of several Software Packages shall be installed to a device as a single file. The device is then responsible for distribution / installation of the subpackages.

A Solution Package can include an assignment information that declares which subpackage shall be installed to which targets on the device. A target can be either a specific instance or a type. If a type is specified, the package should be installed to all instances of that type. Example: A FieldBus head with OPC UA Server manages the firmware update of the connected IO modules.

A Solution Package also contains the standard package_metadata.json file with manufacturer and optional version information about the solution. Here the PackageType shall be set to Solution.

If there are several components in a Device that support the Software Update the CanUpdateReferenceType can be used to describe which subcomponents can be updated via the Solution Package.

If a precise assignment of the contained Software Packages is required, the Assignments element of the PackageMetadata can be used. The structures for the Assignment are defined in Table 136.

Table 136 – Assignment structure

Name	Type	Description	Optional
Assignment	0:Structure
Subpackage	0:String	Name of the subfolder within the SUBPACKAGES folder.	False
InstallationOrder	0:UInt32	Optional order of installation (lower numbers shall be installed first).	True
Targets[]	2:PackageTarget	List of targets for the Software Package with at least one element.	False

Table 137 – Assignment definition

Attribute		Value
BrowseName		2:Assignment
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 138 – PackageTarget structure

Name	Type	Description	Optional
PackageTarget	0:Structure
TargetType	0:NodeId	Install to all instances of that ObjectType.	True
TargetNode	0:NodeId	Install to specific node on the server.	True
ProductInstanceUri	0:String	Specific target with the ProductInstanceUri (see 4.5.3).	True
AssetId	0:String	Specific target with the AssetId (see 4.5.3).	True
ManufacturerUri	0:String	ManufacturerUri (see 4.5.3).	True
ProductCode	0:String	ProductCode (see 4.5.3).	True
SerialNumber	0:String	SerialNumber (see 4.5.2).	True
FxPath[]	2:FxPathElement	Path to a UA FX Asset (OPC 10000-81).	True
FxScope[]	2:FxPathElement	The package shall only be installed to targets behind this node (OPC 10000-81).	True
BrowsePath[]	0:RelativePathElement	BrowsePath to a concrete target node (see RelativePathElement of OPC 10000-5).	True
TargetServer	0:String	ApplicationUri of a target OPC UA Server.	True

Table 139 – PackageTarget definition

Attribute		Value
BrowseName		2:PackageTarget
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 140 – FxPathElement structure

Name	Type	Description	Optional
FxPathElement	0:Structure	Path based on OPC UA FX AssetConnectorTypes.
AssetConnectorType	0:NodeId	Connector type as defined in OPC 10000-81.Additionally either Id or Name shall be specified.	False
ConnectorId	0:UInt16	Id of the connector.	True
ConnectorName	0:String	Name of the connector.	True

Table 141 – FxPathElement definition

Attribute		Value
BrowseName		2:FxPathElement
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

PackageTarget can describe either a single or multiple targets for the subpackage. For example, TargetType describes multiple targets (all instances of that ObjectType), while the combination of SerialNumber, ProductCode, and ManufacturerUri uniquely identifies a single target. The following options can be used to filter the list of targets:

1. If no target is specified, the subpackage shall be installed on all matching target nodes.
2. If a TargetType is specified, all targes that are subtypes of the specified ObjectType shall be updated.
3. If a TargetNode is specified, only this node shall be updated.
4. If a ProductInstanceUri is specified, only the target with the specified ProductInstanceUri in its IVendorNameplateType shall be updated.
5. If AssetId is specified, only the target with the specified AssetId in its ITagNameplate shall be updated.
6. If ManufacturerUri and ProductCode are specified, all targets identified with these properties in its IVendorNameplateType shall be updated.
7. If ManufacturerUri, ProductCode and SerialNumber are specified, only the target identified with these properties in its IVendorNameplateType shall be updated.
8. If an FxPath is specified, the target is identified following the AssetConnectors (see OPC 10000-81) identified by its type and either its Id or its Name.
9. If AssetsTypes of OPC 10000-81 are used, TargetScope can be used to restrict the installation to targets which are connected to that asset. This can, for example, be combined with FxPath.
10. If a TargetBrowsePath is specified, the target is identified by the specified path. This path starts at the Objects Node and shall only result in a single node.

If the distribution of the packages is done by the Update Client and the package shall be installed on a specific server, the TargetServer contains the ApplicationUri of that server.