SmartAPI
Annotating a list of items, JSON-LD?
When a response included a list of items, we annotated them all of the same type, which was a safe assumption for the specific endpoint. However, we expect to have responses that can have complex types returned.
Is it possible to use the spec such tags we add in the JSON schemas are used instead of annotating the response value?
This would allow us to use oneof features of OpenAPI 3 to return the right type for complex responses. It also suggests we might be able to use JSON-LD context in the schemas to annotate responses.
can you give an example of what you mean by "tags in the JSON schemas"
Hi @micheldumontier ! As I understand it, I currently annotate the responseType, which provides a single level of annotation. I am curious whether it might be possible to specify the URI of the response type in the schema of the items returned by a response, instead of under the path as it is done currently.
If that is possible, it might be easier for us to annotate more complicated objects, since we might be able to use JSON-LD to add @context tags in the JSON schemas themselves, as opposed to in an OpenAPI extension type.
Please bear with this "protoschema" example:
path:
genes/
x.responseValueType: id = http://geneIdURI
returns definitions$gene
definitions:
gene:
id: str
Might become:
path:
genes/
returns definitions$gene
definitions:
gene:
id: str
@context: http://geneIdURI
I apologize if I'm misinterpreting the spec or usage of JSON-LD context in this case! I understand this would induce significant churn in existing APIs if it worked, but would make them generally easier to interpret.
For what it's worth I ran this by @newgene in person at the RDF Summit 3. If I recall correctly, the current implementation relies on the OpenAPI x- extensions to describe annotations. This approach would require different tooling, but conceivably could make better use of existing linked data tooling since the task would be to define context labels for your JSON schema.
I believe it would be interesting to consider defining top level API annotations, like maintainer, using JSON-LD as opposed to the OpenAPI spec, as well. This would allow one to easily reason about different API implementations using SPARQL/RDF. However, changing the top-level annotation keys will certainly break down stream Open API tooling. Perhaps by mixing x- extensions for top-level API info (maintainer/server/license) and JSON-LD context for response definitions one could find a balance between schema changes and broken implementations.
@david4096 we are currently treating the "x-responseType" from SmartAPI specs as the "level-1" annotation (for those who don't want to write more complex JSON-LD context). JSON-LD context (like "level-2" annotation) can be more expressive to describe the semantics of the corresponding JSON fields (e.g. you can add the relationships, etc). In our BioThings Explorer application (http://biothings.io/explorer), it relies on the annotated JSON-LD context for the integrated APIs. So I agree with you that JSON-LD can be used for richer annotations, but I'm not sure about putting maintainer/server/license into the JSON-LD context. JSON-LD just a way to annotate existing JSON field, not for adding additional info. Unless you already have a field in your JSON data for maintainer/server/license, I'm not sure how to add them into JSON-LD context.
If I understand correctly, if one simply uses JSON-LD context that points to an existing URI, then we can forego the x-responseType?
Closing due to inactivity, if the issue or need for this this topic is still needed please reopen with updated information.
