What are the rules/schemas for global model references?

[JoergNeidig]

In the AAS Spec Part 1 the Section 5.3.10.4 contains constraints and examples for the keys. However, looking at the examples of model references for submodelElements I do not understand the schema for creating the respective keys. Is it possible to provide more detailled information on how to create the references, possibly in XML/JSON?

[arnoweiss]

ModelReferences always point to something in the neighborhood of the Reference. So let's say, I have two Submodels. One Submodel contains a ReferenceElement that holds the Reference to a Property as its value.

{
  "modelType": "ReferenceElement",
  "idShort": "ExampleReferenceElement",
  "value": {
    "keys": [
      {
        "type": "Submodel",
        "value": "https://acplt.org/Test_Submodel"
      },
      {
        "type": "SubmodelElementCollection",
        "value": "ExampleSubmodelElementCollection"
      },
      {
        "type": "Property",
        "value": "ExampleProperty"
      }
    ],
    "type": "ModelReference"
  }
}

This Reference has three Keys. They are ordered and can be compose to a path. Let's go through the constraints for Reference to see how to construct it.

• As per AASd-121, the first key.type must be something with a unique id. A Submodel has a unique id as it's Identifiable.
• As per AASd-123, the first key.type can't be GlobalReference. That's because reference.type is ModelReference.
• As per AASd-125, all following key.types must be FragmentKeys which is basically saying: Only AAS-SubmodelElements.

[arnoweiss]

The questions that I have:

1. How to I refer to a Referable that's embedded? Examples include:
   1. AnnotatedRelationshipElement.annotations
   2. Entity.statements
   3. Capability.inputVariable
   4. Capability.outputVariable
2. What's the reason that AASd-125 ("no keys after the first may be globally identifiable") does not extend to GlobalReferences?

[StenGruener]

@BirgitBoss [ToDo] please kindly provide an example with XML and Text-Serialization

[BirgitBoss]

The questions that I have:

1. How to I refer to a Referable that's embedded? Examples include:

   1. `AnnotatedRelationshipElement.annotations`
   2. `Entity.statements`
   3. `Capability.inputVariable`
   4. `Capability.outputVariable`

annotations, inputVariable and outputVariable are not referable, only AnnotatedRelationshipElement, Entity, Capability. Attributes within Referables cannot be referenced in the current specification of the Asset Administration Shell (IDTA-01001-3-0)

Do you have use cases that would require to reference these "embedded" attributes.

This would be a new issue for https://github.com/admin-shell-io/aas-specs to also allow References to non-referable model elements.

Up to now the metamodel allows a key/type "FragmentReference", but this is used for (IDTA-01001-3-0): Bookmark or a similar local identifier of a subordinate part of a primary resource

[arnoweiss]

The attributes themselves aren't referable but the content they hold is. All have a range of SubmodelElement or Property respectively. So when adding a SubmodelElement INTO these attributes, they are referable. However, they can't be referred to with the existing Reference mechanism. That's how they differ from - say - AssetAdministrationShell.administration whose target (AdministrativeInformation) doesn't inherit from Referable. But the elements in the mentioned list do hold Referables, just like SubmodelElementCollection.value does.

I don't have a use-case which is why I'll let this topic rest. The Reference mechanism is underspecified in this instance.

[BirgitBoss]

The attributes themselves aren't referable but the content they hold is. All have a range of SubmodelElement or Property respectively. So when adding a SubmodelElement INTO these attributes, they are referable. However, they can't be referred to with the existing Reference mechanism. That's how they differ from - say - AssetAdministrationShell.administration whose target (AdministrativeInformation) doesn't inherit from Referable. But the elements in the mentioned list do hold Referables, just like SubmodelElementCollection.value does.

I don't have a use-case which is why I'll let this topic rest. The Reference mechanism is underspecified in this instance.

you are right

[BirgitBoss]

{
  "modelType": "ReferenceElement",
  "idShort": "ExampleReferenceElement",
  "value": {
    "keys": [
      {
        "type": "Submodel",
        "value": "https://acplt.org/Test_Submodel"
      },
      {
        "type": "SubmodelElementCollection",
        "value": "ExampleSubmodelElementCollection"
      },
      {
        "type": "Property",
        "value": "ExampleProperty"
      }
    ],
    "type": "ModelReference"
  }
}

