Describe how hydra:apiDocumentation can be used to associate information to concepts defined in other vocabularies

[lanthaler]

If we would say that a client has to take into consideration the apiDocumentation when processing responses we could make it much simpler to reuse concepts from other vocabularies such as schema.org for instance. The client would look up the API documentation, would find a number of supportedClasses and trust the operations or supported properties associated to those classes. If that wouldn't be supported, it is necessary to introduce classes (e.g. subclasses or equivalent classes) to achieve that. Here's how you could associated some information to schema.org/Person in a ApiDocumentation:

{
  ...
  "supportedClasses": [
    {
      "@id": "http://schema.org/Person",
      "supportedProperties": [
         ...
      ],
      "supportedOperations": [
        ...
      ]
    }
  ]
}

[alien-mcl]

Dou you feel that client behavior related to missing graph definitions provided in section 5.3 Templated Links (three bullet-point rules) is enough to have this issue covered and closed? @tpluscode @asbjornu ?

[tpluscode]

I think it's not really what this is about. More related to the problem of adding statements to external vocabularies?

[asbjornu]

I'm not sure I understand @lanthaler completely. Especially the following statement makes me puzzled:

trust the operations or supported properties associated to those classes

[alien-mcl]

I think the idea is the payload may contain concepts (i.e. returned resource is of some type), but there is no more information regarding that type and client should consult the API documentation to possibly discover more. Currently there is no requirement to use API documentation at all except the part of the spec I've pointed

[alien-mcl]

Could you please reevaluate whether the 4.1 Adding Affordances to Representations addresses this? There were some changes and general client behavior regarding terms and API documentation sits now in this paragraph. There is a sentence says that client may dereference an IRI in case of an API that is well-known to that client (after consulting API documentation(