Closed JoergNeidig closed 5 months ago
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.
GlobalReference
. That's because reference.type is ModelReference
.The questions that I have:
AnnotatedRelationshipElement.annotations
Entity.statements
Capability.inputVariable
Capability.outputVariable
@BirgitBoss [ToDo] please kindly provide an example with XML and Text-Serialization
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
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 Referable
s, 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.
The attributes themselves aren't referable but the content they hold is. All have a range of
SubmodelElement
orProperty
respectively. So when adding aSubmodelElement
INTO these attributes, they are referable. However, they can't be referred to with the existingReference
mechanism. That's how they differ from - say -AssetAdministrationShell.administration
whose target (AdministrativeInformation
) doesn't inherit fromReferable
. But the elements in the mentioned list do holdReferable
s, just likeSubmodelElementCollection.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
{ "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"
},
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'>
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
The attributes themselves aren't referable but the content they hold is. All have a range of
SubmodelElement
orProperty
respectively. So when adding aSubmodelElement
INTO these attributes, they are referable. However, they can't be referred to with the existingReference
mechanism. That's how they differ from - say -AssetAdministrationShell.administration
whose target (AdministrativeInformation
) doesn't inherit fromReferable
. But the elements in the mentioned list do holdReferable
s, just likeSubmodelElementCollection.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 is this one closed with closed #103?
Yes
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?