Clarify behaviour when ApiDocumentation resource contains more than just itself

[tpluscode]

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.

[tpluscode]

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.

[alien-mcl]

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.

[tpluscode]

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