⧉  ⧉

Common Validation Errors of AAS

A guide to understand, avoid and handle AAS validation errors.

by Fabian Gumbrecht and Christian Körber

Version 1.1 (06-Aug-2024)

Introduction

Asset Administration Shell (AAS) is a fairly complex data standard that is still evolving and maturing. The tools that support it are also still in development and, in some cases, do not yet have support for the latest specification. The creators of AAS are under immense pressure in this situation. They must adapt their data using incomplete tools to a standard that is both difficult to access and constantly changing. Not surprisingly, data quality problems emerge.

At conplement AG, we are proud to provide Twinsphere, a software suite for the creation, hosting, and distribution of asset administration shells. As its provider, we often encounter data quality issues when customers try to upload their AAS to our platform.

The purpose of this guide is to explain the meaning and reason behind validation errors in terms of the AAS specification and to provide support for handling them. It focuses on the most commonly encountered validation errors on our end, but it is not exhaustive. Additional errors may be added in the future.

We hope this guide will assist you on your Asset Administration Shell journey!

Table of Conent

Errors with the Metamodel

General Metamodel Errors

Supported Version

twinsphere only supports AAS in the recent version 3
Problem Description
  • twinsphere is a platform for asset administration shells conform to the metamodel specification version 3.
  • If you try to upload an asset administration shell of an earlier version the platform will deny it.
Specification Reference
  • The Eclipse AASX Package Explorer is able to convert v2 packages into the v3 format.
  • Try to upgrade your package with the current Eclipse AASX Package Explorer ⧉
    • Open the Asset Administration Shell with the AasxPackageExplorer
    • Save the Asset Administration Shell as a new Asset Administration Shell
  • Re-Upload the converted AASX package to twinsphere

Common Attributes

idShort

idShort has to be unique within the same namespace
Error Message

Constraint AASd-022: ID-short of non-identifiable referables within the same name space shall be unique (case-sensitive).

Specification Reference
Remarks
  • idShort is case-sensitive.
  • A name space is defined as the parent element(s), which an element is part of and that is either referable or identifiable.
  • Constraint is necessary in order to address an element via API by an unique idShortPath.
  • Change idShort to a unique value or number identical values from 01 to n (i.e. DigitalFile -> DigitalFile01).
idShort of Referables shall only feature letters, digits, underscore
Error Message

ID-Short of Referables shall only feature letters, digits, underscore ( _ ); starting mandatory with a letter, i.e. [a-zA-Z][a-zA-Z0-9_]*.

Specification Reference
Remarks
  • Replace separators like hyphens, dots or commas in the idShort with an underscore.

Asset Information

Asset Identifier

At least one Asset Identifier has to be defined
Error Message

Constraint AASd-131: Either the global asset ID shall be defined or at least one specific asset ID.

Specification Reference
Remarks
  • Since globalAssetId and (the value of) specificAssetId are both identifiers they have to be GLOBALLY unique.
  • Define one globalAssetId or add at least a specificAssetId to the asset information.

Submodel

SubmodelIdss

Do not use SemanticId as SubmodelId of Submodel
Problem Description
  • Submodels require to have globally unique ids to be identifiable in any given scenario.
  • Sometimes we encounter the semanticId of the submodel template being used as SubmodelId for a concrete submodel instance.
  • This is not valid since the semanticId does not identify a single submodel instance and therefore is not a valid identifier.
Specification Reference

Part 1 v3.0, 5.3.5 Submodel Attributes, P. 62 ⧉

Remarks
  • Submodels are Identifiables and therefore must have globally unique ids.

Submodel Elements

Data Element

Valid values for Data Element Category
Error Message

Constraint AASd-090: For data elements category shall be one of the following values: CONSTANT, PARAMETER or VARIABLE.: {position}

Specification Reference
Remarks
  • Default value is VARIABLE.
  • Categories are deprecated and should no longer be used.
  • Remove the category attribute from the data element.

File

Wrong URI Scheme for referenced files
Error Message

The value must represent a valid file URI scheme according to RFC 8089.

