Clarify behaviour when ApiDocumentation resource contains more than just itself
tpluscode opened this issue · 3 comments
Description
Having talked on today's conference call, @serialseb proposed to explicitly allow the ApiDocumentation
to have more than just Hydra-related triples. In the provided example scenario and API may also embed additional RDFS vocabulary terms which the client will need to fully understand the data structures
(@serialseb, please do open a separate issue in which you provide information on how and why this information would be useful)
Example
Written in turtle, that would simply be multiple subgraphs.
# the API Doc itself with all the standard bits
@base <http://some.app/> .
@prefix api: <http://some.api/> .
@prefix ex: <http://ontology.example/> .
@prefix hydra: <http://www.w3.org/ns/hydra/core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
<api>
a hydra:ApiDocumentation ;
hydra:supportedClass api:ClassOne, api:ClassTwo .
# Anything else
ex:SomeType a rdfs:Class .
Now, framing it to have the ApiDocumentation
on top simply discards the unlinked terms so it's just like a standard document. (playground example)
{
"@context": { },
"@graph": [
{
"@id": "http://some.app/api",
"@type": "hydra:ApiDocumentation",
"hydra:supportedClass": [
{
"@id": "api:ClassTwo"
},
{
"@id": "api:ClassOne"
}
]
}
]
}
Framing without a @type
will otherwise return a simple array of everything where the cohesive subgraphs are nicely nested so the api doc is easily discarded and the other triples processed.
PROPOSAL: as first step, to explain that more than just the hydra terms are to be expected in the ApiDocumentation document and a generic client should not discard the additional triples.
I think that framed example that fits better in this situation would look like this:
{
"@context": { },
"@id": "http://some.app/api",
"@type": "hydra:ApiDocumentation",
"hydra:supportedClass": [
{
"@id": "api:ClassTwo"
},
{
"@id": "api:ClassOne"
}
]
}
Please note the lack of @graph
- this is the shape of the document many of the JSON-LD users would aim to achieve and this is the sole issue non-RDF users may have.
It has nothing to do what you or I think. I simply copied the framing output from JSON-LD playground.
That being said, yes, it's a simple transformation to get to your presented JSON but JSON-LD will not to it alone