Openapi-specification: 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]

:+1:

[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": "[phone]"
},
"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?