Specification Reference
Remarks
  • All submodel elements "file" have to use the PathType which demand a URI according to RFC 8089.
  • This also applies to the path of defaultThumbnail within AssetInformation.
  • RFC 8089 or "The 'file' URI Scheme" demands a leading file-scheme for an URI, so it has to start with "file:".
  • AASX Package Explorer (v2023-11-17 and earlier) is not able to handle PathTypes with correctly referenced files (file:/...) and will not be shown them.
  • The specification currently is not consistent since the examples for PathType given in Part 1 v3.0 are not all valid (./Specification.pdf).
  • The upcoming specification Part 1 v3.1 will address this issue by allowing more generic URIs. See Issue #299 of aas-specs on Github ⧉ for details.
  • For now: Change the file path from /aasx/files/example.pdf to file:/aasx/files/example.pdf.
Empty File Path
Error Message

Filepath can not be null

Specification Reference
Remarks
  • Since the PathType of a file value is an identifier, it must contain a valid reference identifying something.
  • Same applies to the path attribute on a defaultThumbnail in AssetInformation.
  • Add a valid and existing file path to the file property or remove the property.
Valid Content Type of File
Error Message

The value must represent a valid content MIME type according to RFC 2046.

Specification Reference
Remarks
  • Valid MIME types for the contentType attribute are defined in RFC 2046 ⧉.
  • Assign a MIME type to the file that is RFC 2046 compliant.

Property

Value must be consistent with the value type of the property
Error Message

Value must be consistent with the value type.

Specification Reference
Remarks
  • Part 1's chapter on primitive and simple data types helps to determine the data type of the respective property.
  • Apply values with the right data type to the property.

MultiLanguageProperty

Value specifies duplicate languages
Error Message

Value specifies no duplicate languages.

Specification Reference
Remarks
  • The value of the MultiLanguageProperty depends on the serialization and has a similar structure like a dictionary.
  • So the indices in the multi language value have to be unique.
  • The error message is currently somewhat misleading. A corresponding aas-core-works issue ⧉ has already been created.
  • Check that the langStrings do not have overlapping languages.
  • Remove entries with duplicate keys so each language has exactly one entry.
Valid language tags
Error Message

The value must represent a value language tag conformant to BCP 47.

Specification Reference
Remarks
  • RDF requires IETF BCP 4729 language tags ⧉.
  • Simple two-letter language tags for locales like "de" conformant to ISO 639-1 are allowed, as well as language tags plus extension like "de-DE" for country code, dialect, etc. like in "en-US" for English (United States) or "en-GB" for English (United Kingdom).
  • Make sure that all uses language tags in the MultiLanguageProperty value are valid as described above.

References

Empty Keys
Error Message

Keys must contain at least one item.

Specification Reference
Remarks
  • Cardinality of attribute 'key' is 1..*.
  • Add at least one key to the reference or remove the whole reference.

Submodels References

All submodel references must be model references to a submodel
Error Message

All submodels must be model references to a submodel.

Specification Reference
  • Make sure that the type of every submodel reference is set to ModelReference.
  • Make sure that the type of every key of the submodel reference is set to Submodel.
Valid types of first reference key
Error Message

Constraint AASd-121: For References the value of type of the first key of keys shall be one of Globally Identifiables

Specification Reference
Remarks
  • For References, the value of Key/type of the first key of Reference/keys shall be one
    of GloballyIdentifiables.
  • Part 1 v3.0.1 specifies the following literals in the enumeration GloballyIdentifiables: "AssetAdministrationShell", "ConceptDescription", "GlobalReference", "Identifiable" and "Submodel".
  • Be aware that more restrictive constraints exist for other, more specific reference types , i.e. external or model references.
  • Make sure the type value of the first key of your reference is one of the afore mentioned literals.
Type of first external reference key has to be 'GlobalReference'
Error Message

Constraint AASd-122: For external references the value of type of the first key of keys shall be one of Generic Globally Identifiables.

Specification Reference
Remarks
  • For external references, i.e. References with Reference/type =
    ExternalReference, the value of Key/type of the first key of Reference/keys shall be one of GenericGloballyIdentifiables.
  • Part 1 v3.0.1 defines exactly one literal in the enumeration GenericGloballyIdentifiables which is "GlobalReference".
  • Make sure the first key of your external reference is of type GlobalReference.
Valid types of first model reference key
Error Message

Constraint AASd-123: For model references the value of type of the first key of keys shall be one of AAS identifiables.

Specification Reference
Remarks
  • For model references, i.e. References with Reference/type = ModelReference, the value of Key/type of the first key of Reference/keys shall be one of AasIdentifiables.
  • Part 1 v3.0.1 specifies the following literals in the enumeration AasIdentifiables: "AssetAdministrationShell", "ConceptDescription", "Identifiable" and "Submodel".
  • Make sure the type value of the first key of your model reference is one of the afore mentioned literals.
