UAFX OfflineEngineering - 7 Descriptor structure

This clause gives the formal definitions for the Descriptor concept.

A Descriptor shall be an AutomationML Container file with the file name extension “.amlx”.

The Descriptor content is organized into files and folders.

A Descriptor contains several kinds of files: The Descriptor manifest, Information Model files, attachment files, embedded Descriptors, and Common Services files. This is illustrated in Figure 17.

There is no prescribed folder structure for the Descriptor. The files of a specific kind are identified by Open Packaging Conventions relationships (see 7.5.2).

Figure 17 – Descriptor file structure

7.3.2 Descriptor manifest

The Descriptor manifest is an XML file that defines the metadata for a Descriptor.

There shall be exactly one Descriptor manifest in a Descriptor.

The Descriptor manifest file shall be identified by an Open Packaging Conventions relationship of type “http://schemas.opcfoundation.org/container/relationship/Manifest” stored in the container relationship file “_rels/.rels”.

Example:

The Descriptor manifest shall have exactly one “DescriptorInfo” XML element, which defines the XML sub-elements “DescriptorIdentifier”, “DescriptorVersion”, and “OpcUaFxVersion”, as defined in Table 1.

Table 1 – The content of the DescriptorInfo XML element

Tag	Type	Description
DescriptorIdentifier	xs:anyURI	URI of the Descriptor. Defines a globally unique identifier for the Descriptor.
DescriptorVersion	4 integers of type xs:short	Descriptor version. Defines the version numbers of the Descriptor.
OpcUaFxVersion	xs:string	Version of the OPC UA FX standard taken from the NodeSet file the Descriptor adheres to.

The following is an example of a “DescriptorInfo” XML element:

<DescriptorIdentifier>urn:company:factory:plant_project:automation_

component:1.0.0</DescriptorIdentifier>

</DescriptorVersion>

</DescriptorInfo>

The schema of the Descriptor manifest is defined in Annex J.

If a Descriptor is stored in an AcDescriptorType instance in the online Information Model and a value for the DescriptorIdentifier or the DescriptorVersion Variable of the instance is provided, this value will match the respective content of the DescriptorIdentifier or DescriptorVersion element in the DescriptorInfo XML element of the Descriptor manifest. (See OPC 10000-81, FxAssetType definition)

7.3.3 Information Model files

Information Model files are AutomationML files based on the OPC UA FX AML libraries defined in this document. Information Model files may also include or reference AutomationML content that is based on AML libraries other than the OPC UA FX AML libraries.

