JSON-LD serialization

[sebastiankb]

What is missing?

Currently, various details of JSON response messages are possible, ranging from complete detail serialization, e.g., with semanticIds, to ValueOnly serialization without semanticId information. It would be great, if there is something it between which gives back ValueOnly, but gives the oppertunity to have the semantic background of each key-value pair. The answear would be JSON-LD.

How should it be fixed?

Support JSON-LD.

We should invite a member from the PASSAT project, who already extended the AAS API by introducing $JSON-LD in the API calls (similar to $value).

[dglachs]

Hello everyone, glad to see this topic as an issue here!

My proposal (and the demonstrator) in order to support JSON-LD as a serialization format for AAS Model "values" is quite simple. There are only few "pre-requisites" for AAS models / environment to support the data exchange with JSON-LD, thus with more semantics than with plain JSON:

• Ensure, each element of the AAS model TEMPLATE has appropriate semantic identifiers
• The semanticId of a DataElement refers to a ConceptDescripiton, whose id is a valid URI and which denotes the concepts details (DataSpecificationContentIec61360)
• The semanticId of SMC's refer to a ConceptDescription, whose id is a valid URI and which refers to the @type of the SMC via isCaseOf-Statement
• the semanticId of any element in an AAS INSTANCE model refers to its defining template element via ModelReference, ideally the referredSemanticId provides a 'short cut' to the template elements ConceptDescription

That way, it is possible to resolve a valid URI for each SubmodelElement by following the semanticId references until the corresponding ConceptDescription.

For SMC's, it is recommended to outline the element's type in the ConceptDescription's ``isCaseOf list:

Asking for the JSON or JSON-LD is then a matter of the AAS API by identifying the element to be processed via

./shells/<aas-id>/submodels/<submodel-id>/submodel-elements/<path>/$value (*)

The generation of RDF model is then straightforward:

1. Create a BNode as root resource. The id need not be permanent here, except when having the submodel as root element in the request.
2. For each instance element of type DataElement, use the parent/root resource and create a statement <bnode> <predicate> <value>
3. Resolve the elements predicate URI by following the ModelReference or the referredSemanticId ( when no valid URI available, the element is not part of the rdf output)
4. For each instance element of type SubmodelElementCollection, use the parent/root resource and create a statement <bnode> <predicate> <smc's bnode>
5. Resolve the SMC's ConceptDescription by following the ModelReference or the referredSemanticId
6. Use the id of the ConceptDescription as predicate in the above statement
7. Check for a GlobalReference out of the isCaseOf List and create a statement <bnode> rdf:type <isCaseOf-type>

Recursively process all the SMC's and collect the statements in the RDF model. The RDF model may then be serialized to JSON-LD in COMPACT, EXPANDED or whatever format.

(*) Either use a different content-modifier such as $jsonld in the request - or preferably - have the distinction via content negotiation e.g. keep the $value content-modifier and additionally evaluate the Content-Type header.

EXAMPLE for JSON & JSON-LD - taken from a PASSAT Use Case

While Content-Type: application/json --> default behavior produces plain JSON

{
    "identification": {
       "serialNumber" : "1234567"
        // confidential identification properties
    },
    "baseEdgeParameter": {
        "angleTail": 0.8,
        "angleWaist": 0.8,
        "angleTip": 0.8
    },
    "sideEdgeParameter": {
        "angleTail": 87.5,
        "angleWaist": 87.5,
        "angleTip": 87.5
    },
    "productData": {
        "skiBrand" : "ATOMIC"
        // confidential product details 
    }
}

The Content-Type: application/ld+json --> switch to JSON-LD exchange format

{
   "@graph": [
      {
        "@id": "_:f1c8d63313e642d39809fc5660a0c1c22",
        "@type": "dpp:SkiDataResponse",
        "dpp:baseEdgeParameter": {
          "@id": "_:f1c8d63313e642d39809fc5660a0c1c24"
        },
        "dpp:edgePerformance": {
          "@id": "_:f1c8d63313e642d39809fc5660a0c1c23"
        },
        "dpp:identification": {
          "@id": "_:f1c8d63313e642d39809fc5660a0c1c27"
        },
        "dpp:productData": {
          "@id": "_:f1c8d63313e642d39809fc5660a0c1c26"
        },
        "dpp:sideEdgeParameter": {
          "@id": "_:f1c8d63313e642d39809fc5660a0c1c25"
        }
      },
      {
        "@id": "_:f1c8d63313e642d39809fc5660a0c1c25",
        "@type": "dpp:EdgeParameter",
        "dpp:angleTail": {
          "@value": "87.5",
          "@type": "xsd:double"
        },
        "dpp:angleTip": {
          "@value": "87.5",
          "@type": "xsd:double"
        },
        "dpp:angleWaist": {
          "@value": "87.5",
          "@type": "xsd:double"
        }
      },
      {
        "@id": "_:f1c8d63313e642d39809fc5660a0c1c24",
        "@type": "dpp:EdgeParameter",
        "dpp:angleTail": {
          "@value": "0.8",
          "@type": "xsd:double"
        },
        "dpp:angleTip": {
          "@value": "0.8",
          "@type": "xsd:double"
        },
        "dpp:angleWaist": {
          "@value": "0.8",
          "@type": "xsd:double"
        }
      },
      {
        "@id": "_:f1c8d63313e642d39809fc5660a0c1c27",
        "@type": "dpp:IdentificationData",
        "dpp:serialNumber": "1234567"
        // other identification data omitted
      },
      {
        "@id": "_:f1c8d63313e642d39809fc5660a0c1c26",
        "@type": "dpp:ProductData",
        "dpp:skiBrand": "ATOMIC"
        // other product data omitted
      }
   ],
   "@context": {
     "dpp": "urn:samm:org.passat.ski:1.0.0#",
     "xsd": "http://www.w3.org/2001/XMLSchema#"
   }
}

The resulting RDF model follows the same structure as the plain JSON output. As with the plain JSON, there is no permanent ID for the root object itself, but the JSON-LD contains a @type statement for each SMC (or complex type) and explicitly states the data type for the non-string values.