Valid types of last external reference key
Error Message

Constraint AASd-124: For external references the last key of keys shall be either one of Generic Globally Identifiables or one of Generic Fragment Keys.

Specification Reference
Remarks
  • For external references, i.e. References with Reference/type = ExternalReference, the last key of Reference/keys shall be either one of GenericGloballyIdentifiables or one of GenericFragmentKeys.
  • Part 1 v3.0.1 defines exactly one literal in the enumeration GenericGloballyIdentifiables which is "GlobalReference".
  • Part 1 v3.0.1 defines exactly one literal in the enumeration GenericFragmentKeys which is "FragmentReference".
  • Make sure the type value of the last key of your external reference is one of the mentioned two literals.

Errors with Specific Submodels

Handover Documentation

General Errors

No Cardinality Counters in ECLASS IRDI Path of SemanticIds
Problem Description
  • The semanticId of a Submodel Elements like DocumentId, DocumentClassification or DocumentVersion has a defined ECLASS IRDI path.
  • This is a fixed exact value in each case, e.g. "0173-1#02-ABI501#001/0173-1#01- AHF580#001", " 0173-1#02-ABI502#001/0173-1#01-AHF581#001" or "0173-1#02-ABI503#001/0173-1#01-AHF582#001".
  • Sometimes we encounter a semanticId for those elements with an additional attached string like "0173-1#02-ABI501#001/0173-1#01-AHF580#001*01", "0173-1#02-ABI502#001/0173-1#01-AHF581#001*01" or "0173-1#02-ABI503#001/0173-1#01-AHF582#001*01".
  • These are no valid semanticId as specified in the Handover Documentation submodel template.
Specification Reference
Remarks
  • Do not use cardinality counters in semanticIds.
  • Make sure the semanticId of each Submodel Element has the exact value as defined in the submodel template specification.

Errors with SubmodelElements of Document

SemanticId of SubmodelElement Document
Problem Description
  • The semanticId of a Document should be 0173-1#02-ABI500#001/0173-1#01-AHF579#001.
  • Sometimes it is mistaken with the ECLASS IRDI for number of DocumentIds 0173-1#02-ABH990#001.
Specification Reference
Remarks
  • 0173-1#02-ABI500#001 (property) is defined as "This SubmodelElementCollection holds the information for a document entity"
  • 0173-1#01-AHF579#001 (class) is defined as "Each SubmodelElementCollection describes a document by standard, which is associated to the particular Asset Administration Shell"
  • 0173-1#02-ABH990#001 (property) is defined as "Number of documents (handover documentation)"
  • Make sure the semanticId of the Document Submodel Element Collection has the value "0173-1#02-ABI500#001/0173-1#01-AHF579#001".

Errors with SubmodelElements of DocumentID

Mandatory property ValueId in Submodel Element DocumentId
Problem Description
  • ValueId is a required value in the DocumentId.
  • Somethimes we encounter handover documentation submodel instances where ValueId is missing in some or all DocumentIds.
Specification Reference
Remarks
  • ValueId is an identification number of the Document within a given domain, e.g. the providing organization
  • Example values for ValueId: 1213455566, XF90-884
  • Make sure there is a value set for each ValueId of each DocumentId representing an identifier which clearly identifies the document within your organization.

Errors with SubmodelElements of DocumentVersion

SemanticId of SubmodelElement DigitalFile
Problem Description
  • The semanticId of a digital file should be 0173-1#02-ABI504#001/0173-1#01-AHF583#001.
  • Sometimes it is mistaken with the ECLASS IRDI for the document path 0173-1#02-ABI005#001, which doesn't describe the whole file.
Specification Reference
Remarks
  • 0173-1#02-ABI504#001 (property) is defined as "MIME-Type, file name and file contents given by the file SubmodelElement". 0173-1#01-AHF583#001 (class) is defined as "MIME-Type, file name and file contents given by the file SubmodelElement".
  • 0173-1#02-ABI005#001 (property) is defined as "Path of the document".
  • Replace the semanticId of the DigitalFile element with the IRDI path "0173-1#02-ABI504#001/0173-1#01-AHF583#001".
IdShort of SubmodelElement DigitalFile
Problem Description
  • IdShorts for digital files have to be unique within the DocumentVersion.
  • It is recommended to name them "DigitalFile" with a following two-digit number.