There shall be at least one Information Model file present in a Descriptor. The organization of the Information Model files is explained in 5.4 and 7.5.2. The content of the Descriptor shall correspond to the online UAFX Information Model Profiles as described in the UAFX Offline Descriptor Profile (see OPC 10000-84 and http://opcfoundation.org/UA-Profile/UAFX-Offline-Descriptor-Profile).

Information Model files and AutomationML files providing content for Information Model files are identified by an Open Packaging Conventions relationship of type “http://schemas.automationml.org/container/relationship/Library”.

7.3.4 Attachment files

A Descriptor may include one or more Attachment files. Attachment files are any files that are neither a manifest file, Information Model files, Embedded Descriptors, or common service files. Attachment files are useful for providing additional information for the understanding and usage of the AutomationComponent.

There is no specific format required for attachment files.

The file name extension and the content type of an attachment file shall be listed in the [Content_Types].xml file of a Descriptor. (See 7.6)

Attachment files are identified by an Open Packaging Conventions relationship of type “http://schemas.automationml.org/container/relationship/AnyContent”.

7.3.5 Embedded Descriptors

A Descriptor may include one or more Embedded Descriptors.

Embedded Descriptors shall be compliant with all Descriptor requirements defined in the UAFX Offline Descriptor Profile (see OPC 10000-84).

Embedded Descriptor files shall be identified by an Open Packaging Conventions relationship of type “http://schemas.opcfoundation.org/container/relationship/EmbeddedDescriptor”.

7.3.6 Common Services files

The following Common Services files shall be present in a Descriptor:

“[Content_Types].xml” file is located in the top-level folder “/”;

NOTE The brackets [ ] are literal text for the .xml file name as defined by the Open Packaging Conventions container.

relationship file “.rels” is located in the folder “/_rels”;
the “origin.psdor” file is located in the folder “/package/service/digital-signature”;
the relationship file “origin.psdor.rels”, which lists the digital signatures, is located in the folder “/package/service/digital-signature/_rels”;
at least one digital signature file with the file name extension .psdsxs is located in the folder “/package/service/digital-signature/xml-signature”.

7.4 Root AML Files

The entry points into the content of a Descriptor are the Root AML Files, as they are defined by the AML Container format (see IEC 62714-1).

A Root AML file shall be an OPC UA FX Information Model file.

A Descriptor shall have at least one Root AML file.

Root AML Files are identified by an Open Packaging Conventions relationship of type “http://schemas.automationml.org/container/relationship/RootDocument” stored in the container relationship file “_rels/.rels”.

Example: <Relationship Target=“{path-to-Root AML file}”Type=“http://schemas.automationml.org/container/relationship/RootDocument” Id=“{Id of root aml file}”/>

7.5 Descriptor References

7.5.1 Overview

Descriptor references have targets that are either in the Descriptor (internal references) or outside of the Descriptor (external references). The target of a Descriptor reference can be a file or content element in an XML file.

Three mechanisms are used for file and content references in a Descriptor:

Open Packaging Conventions relationships which can be used for internal and external references,
AutomationML ExternalDataReference interfaces,
AutomationML External References.

7.5.2 Open Packaging Conventions Relationships

Relationship references define references between files and are located in special Common Services files with the file name extension “.rels”. The reference source is defined by the file name where the relationship definition is located. For the reference targets, the URI syntax is used. The reference targets can be internal or external to the Descriptor. This is denoted by the “TargetMode” attribute. Every relationship reference shall have a valid XML identifier of type xs:ID (see ISO/IEC 29500-2:2021 clause 6.5.3.4).

All Information Model attachment and embedded Descriptors in a Descriptor shall be the target of a relationship reference, and all these files shall be reachable from the Root AML files via relationship references. The relationship references in a Descriptor shall form a Directed Acyclic Graph with the Root AML files as the starting points and with all Information Model, attachments, and embedded Descriptors in a Descriptor referenced from the Root AML files either directly or indirectly (i.e., over a chain of references). There shall be no circular dependencies between the files in a Descriptor. For more details, see IEC 62714-1.

For relationship references to a Descriptor, the Pack URI syntax shall be used to reference individual files in the container.

Some examples for relationship references:

Example of an internal relationship reference from a file “configuration.AML” to a file “library.AML” (The relationship is contained in the file “configuration.AML.rels”):

The same example for an external relationship reference:

Example of an internal relationship reference from a file “configuration.AML” to an attachment file “manual.pdf” (The relationship is contained in the file “configuration.AML.rels”):

Example of an external relationship reference from a file “configuration.AML” to a Descriptor “SensorProduct.amlx” (The relationship is contained in the file “configuration.AML.rels”).

Example of an external relationship reference from a file “configuration.AML” to a file contained in the Descriptor “SensorProduct.amlx” (The relationship is contained in the file “configuration.AML.rels”).

7.5.3 AutomationML ExternalDataReferences interfaces

AutomationML ExternalDataReferences interfaces allow one to define references from XML content inside of an AML file to non-AML files.

ExternalDataReferences interfaces shall be used if the reference target is not an AML file. The target can be inside or outside of the Descriptor.

For defining the reference target, the URI syntax, including the Pack URI syntax for reference targets that are contained in Descriptors, shall be used.

For a concrete reference, an interface shall be used that is either an ExternalDataReference or derived from ExternalDataReference.

An example of an ExternalDataReference to a document contained in a Descriptor is shown in Figure 18, with the code following the figure.

Figure 18 – Example of an ExternalDataReference in a Descriptor

<ExternalInterface

Name=“ManualReference”

ID=“4db4782f-98f2-42a0-a10b-11b3ac7d014d”

RefBaseClassPath=“AutomationMLInterfaceClassLib/AutomationMLBaseInterface/

ExternalDataConnector/ExternalDataReference” xmlns=”http://www.dke.de/CAEX”>

<Attribute

Name=“refURI”

AttributeDataType=“xs:anyURI”

RefAttributeType=“AutomationMLBaseAttributeTypeLib/refURI”>

<Value>file:///attachments/manual.pdf</Value>

</Attribute>

<Attribute

Name=“MIMEType”

AttributeDataType=“xs:string”

RefAttributeType=“AutomationMLBaseAttributeTypeLib/MIMEType”>

<Value>application/pdf</Value>

</Attribute>

</ExternalInterface>

7.5.4 AutomationML ExternalReference

For references between AutomationML Information Model files, the ExternalReference mechanism of AutomationML shall be used.

ExternalReference is defined in the CAEX specification (IEC 62424:2016, A.2.12, CAEX).

ExternalReferences are contained in the AutomationML file from where the reference starts.

The target of an ExternalReference is an AML object contained in an AML file. The target can be inside or outside of the Descriptor.

For defining the reference target, each ExternalReference shall provide a valid URI to the AML file and an alias, which shall be unique within the file where the reference starts. The URI can also be a Pack URI syntax for reference targets that are contained in Descriptors.

The alias may be used for referencing classes or instances. In this case, the reference tag shall begin with the alias name, followed by the alias separator “@”, followed by the path to the referenced class or the ID of the referenced InternalElement or ExternalInterface.

Example of an ExternalReference definition in an AutomationML file to an external AML library file:

The alias is used as an abbreviation when a reference is defined, as shown in the next example:

Example of an ExternalReference definition in an AutomationML file to an SUC in an OPC UA FX AML library file that is contained in a Descriptor that is stored externally:

The alias is used as an abbreviation when a reference is defined, as shown in the next example:

<InternalElement Name=“test” ID=“a1762231-6647-49a3-bbee-5a7df47d738a” RefBaseSystemUnitPath=“MyOpcUaFxAmlLibrary@[SUC_http://mynamespace.org/UA/FX/AC]/[MyAutomationComponentType] ”>…

7.6 Content Types

The Open Packaging Conventions standard requires that the file name extensions of the files contained in a Descriptor are registered in the “[Content_Types].xml” file. Only file name extensions used in a Descriptor shall be present in the “[Content_Types].xml” file of the Descriptor.

A list of IANA registered content types is given in: https://www.iana.org/assignments/media-types/media-types.xhtml.

Table 2 gives some examples of file name extension content types.

Table 2 – Example of File Name Extension Content Types

File name extension	Content type
aml	application/automationml-aml+xml
amlx	application/automationml-amlx+zip
xml	text/xml
pdf	application/pdf
png	image/png

The use of vendor-specific file name extensions is allowed. The vendor-specific file name extensions and content types may or may not be registered with IANA.

7.7 OpcAmlMetaModel and OPC UA FX AML Libraries

The creation of OPC UA FX Information Models is supported by the OpcAmlMetaModel libraries and by AML libraries that are derived from OPC UA types. The OpcAmlMetaModel libraries are defined in A.2. The AML libraries derived from OPC UA types are called OPC UA FX AML Libraries. The structure of an OPC UA FX AML Library is defined in Annex B. Each OPC UA FX AML Library contains AML Libraries for RoleClasses, InterfaceClasses, AttributeTypes and SystemUnitClasses.

This document provides an initial set of AML Libraries, the OPC UA FX AML Libraries, consisting of AML types that are generated from the types defined in the OPC 10000 series – see Annex B, Annex C, Annex D, and Annex E.

OPC UA FX Information Model AML files shall be based on the OPC UA FX AML Libraries defined in this document.

In the case where there is a need to supplement the available OPC UA FX AML Libraries with content not contained within them, then it is possible to generate new AML types (RoleClasses, InterfaceClasses, AttributeTypes and SystemUnitClasses) derived from the types from existing OPC UA FX AML Libraries and create a new OPC UA FX AML Library.

An OPC UA FX AML Library shall contain the AML type libraries (SystemUnitClass, InterfaceClassLibrary, RoleClassLibrary, AttributeTypeLibrary) of exactly one OPC UA Namespace.

For OPC UA FX AML Libraries, the following rules apply:

The new types of an OPC UA FX AML Library should be defined according to Annex B of this document. The new types shall derive directly or indirectly (i.e., over a derivation chain) from the types of the OPC UA FX AML Core Libraries.
The name of an OPC UA FX AML Library shall be according to the scheme XXX_<<ModelUri>>, where XXX stands for ICL for an InterfaceClass library, RCL for a RoleClass library, ATL for an AttributeType library and SUC for a SystemUnitClass library and <ModelUri> is the OPC UA Namespace of the corresponding OPC UA NodeSet file.
In an OPC UA FX AML Library, the namespace URI, the version, and the publication date are deduced from the “<Model>” XML element of the corresponding NodeSet file. This shall be documented with an OpcUaLibInfo XML element in the “Additional Information” sections of the AML library header. The schema for the OpcUaLibInfo XML element is defined in Annex K. An example is shown next:

<OpcUaLibInfo

Xmlns=“http://opcfoundation.org/UA/FX/2021/08/OpcUaLibInfo.xsd”>

<OpcUaNamespaceUri>http://opcfoundation.org/UA/FX/AC<Opcnamespace

URI>

<ModelVersion>1.0.0</ModelVersion> <ModelPublicationDate>2021-06-

16T04:53:39Z</ModelPublicationDate>

</OpcUaLibInfo>

</AdditionalInformation>

An OPC UA FX AML Library shall be distributed as a digitally signed AML Container.
If types from an OPC UA FX AML Library are used in a Descriptor, the library shall be made available in the Descriptor, either by including it as a file or by providing an AutomationML external reference. In the case of a vendor-specific OPC UA FX AML Library, a direct inclusion as either an internal or external reference shall be required. For referencing an OPC UA FX AML Library with a relationship reference, a “Library” relationship type shall be used. Usage dependencies from an OPC UA FX AML Library to other OPC UA FX AML Libraries shall be documented with an ExternalReference. See 7.5.4.

7.8 Descriptor digital signature

7.8.1 General

Digital signatures for Descriptors are based on the XML Signature specification and shall follow the structure and requirements defined in ISO/IEC 29500-2:2021, Clause 13.

A Descriptor shall have at least one digital signature.

The signing scope of each Descriptor signature shall include the following:

the Manifest,
all Information Model files,
all attachment files,
.rels files,
all Embedded Descriptors,
and all Common Services files.

The links to the external references, if any, in a Descriptor shall be included in the signature of the Descriptor. Content of external references shall not be included in this signature and should be digitally signed separately from the Descriptor signature.

There are two exceptions for including Common Services files into the scope of a digital signature:

[Content_Types].xml describing the used file name extensions is not included;
The relationship file of the digital signature origin file (e.g., “/package/services/digital-signature/_rels/origin.psdsor.rels” ) listing the contained digital signatures is not included. This allows adding a signature to the Descriptor without invalidating the existing ones.

Each Descriptor signature shall contain an X.509 certificate, which can be used for signature authentication.

The certificate can be associated with the identity of an individual, an engineering tool, a host, or an organization.

The certificate shall either be signed by a certificate authority or be self-signed.

If the certificate is not self-signed, the intermediate certificate chain shall be included in the X.509 Data element. The root certificate should be included (see 7.8.2), and the signing certificate shall be included.

Descriptors shall only use cryptographic mechanisms from OfflineEngineering security Profiles defined in OPC 10000-84.

Descriptor signatures shall be validated as specified in ISO/IEC 29500-2:2021.

According to ISO/IEC 29500-2:2021, each digital signature shall contain, in the SignatureProperty element, a timestamp indicating the time when the digital signature was created.

NOTE The timestamp can be set to arbitrary values (within the validity period of the signing certificate) by the signer. The validity period check-in procedure (see Table 3) assumes that the signer is trusted to not backdate the timestamp.

An engineering tool importing a Descriptor should support X.509 certificate technology for signer authentication. See Clause 8 for details on X.509 certificate technology usage.

Each digital signature is stored in a file with file name extension psdsxs in the folder “/package/services/digital-signature/xml-signature” in the Descriptor.

The folder “/package/services/digital-signature/_rels” contains the relationship file origin.psdsor.rels, which holds the relationship references to the signature files.

The following shows an example of a relationship reference to a digital signature file.

The digital signature file contains XML Signature markup with a subset of elements and attributes of the XML Digital Signature specification, e.g., the elements SignedInfo, SignatureValue, KeyInfo, X509Data and Manifest. The Manifest element lists the files of the signature scope.

An example of a digital signature is given in Annex I.

7.8.2 Certificate validation

Engineering tools should never import a Descriptor that they do not trust. An engineering tool decides if a Descriptor is trusted by checking whether each certificate associated with the digital signature of the Descriptor is trusted. A certificate is only trusted if its chain can be validated. Trust can be established by following the validation steps of Table 3 or by manually establishing trust in case the validation steps fail by deliberately suppressing an error.

Engineering tools should rely on lists of certificates provided by the administrator to determine trust. There are two separate lists: a list of trusted certificates and a list of issuer certificates. The list of trusted certificates may contain a certificate issued to another entity, or it may be a certificate belonging to a CA. The list of issuer certificates contains CA certificates needed for chain validation that are not in the list of trusted certificates.

When building a chain, each certificate in the chain shall be validated back to a CA with a self-signed certificate (i.e., a root CA). If any validation error occurs, then the trust check fails. Some validation errors are non-critical, which means they may be suppressed by a user of an engineering tool with appropriate privileges. Suppressed validation errors should be reported via log messages.

Determining trust requires access to all certificates in the chain. The certificate used to sign the Descriptor, and all intermediate certificates shall be provided with the Descriptor. Validation fails if a certificate in the chain cannot be found. A certificate is trusted if the certificate or at least one of the certificates in the chain is in the list of trusted certificates for the engineering tool and the chain is valid.

Table 3 specifies the steps used to validate a certificate in the order that they shall be followed. These steps are repeated for each certificate in the chain. Each validation step has a unique error log message that shall be reported if the check fails. Validation check failures shall be displayed to the user unless suppressed. It shall be possible for the user to suppress validation check failures individually or permanently.

Details on the validation steps in Table 3 are in IETF RFC 5280, 6.

Table 3 – Certificate validation steps

Step	Description
Certificate Structure	The certificate structure is verified.
Build Certificate Chain	The trust chain for the certificate is created.
Signature	A certificate with an invalid signature shall always be rejected. A certificate signature is invalid if the issuer certificate is unknown. A self-signed certificate is its own issuer.
Security Policy Check	A certificate signature shall comply with the CertificateSignatureAlgorithm, MinAsymmetricKeyLength and MaxAsymmetricKeyLength requirements for the used SecurityPolicy defined in OPC 10000-84.
Trust List Check	If the certificate signing the Descriptor is not trusted, and none of the CA certificates in the chain are trusted, the certificate validation shall fail.
Validity Period	The current time shall be after the start of the validity period. The time at which the signature was created shall be after the start of the validity period and before the end.
Certificate Usage	Each certificate has a set of uses for the certificate. For the certificate signing the Descriptor, the keyUsage shall include digitalSignature. The certificate shall not have a Basic Constraints extension with the CA flag set to TRUE. For CA certificates, the uses shall match use as a CA certificate (see OPC-10000-6). If the validation fails, it shall be reported if the usage is mandatory.
Find Revocation List	Each CA certificate may have a revocation list. This check fails if this list is not available (e.g., a network interruption prevents the engineering tool from accessing the list). No error is reported if the Security Administrator disables revocation checks for a CA certificate.
Revocation Check	The certificate shall not be revoked. Whether a certificate is revoked shall be checked as specified in IETF RFC 5280, 6.3.