Mappings (normative) Technical Data Formats This document specifies the Asset Administration Shell in a technology-neutral format, UML. Different data formats are used or recommended to be used in the different life cycle phases of a product[1]. The Asset Administration Shell supports three widely used formats: XML JSON RDF Note: the mapping specifications and schemata for XML, JSON and RDF are part of https://github.com/admin-shell-io/aas-specs. Content Format Types For different use case scenarios different formats are suitable to fulfill the needs. Besides technical formats like JSON and XML also different content formats are available. Table 1. Format Types Format Explanation Normal The standard serialization of the model element or child elements is applied. Metadata Only metadata of an element or child elements is returned; the value is not. Value Only the raw value of the model element or child elements is returned; it is commonly referred to as ValueOnly-serialization. Reference Only applicable to Referables. Only the reference to the found element is returned; potential child elements are ignored. Path Returns the idShort of the requested element and a list of idShortPath to child elements if the requested element is a Submodel, a SubmodelElementCollection, a SubmodelElementList, a AnnotatedRelationshipElement, or an Entity. Encoding Blobs require the following encoding: base64 string. Text Serialization of Values of Type "Reference" Grammar for Text Serialization Type "Reference" Some mappings or serializations convert the type "Reference" into a single string. In this case, the following serialization is required: Grammar: <Reference> ::= ["[" <ReferenceType> [ "- " <referredSemanticId> " -" ] "]" ] <Key> {(", " <Key> }* <ReferenceType> ::= "ExternalRef" | "ModelRef" value of AAS:Reference/type <SemanticId> ::= ["[" <ReferenceType> "]"] <Key> {(", " <Key> }* value of AAS:Reference/referredSemanticId <Key> ::= "(" <KeyType> ")" <KeyValue> <KeyType> ::= value of AAS:Key/type <KeyValue> ::= value of AAS:Key/value Note 1: an IRI may also contain special symbols like "(", "," and "[". A blank is added before the new key or value to distinguish beginning and end of a new key. Note 2: ReferenceType is optional. It is clear from the first key in the key chain whether the reference is a global or a model reference. The examples in this document therefore do not use this prefix. Examples for Text Serialization Type "Reference" Valid Examples: External References: (GlobalReference)0173-1#02-BAA120#008 [ExternalRef](GlobalReference)0173-1#02-BAA120#008 (GlobalReference)https://example.com/specification.html (FragmentReference)Hints Model References: (ConceptDescription)0173-1#02-BAA120#008 [ModelRef](ConceptDescription)0173-1#02-BAA120#008 (Submodel)https://example.com/aas/1/1/1234859590, (Property)Temperature (Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title Embedded Data Specifications The document series "Specification Asset Administration Shell" predefines data specifications that can be used within an Asset Administration Shell to ensure interoperability (see Part 3 documents). Consequently, some serializations or mappings support exactly the data descriptions defined in this specification, although the metamodel as such is more flexible and would also support proprietary data specifications. In the case of restricted use of data specifications, we speak of "embedded data specifications". Figure 58 explains the realization: instead of a set of external global references to externally defined data specifications, a set of pairs consisting of an external global reference to a data specification and the data specification content itself are directly "embedded". Here, the data specification content belongs to the schema, while the data specification including its content are not part of the schema in the general concept. This is similar to the concept of semanticIds: either it is an external global reference to an external concept dictionary, or it is a reference to a concept description within the schema. However, there is only one reference allowed for semanticId, whereas a set of data specification references is permitted for data specifications. Figure 1. Realization of Embedded Data Specifications Format "Metadata" (Metadata-Serialization) Metadata objects are defined for scenarios where a client only wants to access the metadata of an object, but not the value. Metadata objects are used to reduce the payload response to a minimum and to avoid the recursive traversing through the data model when not needed. In many cases, a client is not interested in each child element or value of a resource, but only in the resource itself. A metadata object does not contain any additional fields in relation to its full object representation, only some fields are left off. The left off fields are fields which could be requested by an own API call and may consist of a recursive or potentially large substructure. The serialization of a metadata object is the same as for the original full object, but without the left off fields. For elements in the metamodel that are not listed in the table no "Metadata"-serialization is available. Table 2. Metadata Attributes Class Name Fields not available in metadata representation Identifiables AssetAdministrationShell assetInformation, submodels Submodel submodelElements SubmodelElements SubmodelElementCollection value SubmodelElementList value Entity statements, globalAssetId, specificAssetId BasicEventElement observed Capability — Operation — DataElements Property value, valueId MultilanguageProperty value, valueId Range min, max ReferenceElement value RelationshipElement first, second AnnotatedRelationshipElement first, second, annotations Blob value, contentType File value, contentType Example The example shows a JSON serialization of an AssetAdministrationShell object in its full representation and how it looks like in a metadata representation. Note: for editorial reasons, some fields which are the same for both representations are omitted. Table 3. AssetAdministrationShell JSON Serialization Example { "idShort": "TestAssetAdministrationShell", "description": [...], "id": {...}, ... "derivedFrom": {...} "assetInformation": {...}, "submodels": [...] } Table 4. AssetAdministrationShell Metadata JSON Serialization Example { "idShort": "TestAssetAdministrationShell", "description": [...], "id": {...}, ... "derivedFrom": {...} } Format "Value" (Value-Only Serialization) in JSON Overview of Value-Only Serialization Attributes In many cases, applications using data from Asset Administration Shells already know the Submodel regarding its structure, attributes, and semantics. Consequently, there is not always a need to receive the entire model information, which can be requested separately via Content modifier set to Metadata, in each request since it is constant most of the time. Instead, applications are most likely only interested in the values of the modelled data. Furthermore, having limited processing power or limited bandwidth, one use case of this format is to transfer data as efficiently as possible. Semantics and data might be split into two separate architecture building blocks. For example, a database would suit the needs for querying semantics, while a device would only provide the data at runtime. Two separate requests make it possible to build up a user interface (UI) and show new upcoming values highly efficiently. Values are only available for All subtypes of abstract type DataElement, SubmodelElementList and SubmodelElementCollection resp. for their included SubmodelElements, ReferenceElement, RelationshipElement + AnnotatedRelationshipElement, Entity, BasicEventElement, Submodel. Capabilities are excluded from the serialization scope since only data containing elements are in the focus. They are consequently omitted in the serialization. The following rules shall be adhered to when serializing a submodel, a submodel collection or a submodel element list with the format _Value_[2]: A submodel or a submodel element collection is serialized as an unnamed JSON object. A submodel element list is serialized as an JSON array. A submodel element is considered a leaf submodel element if it does not contain other submodel elements. A leaf submodel element follows the rules for the different submodel elements considered in the serialization, as described below. If it is not a leaf element, the serialization rules must be transitively followed until the value is a leaf submodel element. For each submodel element within the submodel, the submodel collection or submodel list: Property is serialized as $\{Property/idShort}: $\{Property/value} where $\{Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section). MultiLanguageProperty is serialized as named JSON object with $\{MultiLanguageProperty/idShort} as the name of the containing JSON property. The JSON object contains an array of JSON objects for each language of the MultiLanguageProperty with the language as name and the corresponding localized string as value of the respective JSON property. The language name is defined as two chars according to ISO 639-1. Range is serialized as named JSON object with $\{Range/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “min”. The second is named “max”. Their corresponding values are $\{Range/min} and $\{Range/max}. File and Blob are serialized as named JSON objects with $\{File/idShort} or $\{Blob/idShort}as the name of the containing JSON property. The JSON object contains two JSON properties. The first refers to the content type named $\{File/contentType} resp. $\{Blob/contentType}. The latter refers to the value named “value” $\{File/value} resp. $\{Blob/value}. The resulting ValueOnly object is indistinguishable whether it contains File or Blob attributes. Therefore, the receiver needs to take the type of the target resource into account. Since the receiver knows in advance if a File or a Blob SubmodelElement shall be manipulated, it can parse the transferred Value-Only object accordingly as a File or Blob object. For Blobs the value attribute is optional (in this case a Blob can be distinguished from a File). SubmodelElementCollection is serialized as named JSON object with $\{SubmodelElementCollection/idShort} as the name of the containing JSON property. The elements contained within the struct are serialized according to their respective type with $\{SubmodelElement/idShort} as the name of the containing JSON property. SubmodelElementList is serialized as a named JSON array with $\{SubmodelElementList/idShort} as the name of the containing JSON property. The elements in the JSON array are the ValueOnly serializations of the elements contained in the SubmodelElementList while preserving the order, i.e. index n in the JSON array is the ValueOnly serialization of the element at index n of the SubmodelElementList. ReferenceElement is serialized as $\{ReferenceElement/idShort}: $\{ReferenceElement/value} where $\{ReferenceElement/value} is the serialization of the Reference class in format "Normal". RelationshipElement is serialized as named JSON object with $\{RelationshipElement/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named “first”. The second is named “second”. Their corresponding values are $\{RelationshipElement/first} resp. $\{Relationship/second}. The values are serialized according to the serialization of a ReferenceElement (see above). AnnotatedRelationshipElement is serialized according to the serialization of a RelationshipElement (see above). Additionally, a third named JSON object is introduced with “annotations” as the name of the containing JSON property. The value is $\{AnnotatedRelationshipElement/annotations}. The values of the array items are serialized depending on the type of the annotation data element. Annotations are optional. Entity is serialized as named JSON object with $\{Entity/idShort} as the name of the containing JSON property. The JSON object contains four JSON properties. The first is named “statements” $\{Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause. The second is named “globalAssetId” and the third “specificAssetIds”. Either a "globalAssetId" value or a "specificAssetIds" value shall exist. The other attributes are optional. “globalAssetId” corresponds to a Reference (see above). SpecificAssetIds" is an array of objects serializing _SpecificAssetId. A single SpecificAssetId in the array corresponds to the serialization of the SpecificAssetId class in format "Normal". The forth property is named “entityType” and contains a string representation of $\{Entity/entityType}. Statements and the entityType are optional. BasicEventElement is serialized as named JSON object with $\{BasicEventElement/idShort} as the name of the containing JSON property. The JSON object contains one JSON property named “observed” with the corresponding value of $\{BasicEventElement/observed} as the standard serialization of the Reference class. The following rules shall be adhered to when serializing a single submodel element with the format Value: Property is serialized as $\{Property/value} where $\{Property/value} is serialized as described above. MultiLanguageProperty is serialized as JSON object. The JSON object is serialized as described above. Range is serialized as JSON object. The JSON object is serialized as described above. File and Blob are serialized as JSON objects. The JSON object is serialized as described above. ReferenceElement is serialized as $\{ReferenceElement/value} where $\{ReferenceElement/value} is serialized as described above. RelationshipElement is serialized as JSON object. The JSON object is serialized as described above. AnnotatedRelationshipElement is serialized as JSON object. The JSON object is serialized as described above. Entity is serialized as JSON object. The JSON object is serialized as described above. BasicEventElement is serialized as JSON object. The JSON object is serialized as described above. Submodel elements defined in the submodel other than the ones mentioned above are not subject to the Value-Only serialization. Optional elements (like for example globalAssetId for an Entity submodel element) with no value shall be omitted in the serialization. Data type to value mapping The serialization of submodel element values is described in the following table. The left column “Data Type” shows the data types which can be used for submodel element values. The data types are defined according to the W3C XML Schema (https://www.w3.org/TR/xmlschema-2/#built-in-datatypes and https://www.w3.org/TR/xmlschema-2/#built-in-derived). “Value Range” further explains the possible range of data values for this data type. The right column comprises related examples of the serialization of submodel element values. Table 5. Mapping of Data Types in ValueOnly-Serialization[3] Data Type JSON Type Value Range Sample Values Core Types xs:string string Character string "Hello world", "Καλημέρα κόσμε", "コンニチハ" xs:boolean boolean true, false true, false xs:decimal number Arbitrary-precision decimal numbers -1.23, 126789672374892739424.543233, 100000.00, 210 xs:integer number Arbitrary-size integer numbers -1, 0, 126789675432332938792837429837429837429, 100000 IEEE-floating-point numbers xs:double number 64-bit floating point numbers -1.0, -0.0, 0.0, 234.567e8, 234.567e+8, 234.567e-8 xs:float number 32-bit floating point numbers -1.0, -0.0, 0.0, 234.567e8, 234.567e+8, 234.567e-8 Time and data xs:date string Dates (yyyy-mm-dd) with or without time zone "2000-01-01","2000-01-01Z", "2000-01-01+12:05" xs:time string Times (hh:mm:ss.sss…) with or without time zone "14:23:00", "14:23:00.527634Z", "14:23:00+03:00" xs:dateTime string Date and time with or without time zone "2000-01-01T14:23:00", "2000-01-01T14:23:00.66372+14:00" xs:dateTimeStamp string Date and time with required time zone "2000-01-01T14:23:00.66372+14:00" Recurring and partial dates xs:gYear string Gregorian calendar year "2000", "2000+03:00" xs:gMonth string Gregorian calendar month "--04", "--04+03:00" xs:gDay string Gregorian calendar day of the month "---04", "---04+03:00" xs:gYearMonth string Gregorian calendar year and month "2000-01", "2000-01+03:00" xs:gMonthDay string Gregorian calendar month and day "--01-01", "--01-01+03:00" xs:duration string Duration of time "P30D", "-P1Y2M3DT1H", "PT1H5M0S" xs:yearMonthDuration string Duration of time (months and years only) "P10M", 'P5Y2M" xs:dayTimeDuration string Duration of time (days, hours, minutes, seconds only) "P30D", 'P1DT5H", 'PT1H5M0S" Limited-range integer numbers xs:byte number -128…+127 (8 bit) -1, 0, 127 xs:short number -32768…+32767 (16 bit) -1, 0, 32767 xs:int number 2147483648…+2147483647 (32 bit) -1, 0, 2147483647 xs:long number -9223372036854775808…+9223372036854775807 (64 bit) -1, 0, 9223372036854775807 xs:unsignedByte number 0…255 (8 bit) 0, 1, 255 xs:unsignedShort number 0…65535 (16 bit) 0, 1, 65535 xs:unsignedInt number 0…4294967295 (32 bit) 0, 1, 4294967295 xs:unsignedLong number 0…18446744073709551615 (64 bit) 0, 1, 18446744073709551615 xs:positiveInteger number Integer numbers >0 1, 7345683746578364857368475638745 xs:nonNegativeInteger number Integer numbers ≥0 0, 1, 7345683746578364857368475638745 xs:negativeInteger number Integer numbers <0 -1, -23487263847628376482736487263847 xs:nonPositiveInteger number Integer numbers ≤0 -1, 0, -93845837498573987498798987394 Encoded binary data xs:hexBinary string Hex-encoded binary data "6b756d6f77617368657265" xs:base64Binary string base64-encoded binary data "a3Vtb3dhc2hlcmU=" Miscellaneous types xs:anyURI string Absolute or relative URIs and IRIs "http://customer.com/demo/aas/1/1/1234859590", "urn:example:company:1.0.0" rdf:langString string Strings with language tags "'Hello'@en", "'Hallo'@de" Note: the examples are written in RDF/Turtle syntax, and only "Hello" and "Hallo" are the actual values. The following types defined by the XSD and RDF specifications are explicitly omitted for serialization - they are not element of DataTypeDefXsd or DataTypeDefRdf: xs:language, xs:normalizedString, xs:token, xs:NMTOKEN, xs:Name, xs:NCName, xs:QName, xs:ENTITY, xs:ID, xs:IDREF, xs:NOTATION, xs:IDREFS, xs:ENTITIES, xs:NMTOKENS, rdf:HTML and rdf:XMLLiteral. Note 1: due to the limits in the representation of numbers in JSON, the maximum integer number that can be used without losing precision is 253-1 (defined as Number.MAX_SAFE_INTEGER). Even if the used data type would allow higher or lower values, they cannot be used if they cannot be represented in JSON. Affected data types are unbounded numeric types xs:decimal, xs:integer, xs:positiveInteger, xs:nonNegativeInteger, xs:negativeInteger, xs:nonPositiveInteger and the bounded type xs:unsignedLong. Other numeric types are not affected. [4] Note 2: the ValueOnly-serialization uses JSON native data types, AAS in general uses XML Schema Built-in Datatypes for Simple Data Types and ValueDataType. In case of booleans, JSON accepts only literals true and false, whereas xs:boolean also accepts 1 and 0, respectively. In case of double, JSON number is used in ValueOnly, but JSON number does not support INF/-INF (positive Infinity/negative), which is supported by xs:double. Furthermore, NaN (Not a Number) is also not supported. (See https://datatracker.ietf.org/doc/html/rfc8259#section-6 ) Note 3: language-tagged strings (rdf:langString) containing single quotes (‘) or double quotes (“) are not supported. Note 4: Roundtrip conversion from "Normal" to "ValueOnly" format may not result in the original payload because "Normal" is using string whereas "ValueOnly" is using the JSON type closest to the xsd datatype (see table [data-types-value-only]). Example Value-Only serialization for a Submodel The following example shows the JSON Value-Only serialization for a Submodel with name "Example" and two direct SubmodelElements "ProductClassifications" and "MaxRotationSpeed". "ProductClassifications" is represented by a SubmodelElementList with SubmodelElementCollections as its elements. Each of the SubmodelCollections has two mandatory elements "ProductClassificationSystem" and "ProductClassId" and one optional element "ProductClassificationVersion". All of these elements have data type "xs:string". "MaxRotationSpeed" is a property with data type "xs:int". { "ProductClassifications": [ { "ProductClassificationSystem": "ECLASS", "ProductClassId": "27-01-88-77", "ProductClassificationVersion": "9.0" }, { "ProductClassificationSystem": "IEC CDD", "ProductClassId": "0112/2///61987#ABA827#003" } ], "MaxRotationSpeed": 5000 } The JSON Value-Only serialization for the element "ProductClassifications", a SubmodelElementList, within the submodel above looks like this: [ { "ProductClassificationSystem": "ECLASS", "ProductClassId": "27-01-88-77", "ProductClassificationVersion": "9.0" }, { "ProductClassificationSystem": "IEC CDD", "ProductClassId": "0112/2///61987#ABA827#003" } ] The JSON Value-Only serialization for the first element, a SubmodelElementCollection, within the "ProductClassifications" list above looks like this: { "ProductClassificationSystem": "ECLASS", "ProductClassId": "27-01-88-77", "ProductClassificationVersion": "9.0" } The JSON Value-Only serialization for the Property "MaxRotationSpeed" of the submodel above looks like this: 5000 The Format "Normal" in comparison to this Value-Only serialization of the property "MaxRotationSpeed" would look like this: { "idShort": "MaxRotationSpeed", "semanticId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", "value": "0173-1#02-BAA120#008" } ] }, "modelType": "Property", "valueType": "xs:int", "value": "5000" } Examples Value-Only serialization for all submodel element types In the following examples for Value-Only serializations for all submodel element types are given. For a single Property named "MaxRotationSpeed", the value-Only payload is minimized to the following (assuming its value is 5000): 5000 For a SubmodelElementCollection named "ProductClassification" or being part of a list "ProductionClassifications", the Value-Only payload is minimized to the following, i.e. the name of the SubmodelElementCollection or its index in the list is not part of the Value-Only serialization: { "ProductClassificationSystem": "ECLASS", "ProductClassId": "27-01-88-77", "ProductClassificationVersion": "9.0" } For a SubmodelElementList named "Authors" with string Properties as its value, the Value-Only payload is minimized to the following (values within a SubmodelElementList do not have idShort values)[5]: [ "Martha", "Jonathan", "Clark" ] For a MultiLanguageProperty the Value-Only payload is minimized to the following: [ {"de": "Das ist ein deutscher Bezeichner"}, {"en": "That's an English label"} ] For a Range named “TorqueRange”, the Value-Only payload is minimized to the following: { "min": 3, "max": 15 } For a ReferenceElement named “MaxRotationSpeedReference”, the Value-Only payload is minimized to the following: { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", "value": "0173-1#02-BAA120#008" } ] } For a File named “Document”, the Value-Only payload is minimized to the following: { "contentType": "application/pdf", "value": "SafetyInstructions.pdf" } For a Blob named “Library”, there are two possibilities for the Value-Only payload. In case the Blob value - that can be very large - shall not be part of the payload, the payload is minimized to the following[6] { "contentType": "application/octet-stream" } In the second case the Blob value is part of the payload.[7], there is an additional attribute containing the base64-encoded value: { "contentType": "application/octet-stream", "value": "VGhpcyBpcyBteSBibG9i" } For a RelationshipElement named “CurrentFlowsFrom”, the Value-Only payload is minimized to the following: { "first": { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "http://customer.com/demo/aas/1/1/1234859590" }, { "type": "Property", "value": "PlusPole" } ] }, "second": { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "http://customer.com/demo/aas/1/0/1234859123490" }, { "type": "Property", "value": "MinusPole" } ] } } For an AnnotatedRelationshipElement named “CurrentFlowFrom”, with an annotated Property-DataElement “AppliedRule”, the Value-Only-payload is minimized to the following: { "first": { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "http://customer.com/demo/aas/1/1/1234859590" }, { "type": "Property", "value": "PlusPole" } ] }, "second": { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "http://customer.com/demo/aas/1/0/1234859123490" }, { "type": "Property", "value": "MinusPole" } ] }, "annotations": [ { "AppliedRule": "TechnicalCurrentFlowDirection" } ] } For an Entity named “MySubAssetEntity”, the Value-Only-payload is minimized to the following: { "statements": { "MaxRotationSpeed": 5000 }, "entityType": "SelfManagedEntity", "globalAssetId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", "value": "http://customer.com/demo/asset/1/1/MySubAsset" } ] } } For a BasicEventElement named “MyBasicEvent”, the Value-Only-payload is minimized to the following: { "observed": { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "http://customer.com/demo/aas/1/1/1234859590" }, { "type": "Property", "value": "MaxRotation" } ] } } JSON-Schema for the Value-Only Serialization The following JSON-Schema represents the validation schema for the ValueOnly-Serialization of submodel elements. This holds true for all submodel elements mentioned in the previous clause except for SubmodelElementCollections. Since SubmodelElementCollections are treated as objects containing submodel elements of any kind, the integration into the same validation schema would result in a circular reference or ambiguous results ignoring the actual validation of submodel elements other than SubmodelElementCollections. Hence, the same validation schema must be applied for each SubmodelElementCollection within a submodel element hierarchy. In this case, it may be necessary to create a specific JSON-Schema for the individual use case. The SubmodelElementCollection is added to the following schema for completeness and clarity. It is, however, not referenced from the SubmodelElementValue-oneOf-Enumeration due to the reasons mentioned above. See Annex ValueOnly-Serialization Example for an example that validates against this schema. { "$schema": "https://json-schema.org/draft/2019-09/schema", "title": "ValueOnly-Serialization-Schema", "$id": "https://admin-shell.io/schema/valueonly/json/V3.0", "definitions": { "AnnotatedRelationshipElementValue": { "type": "object", "properties": { "first": { "$ref": "#/definitions/ReferenceValue" }, "second": { "$ref": "#/definitions/ReferenceValue" }, "annotations": { "type": "array", "items": { "$ref": "#/definitions/ValueOnly" } } }, "additionalProperties": false }, "BasicEventElementValue": { "type": "object", "properties": { "observed": { "$ref": "#/definitions/ReferenceValue" } }, "required": [ "observed" ], "additionalProperties": false }, "BlobValue": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": "1", "maxLength": "100" }, "value": { "type": "string" } }, "additionalProperties": false }, "BooleanValue": { "type": "boolean", "additionalProperties": false }, "EntityValue": { "type": "object", "properties": { "statements": { "$ref": "#/definitions/ValueOnly" }, "entityType": { "enum": [ "SelfManagedEntity", "CoManagedEntity" ] }, "globalAssetId": { "type": "string" }, "specificAssetIds": { "type": "array", "items": { "$ref": "#/definitions/SpecificAssetIdValue" } } }, "additionalProperties": false }, "FileValue": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": "1", "maxLength": "100" }, "value": { "type": "string", "minLength": "1", "maxLength": "200" } }, "additionalProperties": false }, "Identifier": { "type": "string" }, "Key": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, "LangString": { "type": "object", "patternProperties": { "^[a-z]{2,4}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": { "type": "string" } }, "additionalProperties": false }, "MultiLanguagePropertyValue": { "type": "array", "items": { "$ref": "#/definitions/LangString" }, "additionalProperties": false }, "NumberValue": { "type": "number", "additionalProperties": false }, "PropertyValue": { "oneOf": [ { "$ref": "#/definitions/StringValue" }, { "$ref": "#/definitions/NumberValue" }, { "$ref": "#/definitions/BooleanValue" } ] }, "RangeValue": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "ReferenceElementValue": { "$ref": "#/definitions/ReferenceValue" }, "ReferenceValue": { "type": "object", "properties": { "type": { "type": "string", "enum": ["ModelReference", "ExternalReference"] }, "keys": { "type": "array", "items": { "$ref": "#/definitions/Key" } } }, "additionalProperties": false }, "RelationshipElementValue": { "type": "object", "properties": { "first": { "$ref": "#/definitions/ReferenceValue" }, "second": { "$ref": "#/definitions/ReferenceValue" } }, "additionalProperties": false }, "SpecificAssetIdValue": { "type": "object", "patternProperties": { "(.*?)": { "type": "string" } } }, "StringValue": { "type": "string", "additionalProperties": false }, "SubmodelElementCollectionValue": { "$ref": "#/definitions/ValueOnly" }, "SubmodelElementListValue": { "type": "array", "items": { "$ref": "#/definitions/SubmodelElementValue" } }, "SubmodelElementValue": { "oneOf": [ { "$ref": "#/definitions/BasicEventElementValue" }, { "$ref": "#/definitions/RangeValue" }, { "$ref": "#/definitions/MultiLanguagePropertyValue" }, { "$ref": "#/definitions/FileBlobValue" }, { "$ref": "#/definitions/ReferenceElementValue" }, { "$ref": "#/definitions/RelationshipElementValue" }, { "$ref": "#/definitions/AnnotatedRelationshipElementValue" }, { "$ref": "#/definitions/EntityValue" }, { "$ref": "#/definitions/PropertyValue" }, { "$ref": "#/definitions/SubmodelElementListValue" } ] }, "ValueOnly": { "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$" }, "patternProperties": { "^[A-Za-z_][A-Za-z0-9_-]*$": { "$ref": "#/definitions/SubmodelElementValue" } }, "additionalProperties": false } } } Format "Path" (idShortPath Serialization) in JSON To get only the idShort paths of a submodel element hierarchy, the serialization format is specified in terms of an idShortPath notation to be returned in an JSON array. The notation differs depending on whether a SubmodelElementCollection or a SubmodelElementList is present. In the first case, the submodel element’s idShort is separated by "." (dot) from top level down to child level. In the second case, square brackets with an index "[<Index>]" are appended after the idShort of the containing SubmodelElementList. In any case, the first item of any idShortPath is the idShort of the requested element. Grammar: <idShortPath> ::= <idShort> {["." <idShort> | "["<Index>"]" ]}* <Index> ::= <Zero> | <PositiveNumber> <PositiveNumber> ::= <NonZeroDigit>{<Digit>}* <Digit> ::= <Zero> | <NonZeroDigit> <Zero> ::= "0" <NonZeroDigit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" In the following example, where a request for idShort paths targets a MySubmodelElementCollection with SerializationModifier level = deep, the list of idShort paths is returned as follows: EXAMPLE Submodel Submodel: MySubmodel Property: MyTopLevelProperty SMC: MySubmodelElementCollection Property: MySubProperty1 Property: MySubProperty2 SMC: MySubSubmodelElementCollection Property: MySubSubProperty1 Property: MySubSubProperty2 SML: MySubSubmodelElementList1 Property: "MySubTestValue1" Property: "MySubTestValue2" SML: MySubSubmodelElementList2 SML Property: "MySubTestValue3" idShortPaths for SMC MySubmodelElementCollection within the Submodel above: [ "MySubmodelElementCollection", "MySubmodelElementCollection.MySubProperty1", "MySubmodelElementCollection.MySubProperty2", "MySubmodelElementCollection.MySubmodelElementCollection", "MySubmodelElementCollection.MySubmodelElementCollection.MySubProperty1", "MySubmodelElementCollection.MySubmodelElementCollection.MySubProperty2", "MySubmodelElementCollection.MySubSubmodelElementList1", "MySubmodelElementCollection.MySubSubmodelElementList1[0]", "MySubmodelElementCollection.MySubSubmodelElementList1[1]", "MySubmodelElementCollection.MySubSubmodelElementList2", "MySubmodelElementCollection.MySubSubmodelElementList2[0]", "MySubmodelElementCollection.MySubSubmodelElementList2[0][0]" ] Note: There is no idShortPath for Identifiables because idShort is optional for Identifiables. Format "Reference" In some use cases only the (model) reference to the object is needed in the first place. References are possible for Referables, only. Potential child elements are ignored. For references see Clause Referencing in Asset Administration Shells. Format "Reference" - Example in JSON { "keys": [ { "type": "AssetAdministrationShell", "value": "urn:an-example08:f3f73640" } ], "type": "ModelReference" } Format "Normal" in XML The metamodel of an Asset Administration Shell needs to be serialized for import and export scenarios. XML is a possible serialization format. eXtensible Markup Language (XML[8]) is very well suited to derive information from an IT system, e.g. to process it manually and then feed it into another IT system. XML provides the possibilities of scheme definitions, which can be used to syntactically validate the represented information in each step. Note 1: the xml schema (.xsd files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io [51] in folder schemas\xml Note 2: the mapping rules of how to derive the xml schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io [51] in folder schemas\xml\Readme.md#xml-mappingrules Note 3: example files can be found in the repository “aas-specs” in the GitHub project admin-shell-io [51] in folder : schemas\xml\examples Format "Normal" in JSON JSON[9] (JavaScript Object Notation) is a further serialization format that serializes the metamodel of an Asset Administration Shell for import and export scenarios. Additionally, JSON format is used to describe the payload in the http/REST API for active Asset Administration Shells [37]. Note 1: the JSON schema (.json files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io [51] in folder schemas\json Note 2: the mapping rules of how to derive the JSON schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io [51] in schemas\json\Readme.md#json-mappingrules Note 3: example files can be found in the repository "aas-specs" in the GitHub project admin-shell-io [51] in folder schemas\json\examples Format "Normal" in RDF The Resource Description Framework (RDF) [32] is the recommended standard of the W3C to unambiguously model and present semantic data. RDF documents are structured in the form of triples, consisting of subjects, relations, and objects. The resulting model is often interpreted as a graph, with the subject and object elements as the nodes and the relations as the graph edges. RDF is closely related to web standards, illustrated by the fact that all elements are encoded using (HTTP-)IRIs. As a common practice, the provision of additional information at the referenced location of an RDF entity directly allows the interlinking of entities[10] based on the web. This process – following links in order to discover related information – is called dereferencing a resource and is supported by any browser or web client. Connecting distributed data sources through the web in the described manner is referred to by the term “Linked Data”. Connecting the available resources and capabilities of linked data with the expressiveness of the Asset Administration Shell is one motivation for the RDF serialization. In addition, RDF is the basis of a wide range of logical inference and reasoning techniques. Vocabularies like RDF Schema (RDFS) and the Web Ontology Language (OWL) combine the graph-based syntax of RDF with formal definitions and axioms. This allows automated reasoners to understand the relation between entities to some extent and draw conclusions. Combining both features, the RDF mapping of the Asset Administration Shell can provide the basis for complex queries and requests. SPARQL, the standard query language for the Semantic Web, can combine reasoning features with the integration of external data sources. In order to benefit of these abilities, the Asset Administration Shell requires a clear scheme of its RDF representation. Note 1: the RDF scheme/OWL files (.ttl files) are maintained in the repository "aas-specs" of the GitHub project admin-shell-io [51] in folder schemas\rdf Note 2: the mapping rules of how to derive the RDF schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io [51] in schemas\rdf\Readme.md#rdf-mappingrules Note 3: example files can be found n the repository "aas-specs" of the GitHub project admin-shell-io [51] in folder schemas\rdf\examples 1. The word “data formats” is used as shortcut and includes the use of conceptual advantages such as information models, schemes, transmission protocols, etc. 2. see SerializationModifier in Part 2 of the Specification of the Asset Administration Shell 3. cf. https://eclipse-esmf.github.io/samm-specification/2.0.0/datatypes.html 4. cf. https://eclipse-esmf.github.io/samm-specification/2.0.0/payloads.html (with adjustments for +/-INF, NaN, and language-typed literal support) 5. The Value-Only serialization of the product classification example can be seen above 6. for the API a special JSON query parameter, the SerializationModifier Extent, is set to WithoutBLOBValue for this case 7. in this case the JSON query parameter SerializationModifier Extent is set to WithBlobValue 8. see: https://www.w3.org/TR/2008/REC-xml-20081126/ 9. see: https://tools.ietf.org/html/rfc8259 or https://www.ecma-international.org/publications/standards/Ecma-404.htm 10. Note: entity as a generic term and entity as a specific submodel element subtype need to be distinguished.