I would make it more generic and use the examples generated by aas-core: https://github.com/admin-shell-io/aas-specs/blob/master/schemas/json/examples/generated/Reference/maximal.json and https://github.com/admin-shell-io/aas-specs/blo

There also other examples in https://github.com/admin-shell-io/aas-specs/tree/master/schemas/json/examples/generated/Reference

More generic a model reference looks like this:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "Submodel",
            "value": "<ID of Submodel>"
          }
          {
            "type": "SubmodelElementCollection",
            "value": "<idShort of SMC>"
          }
          {
            "type": "Property",
            "value": "<idShort of Prop>"
          }
        ],
        "type": "ModelReference"
      },

[BirgitBoss]

I would use the header in the Q&A:

What is the relationship between text serialization of "Reference" and other serializations like json or xml?

In IDTA-01001-3-0 (chapter 7.2.3) there is a text serialization defined for the type "Reference" that is used for many model references in the metamodel and as type for other attributes like "semanticId".

Please note: string references like XPATH pose a potential risk of injection, this is the reason for the design decision to explicitly model the reference

How is this text serialization related to JSON or xml serializations?

Answer:

For xml, json or rdf serializations just have a look at https://github.com/admin-shell-io/aas-specs/tree/master/schemas/xml/examples/generated/reference or https://github.com/admin-shell-io/aas-specs/tree/master/schemas/json/examples/generated/Reference or https://github.com/admin-shell-io/aas-specs/tree/master/schemas/rdf/examples/generated/Reference resp.

Now lets have a look at some of the examples given in the IDTA-01001-3-0 Metamodel specification for text serializations:

(Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title

This is identical to the JSON representation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "Submodel",
            "value": "https://example.com/aas/1/1/1234859590"
          }
          {
            "type": "SubmodelElementList",
            "value": "Documents"
          }
          {
            "type": "SubmodelElementCollection",
            "value": "0"
          }
          {
            "type": "MultiLanguageProperty",
            "value": "Title"
          }
        ],
        "type": "ModelReference"
      },

[ExternalRef](GlobalReference)0173-1#02-BAA120#008

is identical to the JSON representation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "GlobalReference",
            "value": "0173-1#02-BAA120#008"
          }
         ],
        "type": "ExternalReference"
      },

[ModelRef](ConceptDescription)0173-1#02-BAA120#008 is identical to the JSON represenation:

"<attribute with Type 'Reference'": {
        "keys": [
          {
            "type": "ConceptDescription",
            "value": "0173-1#02-BAA120#008"
          }
         ],
        "type": "ModelReference"
      },

The corresponding xml representation would look like this:

<attribute with Type 'Reference'>
                <type>ModelReference</type>
                <keys>
                    <key>
                        <type>ConceptDescription</type>
                        <value>0173-1#02-BAA120#008</value>
                    </key>
                </keys>
</attribute with Type 'Reference'>

[BirgitBoss]

Perhaps to add a third way of building paths to model elements. In Part 2 API of the AAS Specification there are so-called "idShort-Paths" defined (see Chapter 12.4 in V3.0 Addressing Resources). For the example (Submodel)https://example.com/aas/1/1/1234859590, (SubmodelElementList)Documents, (SubmodelElementCollection)0, (MultiLanguageProperty)Title

we would have the idShort-Path Documents[0].Title

Using it in an http/REST call needs base64url encoding for identifiers and URL encoding for idShort-Paths leads to GET /submodels/<Base64URL encoded https://example.com/aas/1/1/1234859590>/submodel/submodelElements/<URL encoded Documents[0].Title> i.e. GET /submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMS8xLzEyMzQ4NTk1OTA/submodel/submodelElements/Documents%5B0%5D.Title

[BirgitBoss]

The attributes themselves aren't referable but the content they hold is. All have a range of SubmodelElement or Property respectively. So when adding a SubmodelElement INTO these attributes, they are referable. However, they can't be referred to with the existing Reference mechanism. That's how they differ from - say - AssetAdministrationShell.administration whose target (AdministrativeInformation) doesn't inherit from Referable. But the elements in the mentioned list do hold Referables, just like SubmodelElementCollection.value does.

I don't have a use-case which is why I'll let this topic rest. The Reference mechanism is underspecified in this instance.

see https://github.com/admin-shell-io/aas-specs/issues/346

[StenGruener]

@BirgitBoss is this one closed with closed #103?

[BirgitBoss]

Yes