Referencing in Asset Administration Shells Overview To date, two kinds of references are distinguished: references to external objects or entities (external reference) and references to model elements of the same or another Asset Administration Shell (model reference). Model references are also used for metamodel inherent relationships like submodels of an Asset Administration Shell (notation see Annex A). An external reference is a unique identifier. The identifier can be a concatenation of different identifiers, representing e.g. an IRDI path. Note: references should not be mixed up with locators. Even URLs can be used as identifiers and do not necessarily describe a resource that can be accessed. Reference Attributes Figure 1. Metamodel of Reference See Clause Matching Algorithm for References for reference matching. Class: Reference Explanation: Reference to either a model element of the same or another Asset Administration Shell or to an external entity A model reference is an ordered list of keys, each key referencing an element. The complete list of keys may, for example, be concatenated to a path that gives unique access to an element. An external reference is a reference to an external entity. Inherits from: — ID: https://admin-shell.io/aas/3/1/Reference Attribute ID Explanation Type Card. type https://admin-shell.io/aas/3/1/Reference/type Type of the reference Denotes whether reference is an external reference or a model reference ReferenceTypes 1 referredSemanticId https://admin-shell.io/aas/3/1/Reference/referredSemanticId Expected semantic ID of the referenced model element (Reference/type=ModelReference); there typically is no semantic ID for the referenced object of external references (Reference/type=ExternalReference). Note 1: if Reference/referredSemanticId is defined, the semanticId of the model element referenced should have a matching semantic ID. If this is not the case, a validator should raise a warning. Note 2: it is recommended to use an external reference for the semantic ID expected from the referenced model element. Reference 0..1 key <<ordered>> https://admin-shell.io/aas/3/1/Reference/keys Unique reference in its name space Key 1..* Enumeration: ReferenceTypes Explanation: Enumeration for denoting whether an element is an external or model reference Set of: — ID: https://admin-shell.io/aas/3/1/ReferenceTypes Literal ID Explanation ExternalReference https://admin-shell.io/aas/3/1/ReferenceTypes/ExternalReference External reference ModelReference https://admin-shell.io/aas/3/1/ReferenceTypes/ExternalReference/ExternalReference Model reference Key Attributes Figure 2. Metamodel of Keys Keys are used to define references (Reference). Figure 3 presents a logical model of key types. These logical enumerations are used to formulate constraints. Figure 3. Logical Model for Keys of References (non-normative) Figure 4. Metamodel of KeyTypes Enumeration Class: Key Explanation: A key is a reference to an element by its ID Inherits from: — ID: https://admin-shell.io/aas/3/1/Key Attribute ID Explanation Type Card. type https://admin-shell.io/aas/3/1/Key Denotes which kind of entity is referenced If Key/type = GlobalReference, the key represents a reference to a source that can be globally identified. If Key/type = FragmentReference, the key represents a bookmark or a similar local identifier within its parent element as specified by the key that precedes this key. In all other cases, the key references a model element of the same or another Asset Administration Shell. The name of the model element is explicitly listed. KeyTypes 1 value https://admin-shell.io/aas/3/1/Key The key value, for example an IRDI or a URI Identifier 1 An example for using a FragmentId as type of a key is a reference to an element within a file that is part of an Asset Administration Shell aasx package. Figure 5. Metamodel of AasSubmodelElements Enumeration Enumeration: KeyTypes Explanation: Enumeration of different key value types within a key Set of: FragmentKeys; AasReferables, GloballyIdentifiables ID: https://admin-shell.io/aas/3/1/KeyTypes Literal ID Explanation AnnotatedRelationshipElement https://admin-shell.io/aas/3/1/KeyTypes/AnnotatedRelationshipElement Annotated relationship element AssetAdministrationShell https://admin-shell.io/aas/3/1/KeyTypes/AssetAdministrationShell Asset Administration Shell BasicEventElement https://admin-shell.io/aas/3/1/KeyTypes/BasicEventElement Basic event element Blob https://admin-shell.io/aas/3/1/KeyTypes/Blob Blob Capability https://admin-shell.io/aas/3/1/KeyTypes/Capability Capability ConceptDescription https://admin-shell.io/aas/3/1/KeyTypes/ConceptDescription Concept Description DataElement https://admin-shell.io/aas/3/1/KeyTypes/DataElement Data Element Note: data elements are abstract, i.e. if a key uses "DataElement", the reference may be a property, file, etc. Entity https://admin-shell.io/aas/3/1/KeyTypes/Entity Entity EventElement https://admin-shell.io/aas/3/1/KeyTypes/EventElement Event Note: event element is abstract. File https://admin-shell.io/aas/3/1/KeyTypes/File File FragmentReference https://admin-shell.io/aas/3/1/KeyTypes/FragmentReference Bookmark or a similar local identifier of a subordinate part of a primary resource GlobalReference https://admin-shell.io/aas/3/1/KeyTypes/GlobalReference Global reference Identifiable https://admin-shell.io/aas/3/1/KeyTypes/Identifiable Identifiable Note: identifiable is abstract, i.e. if a key uses "Identifiable" the reference may be an Asset Administration Shell, a submodel or a concept description. MultiLanguageProperty https://admin-shell.io/aas/3/1/KeyTypes/MultiLanguageProperty Property with a value that can be provided in multiple languages Operation https://admin-shell.io/aas/3/1/KeyTypes/Operation Operation Property https://admin-shell.io/aas/3/1/KeyTypes/Property Property Range https://admin-shell.io/aas/3/1/KeyTypes/Range Range with min and max Referable https://admin-shell.io/aas/3/1/KeyTypes/Referable Note: referables are abstract, i.e. if a key uses "Referable", the reference may be an Asset Administration Shell, a property, etc. ReferenceElement https://admin-shell.io/aas/3/1/KeyTypes/ReferenceElement Reference RelationshipElement https://admin-shell.io/aas/3/1/KeyTypes/RelationshipElement Relationship Submodel https://admin-shell.io/aas/3/1/KeyTypes/Submodel Submodel SubmodelElement https://admin-shell.io/aas/3/1/KeyTypes/SubmodelElement Submodel element Note: submodel elements are abstract, i.e. if a key uses "SubmodelElement", the reference may be a property, a submodel element list, an operation, etc. SubmodelElementCollection https://admin-shell.io/aas/3/1/KeyTypes/SubmodelElementCollection Struct of submodel elements SubmodelElementList https://admin-shell.io/aas/3/1/KeyTypes/SubmodelElementList List of submodel elements Enumeration: FragmentKeys Explanation: Enumeration of different fragment key value types within a key Note: not used as type but in constraints. Set of: AASReferableNonIdentifiables, GenericFragmentKeys ID: https://admin-shell.io/aas/3/1/FragmentKeys Literal ID Explanation AnnotatedRelationshipElement https://admin-shell.io/aas/3/1/FragmentKeys/AnnotatedRelationshipElement Annotated relationship element BasicEventElement https://admin-shell.io/aas/3/1/FragmentKeys/BasicEventElement Basic event element Blob https://admin-shell.io/aas/3/1/FragmentKeys/Blob Blob Capability https://admin-shell.io/aas/3/1/FragmentKeys/Capability Capability DataElement https://admin-shell.io/aas/3/1/FragmentKeys/DataElement Data Element Note: data elements are abstract, i.e. if a key uses "DataElement", the reference may be a property, file, etc. Entity https://admin-shell.io/aas/3/1/FragmentKeys/Entity Entity EventElement https://admin-shell.io/aas/3/1/FragmentKeys/EventElement Event Note: event element is abstract. File https://admin-shell.io/aas/3/1/FragmentKeys/File File FragmentReference https://admin-shell.io/aas/3/1/FragmentKeys/FragmentReference Bookmark or a similar local identifier of a subordinate part of a primary resource MultiLanguageProperty https://admin-shell.io/aas/3/1/FragmentKeys/MultiLanguageProperty Property with a value that can be provided in multiple languages Operation https://admin-shell.io/aas/3/1/FragmentKeys/Operation Operation Property https://admin-shell.io/aas/3/1/FragmentKeys/Property Property Range https://admin-shell.io/aas/3/1/FragmentKeys/Range Range with min and max ReferenceElement https://admin-shell.io/aas/3/1/FragmentKeys/ReferenceElement Reference RelationshipElement https://admin-shell.io/aas/3/1/FragmentKeys/RelationshipElement Relationship SubmodelElement https://admin-shell.io/aas/3/1/FragmentKeys/SubmodelElement Submodel element Note: submodel elements are abstract, i.e. if a key uses "SubmodelElement", the reference may be a property, a submodel element list, an operation, etc. SubmodelElementCollection https://admin-shell.io/aas/3/1/FragmentKeys/SubmodelElementCollection Struct of submodel elements SubmodelElementList https://admin-shell.io/aas/3/1/FragmentKeys/SubmodelElementList List of submodel elements Enumeration: AasReferableNonIdentifiables Explanation: Enumeration of different fragment key value types within a key Note: not used as type but in constraints. Set of: AasSubmodelElements ID: https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables Literal ID Explanation AnnotatedRelationshipElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/AnnotatedRelationshipElement Annotated relationship element BasicEventElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/BasicEventElement Basic event element Blob https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Blob Blob Capability https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Capability Capability DataElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/DataElement Data Element Note: data elements are abstract, i.e. if a key uses "DataElement", the reference may be a property, file, etc. Entity https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Entity Entity EventElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/EventElement Event Note: event element is abstract. File https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/File File MultiLanguageProperty https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/MultiLanguageProperty Property with a value that can be provided in multiple languages Operation https://admin-shell.io/aas/3/1/AasSubmodelElements/Operation Operation Property https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Property Property Range https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Range Range with min and max ReferenceElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/ReferenceElement Reference RelationshipElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/RelationshipElement Relationship SubmodelElement https://admin-shell.io/aas/3/1/AAasReferableNonIdentifiables/SubmodelElement Submodel element Note: submodel elements are abstract, i.e. if a key uses "SubmodelElement", the reference may be a property, a submodel element list, an operation, etc. SubmodelElementCollection https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/SubmodelElementCollection Struct of submodel elements SubmodelElementList https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/SubmodelElementList List of submodel elements Enumeration: AasSubmodelElements Explanation: Enumeration of submodel element types including abstract submodel element types Set of: — ID: https://admin-shell.io/aas/3/1/AasSubmodelElements Literal ID Explanation AnnotatedRelationshipElement https://admin-shell.io/aas/3/1/AasSubmodelElements/AnnotatedRelationshipElement Annotated relationship element BasicEventElement https://admin-shell.io/aas/3/1/AasSubmodelElements/BasicEventElement Basic event element Blob https://admin-shell.io/aas/3/1/AasSubmodelElements[/Blob Blob Capability https://admin-shell.io/aas/3/1/AasSubmodelElements/Capability Capability DataElement https://admin-shell.io/aas/3/1/AasSubmodelElements/DataElement Data Element Note: data elements are abstract, i.e. if a key uses "DataElement", the reference may be a property, file, etc. Entity https://admin-shell.io/aas/3/1/AasSubmodelElements/Entity Entity EventElement https://admin-shell.io/aas/3/1/AasSubmodelElements/EventElement Event Note: event element is abstract. File https://admin-shell.io/aas/3/1/AasSubmodelElements/File File MultiLanguageProperty https://admin-shell.io/aas/3/1/AasSubmodelElements/MultiLanguageProperty Property with a value that can be provided in multiple languages Operation https://admin-shell.io/aas/3/1/AasSubmodelElements/Operation Operation Property https://admin-shell.io/aas/3/1/AasSubmodelElements/Property Property Range https://admin-shell.io/aas/3/1/AasSubmodelElements/Range Range with min and max ReferenceElement https://admin-shell.io/aas/3/1/AasSubmodelElements/ReferenceElement Reference RelationshipElement https://admin-shell.io/aas/3/1/AasSubmodelElements/RelationshipElement Relationship SubmodelElement https://admin-shell.io/aas/3/1/AasSubmodelElements/SubmodelElement Submodel element Note: submodel elements are abstract, i.e. if a key uses "SubmodelElement", the reference may be a property, a submodel element list, an operation, etc. SubmodelElementCollection https://admin-shell.io/aas/3/1/AasSubmodelElements/SubmodelElementCollection Struct of submodel elements SubmodelElementList https://admin-shell.io/aas/3/1/AasSubmodelElements/SubmodelElementList List of submodel elements Enumeration: AasReferables Explanation: Enumeration of referables Note: not used as type but in constraints. Set of: AASReferableNonIdentifiables, AasIdentifiables ID: https://admin-shell.io/aas/3/1/AasReferables Literal ID Explanation AnnotatedRelationshipElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/AnnotatedRelationshipElement Annotated relationship element AssetAdministrationShell https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/AssetAdministrationShell Asset Administration Shell BasicEventElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/BasicEventElement Basic event element Blob https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Blob Blob Capability https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Capability Capability DataElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/DataElement Data Element Note: data elements are abstract, i.e. if a key uses "DataElement", the reference may be a property, file, etc. Entity https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Entity Entity EventElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/EventElement Event Note: event element is abstract. File https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/File File MultiLanguageProperty https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/MultiLanguageProperty Property with a value that can be provided in multiple languages Operation https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Operation Operation Property https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Property Property Range https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Range Range with min and max Referable https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/Referable Note: referables are abstract, i.e. if a key uses "Referable", the reference may be an Asset Administration Shell, a property, etc. ReferenceElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/ReferenceElement Reference RelationshipElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/RelationshipElement Relationship SubmodelElement https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/SubmodelElement Submodel element Note: submodel elements are abstract, i.e. if a key uses "SubmodelElement", the reference may be a property, a submodel element list, an operation, etc. SubmodelElementCollection https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/SubmodelElementCollection Struct of submodel elements SubmodelElementList https://admin-shell.io/aas/3/1/AasReferableNonIdentifiables/SubmodelElementList List of submodel elements Enumeration: GenericFragmentKeys Explanation: Enumeration of different fragment key value types within a key Note: not used as type but in constraints. Set of: — ID: https://admin-shell.io/aas/3/1/GenericFragmentKeys Literal ID Explanation FragmentReference https://admin-shell.io/aas/3/1/GenericFragmentKeys/FragmentReference Bookmark or a similar local identifier of a subordinate part of a primary resource Enumeration: AasIdentifiables Explanation: Enumeration of all metamodel element types that represent identifiables Note: not used as type but in constraints. Set of: — ID: https://admin-shell.io/aas/3/1/AasIdentifiables Literal ID Explanation AssetAdministrationShell https://admin-shell.io/aas/3/1/AasIdentifiables/AssetAdministrationShell Asset Administration Shell ConceptDescription https://admin-shell.io/aas/3/1/AasIdentifiables/ConceptDescription Concept description Identifiable https://admin-shell.io/aas/3/1/AasIdentifiables/Identifiable Identifiable Note: Identifiables are abstract, i.e. if a key uses "Identifiable", the reference may be an Asset Administration Shell, a submodel, or a concept description. Submodel https://admin-shell.io/aas/3/1/AasIdentifiables/Submodel Submodel Enumeration: GenericGloballyIdentifiables Explanation: Enumeration of different key value types within a key Set of: — ID: https://admin-shell.io/aas/3/1/GenericGloballyIdentifiables Literal ID Explanation GlobalReference https://admin-shell.io/aas/3/1/GenericGloballyIdentifiables/GlobalReference Global reference Constraints Constraint AASd-121: For References, the value of Key/type of the first key of Reference/keys shall be one of GloballyIdentifiables. Constraint AASd-122: 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. Constraint AASd-123: For model references, i.e. References with Reference/type = ModellReference, the value of Key/type of the first key of Reference/keys shall be one of AasIdentifiables. Constraint AASd-124: 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. Constraint AASd-125: For model references, i.e. References with Reference/type = ModelReference with more than one key in Reference/keys, the value of Key/type of each of the keys following the first key of Reference/keys shall be one of FragmentKeys. Note: constraint AASd-125 ensures that the shortest path is used. Constraint AASd-126: For model references, i.e. References with Reference/type = ModelReference with more than one key in Reference/keys, the value of Key/type of the last Key in the reference key chain may be one of GenericFragmentKeys or no key at all shall have a value out of GenericFragmentKeys. Constraint AASd-127: For model references, i.e. References with Reference/type = ModelReference with more than one key in Reference/keys, a key with Key/type FragmentReference shall be preceded by a key with Key/type File or Blob. All other Asset Administration Shell fragments, i.e. Key/type values out of AasSubmodelElements, do not support fragments. Note: which kind of fragments are supported depends on the content type and the specification of allowed fragment identifiers for the corresponding resource referenced. Constraint AASd-128: For model references, i.e. References with Reference/type = ModelReference, the Key/value of a Key preceded by a Key with Key/type=SubmodelElementList is an integer number denoting the position in the array of the submodel element list. In the following examples for valid und invalid model references and external references are given. The notation follows the grammar as defined in Clause Text Serialization of Values of Type "Reference". Examples for valid references: (Submodel)https://example.com/aas/1/1/1234859590 (GlobalReference)https://example.com/specification.html Examples for valid external references: (GlobalReference)https://example.com/ressource (GlobalReference)0173-1#02-EXA123#001 (GlobalReference)https://example.com/specification.html (FragmentReference)Hints Note: (GlobalReference)https://example.com/specification.html (FragmentReference)Hints represents the path with fragment identifier https://example.com/specification.html#Hints Examples for valid model references: (AssetAdministrationShell)https://example.com/aas/1/0/12348 (Submodel)https://example.com/aas/1/1/1234859590 (Submodel)https://example.com/aas/1/1/1234859590, (File)Specification (ConceptDescription)0173-1#02-BAA120#008 (Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title (Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementCollection)Manual, (MultiLanguageProperty)Title Note: (SubmodelElementCollection)0, (MultiLanguageProperty)Title may be identical to (SubmodelElementCollection)Manual, (MultiLanguageProperty)Title semantically and content-wise. The difference is that more than one document is allowed in the first submodel and thus a submodel element list is defined: elements in a list are numbered. However, it is also possible to define a display name in this case. The display name of the SubmodelElementCollection should be the same in both bases, e.g. "Users Manual". (Submodel)https://example.com/aas/1/1/1234859590, (File)Specification, (FragmentReference)Hints Note: assuming the file has the value using the absolute path https://example.com/specification.html (and not a relative path), the first reference points to the same information as the global reference (GlobalReference)https://example.com/specification.html, (FragmentReference)Hints (Submodel)https://example.com/aas/1/1/1234859590, (Blob)Specification, (FragmentReference)Hints Examples for invalid model references: (GlobalReference)https://example.com/aas/1/1/1234859590 This is an external reference but no model reference. (Property)0173-1#02-BAA120#008 This reference does not start with the ID of an Identifiable. Additionally, the value is not valid idShort for a Property submodel element. (Submodel)https://example.com/aas/1/1/1234859590, (EventElement)Event, (FragmentReference)Comment This model reference is invalid because fragment references so far are only defined for File and Blob submodel elements (see Constraint AASd-127). (AssetAdministrationShell)https://example.com/aas/1/0/12348, (Submodel)https://example.com/aas/1/1/1234859590, (Property)Temperature This is not a valid model reference because AssetAdministrationShell and Submodel are both global identifiables.