RealEstateCore / rec

RealEstateCore ontologies.
http://realestatecore.io
BSD 3-Clause "New" or "Revised" License
84 stars 37 forks source link

Digital Twin Graph creation error from guide #218

Open WesVerhagen opened 1 year ago

WesVerhagen commented 1 year ago

Problem: DTDL graph model is not generating in Azure due to an incomplete JSON file and semantic type error.

Explenation: I try to generate a Azure Digital Twin graph from the guide on the website. https://dev.realestatecore.io/docs/guides/sensor/#azure-digital-twins-json-representation-dtdl-models

I get a lot of errors and managed to fix some of them like on twin 120 if i add a emty components for the "area" and "capacity" as followed { "$dtId": "120", "$etag": "W/\"d1db10f1-a098-4c5d-8e2f-092e8c11f418\"", "geometry": "[[4.0, 2.5], ... , [4.0, 2.5]]", "area": { "$metadata": {} }, "capacity": { "$metadata": {} }, "$metadata": { "$model": "dtmi:org:w3id:rec:Room;1" } The error is gone for 120

but when i look at the temperature twin like 120_Tmp there is a component "LastKnownValue.Value" in the json from the site but Value is not part of LastKnownValue inside the twin explorer (it is defined in the temperature observation model but it is not showing in the explorer ).

I think it is weird that i have to add emty components for the rooms. Am i doing something wrong? For the temp problem when i delete the semantic type temperature and only use type property the value is visable.

Steps to reproduce: Upload the JSON file containing the DTDL model data to Azure. Attempt to generate the DTDL graph model using the uploaded JSON file.

Expected result: The DTDL graph model is generated successfully in Azure.

Actual result: The DTDL graph model generation fails due to an incomplete JSON file.

hammar commented 1 year ago

Thanks for reporting!

This documentation is from the the public preview version of REC4 that was released earlier this year, and which can be downloaded from the releases page of the repo. During the public preview period we have received feedback from users that have caused us to evolve the models, in such a way that the example graphs in the guides are no longer 100 % compliant with what's in the main (dev) branch of the GitHub repo. When REC4 is released as GA in the very near future, these example graphs will need to be updated accordingly.

In this case, it seems related to our move toward DTDL Components for these fields (previously we used nested complex schemas for several of them). Components have some advantages in reusability, the possibility of using semantic types on properties, etc. One downside to using them however is that they need to be added when the twin is created. Using a tool such as the ADT Explorer to create twins these components are created automatically, see, e.g., code snippet below; but if importing a graph that does not have them, you'll get an error.

            {
                "$dtId": "MyTestArch",
                "$etag": "W/\"e3bee579-bd6b-448f-b45f-b7423058885f\"",
                "area": {
                    "$metadata": {}
                },
                "capacity": {
                    "$metadata": {}
                },
                "georeference": {
                    "$metadata": {}
                },
                "$metadata": {
                    "$model": "dtmi:org:w3id:rec:Architecture;1"
                }
            }
hammar commented 1 year ago

Re. the semantic typing issue: it seems that the ADT Explorer does not render the GUI semantically typed properties properly. I'll pass the question on to the ADT Explorer team. However the underlying ADT platform handles them just fine. Suggested workarounds:

  1. Remove the semantic co-typing on the interface declarations in question (as you have done)
  2. Use the ADT console CLI to set/read semantically typed values
WesVerhagen commented 1 year ago

Dear Karl,

Thank you for your response and for explaining the situation with the documentation for REC4. I understand that the example graphs may not be fully compliant with the main branch of the GitHub repo due to changes made based on user feedback. I appreciate the move toward using DTDL Components, as they offer benefits such as reusability and the ability to use semantic types on properties.

I will make sure to use the ADT Explorer to create twins so that the necessary components are added automatically. Thank you for your help and for keeping me informed.

Sincerely, Wes

hammar commented 1 year ago

No worries, thanks for asking -- otherwise we might have missed updating those example docs. I'll keep this issue open until we update them after 4.0 GA release.

hammar commented 1 year ago

In line with today's REC TC call, fixing these docs after REC4 GA ships is assigned to @PeteHart. I'd be happy to pitch in if needed, if so ping me on any of the usual channels.