[Specifications] Clarify behaviour when ApiDocumentation resource contains more than just itself (#202)

tpluscode has just created a new issue for https://github.com/HydraCG/Specifications:

== Clarify behaviour when ApiDocumentation resource contains more than just itself ==
## 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](https://json-ld.org/playground/#startTab=tab-framed&json-ld=%7B%22%40context%22%3A%7B%22api%22%3A%22http%3A%2F%2Fsome.api%2F%22%2C%22ex%22%3A%22http%3A%2F%2Fontology.example%2F%22%2C%22hydra%22%3A%22http%3A%2F%2Fwww.w3.org%2Fns%2Fhydra%2Fcore%23%22%2C%22rdf%22%3A%22http%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22-rdf-syntax-ns%23%22%2C%22rdfs%22%3A%22http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%22%2C%22xsd%22%3A%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%23%22%7D%2C%22%40graph%22%3A%5B%7B%22%40id%22%3A%22http%3A%2F%2Fsome.app%2Fapi%22%2C%22%40type%22%3A%22hydra%3AApiDocumentation%22%2C%22hydra%3AsupportedClass%22%3A%5B%7B%22%40id%22%3A%22api%3AClassTwo%22%7D%2C%7B%22%40id%22%3A%22api%3AClassOne%22%7D%5D%7D%2C%7B%22%40id%22%3A%22ex%3ASomeType%22%2C%22%40type%22%3A%22rdfs%3AClass%22%7D%5D%7D&frame=%7B%22%40context%22%3A%7B%22api%22%3A%22http%3A%2F%2Fsome.api%2F%22%2C%22ex%22%3A%22http%3A%2F%2Fontology.example%2F%22%2C%22hydra%22%3A%22http%3A%2F%2Fwww.w3.org%2Fns%2Fhydra%2Fcore%23%22%2C%22rdf%22%3A%22http%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22-rdf-syntax-ns%23%22%2C%22rdfs%22%3A%22http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%22%2C%22xsd%22%3A%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%23%22%7D%2C%22%40type%22%3A%22hydra%3AApiDocumentation%22%7D))

```json
{
  "@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.

Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/202 using your GitHub account

Received on Tuesday, 26 November 2019 20:25:45 UTC