Specification Reference
Remarks
  • IdShorts for digital files have to be unique within the DocumentVersion.
  • It is recommended to name them "DigitalFile" with a following two-digit number: DigitalFile{00}.
  • If an idShort ends with ‘{00}’, this indicates a suffix of the respective length (here: 2) of decimal digits to make the idShort unique.
  • A different idShort might be chosen, as long as it is unique in the parent’s context.
  • Name the idShort of digital files of one document version "DigitalFile" and add a number from 01 to XX.
  • Example: DigitalFile01, DigitalFile02, ...

XML Serialization

Relevant if you use XML in the aas-spec file of your AASX package, e.g. by using the AASX Package Explorer to generate packages.

Empty XML Nodes

Main error source here is that the official XML schema is demanding that most XML nodes need to contain something (item/value) or be non-existent. So, in many cases empty XML nodes are not allowed by the schema.

Empty EmbeddedDataSpecification
Error Message

Embedded data specifications must be either not set or have at least one item.: {position}

Specification Reference
Remarks
  • EmbeddedDataSpecifications must contain both, a DataSpecification and a DataSpecificationContent node.
  • Cardinality is wrongly documented in Part 1 v3.0, see linked issue.
  • Remove the empty node from the XML file or add DataSpecificationContent to it.
Empty SubmodelElementCollection/Value
Error Message

Value must be either not set or have at least one item.

Specification Reference
Remarks
  • The attribute value of a SubmodelElementCollection is optional.
  • But if there is a value it must contain at least one SubmodelElement item to it.
  • Remove the empty SubmodelElementCollection node from the XML file or add at least one SubmodelElement to it.
Empty SubmodelElement/Description
Error Message

Description must be either not set or have at least one item.

Specification Reference
Remarks
  • The attribute description of any Referable is optional.
  • Among others all SubmodelElements (like Properties) are Referables.
  • If the description attribute is set it must contain at least one item.
  • Remove the empty description node from the XML file or add at least one item to it.
Empty Entity/Statements
Error Message

Statements must be either not set or have at least one item.

Specification Reference
Remarks
  • The attribute statements of an entity is optional.
  • If the statements attribute is set it must contain at least one statement.
  • Remove the empty statements node from submodel in the XML file or add at least one statement item to it.
Empty Qualifiers
Error Message

Qualifiers must be either not set or have at least one item.

Specification Reference
Remarks
  • "A qualifiable element may be further qualified by one or more qualifiers. "
  • The XML element qualifiers of a submodel element is optional.
  • If the qualifiers element is present it must contain at least one qualifier element.
  • Remove the empty qualifiers node from the submodel in the XML file or add at least one qualifier element to it.
Empty (Language) Strings
Error Message

The value must not be empty.

Specification Reference
Remarks
  • Please note that the above schema reference is just one example among many.
  • ALL occurrences of "xs:string" in the XML schema are provided with a restriction of minLength=1.
  • Add a content of at least 1 character length to the attribute or remove it completely from the XML file.

Package File Format (AASX)

The AASX package file format is based on the Open Packaging Conventions and specified in Specification of the Asset Administration Shell, Part 5: Package File Format (AASX) ⧉.

Relationships

Relationships are used within an AASX package to connect the package to files, and to connect various files in the package. They form the logical model of the package.

No origin part found for aasx-origin
Error Message

No origin part found

Specification Reference
Remarks
  • Make sure that the relationship type for the aasx-origin in the /_rels/.rels file is 'http://admin-shell.io/aasx/relationships/aasx-origin' (without 'www.').
  • Make sure that the target property is filled with the correct relative path.

Supplemental Files (aas-suppl)

Incorrect File Path
Error Message

Document with value {filepath} could not be found in the aasx package

Specification Reference
Remarks
  • When a relative URI is used to reference a file from within the data of an AAS this file has to be part of the AASX package (must exists).
  • Make sure all referenced files exist in the package and the folder and file names are correct.
  • Make sure that all relatively referenced files are listed as aas-suppl targets in the relationship part file (e.g. /aasx/_rels/data.json.rels) of the aasx package.
  • Check if unused references exist in the relationship file.

Document Change History

Version 1.1 (06-Aug-2024)

  • Added 'No origin part found for aasx-origin' error and its containing 'Relationships' chapter.

Version 1.0 (15-Jan-2024)

  • Initial Version by Fabian Gumbrecht and Christian Körber.