JSON-LD

[niquola]

Are there any plans or experiments to integrate somehow OpenAPI and JSON-LD?

[eskoviak]

What did you have in mind for this integration?

[dmolesUC]

Offhand, some sort of support for JSON-LD contexts might be nice.

[akuckartz]

👍

[handrews]

@niquola @dmolesUC3 Where in OpenAPI would you want to integrate JSON-LD. Over at JSON Schema we also have a request to better integrate with JSON-LD, so if OpenAPI were to integrate JSON-LD for the parts of OpenAPI that use JSON Schema, it would be nice if we were all compatible. We haven't made any decisions on the JSON Schema end. See https://github.com/json-schema-org/json-schema-spec/issues/309, which had some initial discussion but then stalled, while other things took priority, for details. I hope to revisit this in the draft after the one that will be published this month.

[jam01]

My thinking, at least for OpenAPI schemas, is that they serve for validation only, just as the XML object does not pretend to be an XSD, I don't think we should try to have native support for LD contexts. We should only provide enough tools that'd allow a json+ld instance to pass.

I've been working out some ideas and here's how I think it should work:

  "title" : "Person",
  "xml" : {
    "namespace" : "http://hl7.org/fhir"
  },
  "ld" : {
    "context" : "http://build.fhir.org/fhir.jsonld",
    "type" : "fhir:Person"
  },
  "$ref" : "#/definitions/Person",
  "definitions" : {
    "Person" : {
      "allOf" : [ {
        "properties" : {
          "identifier" : {
            "type" : "array",
            "items" : {
              "$ref" : "Identifier.schema.json#/definitions/Identifier"
            },
            "ld" : {
              "name" : "Person.identifier"
            }
          },
          "name" : {
            "type" : "array",
            "items" : {
              "$ref" : "HumanName.schema.json#/definitions/HumanName"
            },
            "ld" : {
              "name" : "Person.name"
            }
          }
        },
        "required" : [ "name" ]
      } ]
    }
  }
}

And a valid instance would be:

{
  "@type": "fhir:Person",
  "@context": "http://build.fhir.org/fhir.jsonld",
  "role": "fhir:treeRoot",
  "@id": "http://hl7.org/fhir/Person/example",
  "Person.name": [
    {
      "index": 1,
      "HumanName.use": {
        "value": "usual"
      },
      "HumanName.given": [
        {
          "index": 0,
          "value": "Jim"
        }
      ]
    }
  ],
  "Person.telecom": [
    {
      "index": 0,
      "ContactPoint.system": {
        "value": "phone"
      },
      "ContactPoint.value": {
        "value": "(03) 5555 6473"
      },
      "ContactPoint.use": {
        "value": "work"
      }
    }
  ]
}

@handrews I don't think this would intersect with openAPI's use of json-schema. I am following that other issue and I do have the feeling that something might work out there, but I'm not sure how tbh. Maybe it's best if json-schema does not integrate directly with LD, because then what about HAL, or Collection+JSON?

[rob-metalinkage]

(this is cross posted on the relevant JSON-schema issue referenced inline - as this discussion (also) seems to have arisen there in 2017 and remains unresolved)

There have been various discussions around linking JSON schema with semantic information via JSON-LD. JSON-LD can be used to semantically annotate JSON data - but there appears to be no way to annotate the schema itself, [1] which limits the potential of OAS to expose useful semantic information about query and response objects.

We have been exploring this in the context of usage of JSON schema in OAS specifications - where the JSON schemas use the available $ref mechanism to create reusable schema building blocks. We have a workable approach to create reusable mappings form these sub-schemas to JSON-LD contexts and hence be able to semantically annotate both schemas as well as instances, but we'd like to double check we haven't missed an effort to join these dots.

In a nutshell, and following the spirit of the OAS recommendations to deprecate the use of examples within API specifications and add them as schema annotations…

It appears possible to create a 1:1 mapping of schemas and semantic models using an annotation in the schemas, which allow us to then compose , or re-use predefined, JSON-LD fragments. A composite JSON-LD context can then be created for the top level object like so:

{
 "@context": {
   "properties": {
     "@id": "https://purl.org/geojson/vocab#properties",
     "@context": {
       "hasResult": {
         "@id": "http://www.w3.org/ns/sosa/hasResult",
         "@context": {
           "distance": "http://example.com/vectorObservation/distance",
           "geopose": {
             "@id": "http://example.com/vectorObservation/geopose",
             "@context": {
               "angles": {
                 "@id": "http://example.com/geopose/angles",
                 "@context": {
                   "pitch": "http://example.com/geopose/pitch",
                   "yaw": "http://example.com/geopose/yaw",
                   "roll": "http://example.com/geopose/roll"
                 }
               },...

All that is required is to link the schema fragments with a JSON-LD context like so:

"$schema": https://json-schema.org/draft/2020-12/schema
description: 'GeoPose YPR angles'
'@modelReference': geopose.context.jsonld
type: object
properties:
  yaw:
    type: number
 ....

the context is lightweight and doesnt need to replicate type information if it can be derived from the schema.

@modelReference matches this discussion paper [2] which follows the nomenclature from SAWSDL [3] - However we use the JSON-LD approach of an “@” property rather than modifying the JSON schema properties - these could be alternatives perhaps- or we could adopt the modified schema approach if its supported.

Note that neither @context nor $vocabulary match the need to annotate a schema itself, not the instance or the meta-schema (schema description language).

This single mechanism is sufficient to compose a JSON-LD context (like the first example) in the same way OAS can compose a specification from bundled components - and could be built in capability of OAS (or an OAS profile).

Likewise, JSON-LD parsers could potentially lift the context from a scheme reference at run-time.

The approach doesn't predicate tooling support, but we recognise that others may already have equivalent capabilities in the OAS, JSON-schema or JSON-LD spaces, so we reach out for feedback.

[1] Adding Semantic Annotations to JSON Schema · Issue json-ld/json-ld.org#13 · json-schema-org/json-schema-vocabularies

[2] JSON Schemas with Semantic Annotations Supporting Data Translation

[3] Semantic Annotations for WSDL and XML Schema

[handrews]

Assuming I understand @rob-metalinkage correctly, I did a quick implementation of this as a JSON Schema vocabulary and show the 2020-12 and proposed draft-next annotation output in a comment on the JSON-LD issue.

I am currently working on using JSON Schema annotations to build RDF graphs out of instances in a project which should be public soon-ish. So I'm very interested in JSON Schema/OpenAPI/JSON-LD/other Semantic Web linkages right now.