Detailed specification for expects/returns and strongly typed collections

[alien-mcl]

Added specifies predicate to enable server for:

• detailed expects/returns resource description
• strongly typed collections description
  Also added mediaType predicate for non-RDF resources.

This is an alternative approach for PRs #183 and #186 and should resolve #167 and #22.
In general - new specifies predicate is introduced through which a robust resource description in a reification-manner can be provided.

Only construct that worries me is in the strongly typed collection via API documentation, where a nested manages specification is provided. While specification can instruct on how the client should behave - the construct feels ... unnatural to me.

[angelo-v]

I have taken some look at SHACL in the meanwhile and it seams to fit our use case quite well. One could describe a Collection that contains Events by a Shape like this:

{
  "@context": [
    "http://www.w3.org/ns/hydra/context.jsonld",
    {
      "ex": "https://vocab.example/",
      "sh": "http://www.w3.org/ns/shacl#",
      "sh:class": {
        "@type": "@vocab"
      },
      "sh:path": {
        "@type": "@vocab"
      },
      "sh:property": {
        "@type": "@vocab"
      },
      "sh:hasValue": {
        "@type": "@vocab"
      }
    }
  ],
  "@id": "ex:EventCollectionShape",
  "@type": "sh:NodeShape",
  "sh:class": "hydra:Collection",
  "sh:property": {
    "sh:path": "manages",
    "sh:node": {
      "sh:property": [{
        "sh:path": "property",
        "sh:hasValue": "rdf:type"
      },
      {
        "sh:path": "object",
        "sh:hasValue": "schema:Event"
      }]
    }
  }
}

Such a Shape could be used in hydra:returns or hydra:expects to tell the client, that the operation returns/expects data that fulfills the constraints of that shape. That way we are much more flexible without having to reinvent the wheel.

Thinking this further, we could even reconcider the manages block regarding Shapes, since this is also a situation where we want to tell the client "the elements in here, look like this". So instead of hydra:property, hydra:object etc. we could describe the collection elements by a Shape as well:

{
    "@context": [
    "http://www.w3.org/ns/hydra/context.jsonld",
    {
      "ex": "https://vocab.example/",
      "sh": "http://www.w3.org/ns/shacl#",
      "sh:class": {
        "@type": "@vocab"
      },
      "sh:path": {
        "@type": "@vocab"
      },
      "sh:property": {
        "@type": "@vocab"
      },
      "sh:hasValue": {
        "@type": "@id"
      }
    }
  ],
    "@id": "https://api.example/location/1/events",
    "@type": "Collection",
    "manages": {
        "@id": "ex:EventsAtLocation1Shape",
        "@type": "sh:NodeShape",
        "sh:class": "schema:Event",
        "sh:property": {
          "sh:path": "schema:location",
          "sh:hasValue": "/location/1"
        }
    }
}

Then the EventCollectionShape cloud simply refer to the shape for the collection members (ex:EventAtLocation1Shape):

{
  "@context": [
      //... same as above
  ],
  "@id": "ex:EventCollectionShape",
  "@type": "sh:NodeShape",
  "sh:class": "hydra:Collection",
  "sh:property": {
    "sh:path": "manages",
    "sh:hasValue": "ex:EventAtLocation1Shape",
  }
}

[alien-mcl]

SHACL is tempting, but I don't think using it directly into hydra's spec constructs is a good approach. We've considered recommending SHACL to describe expected/returned data structures, but well ... it would be just a recommendation without imposing anything normative. Remember that while SHACL is a nice vocab that would fill the gap for non-RDF developers, RDF hardcore users would still stick to raw RDFS or OWL.

[tpluscode]

I don't think using it directly into hydra's spec constructs is a good approach

How would you use it then?

hardcore users would still stick to raw RDFS or OWL.

I don't think that's true. There is no sufficient tooling, especially in the browser to make OWL compelling even to "hardcore users"

[angelo-v]

SHACL is tempting, but I don't think using it directly into hydra's spec constructs is a good approach.

Why not? It fits the purpose. Why should we invent another vocabulary that does the same things, just worse / not as complete as SHACL?

We've considered recommending SHACL to describe expected/returned data structures, but well ... it would be just a recommendation without imposing anything normative.

That would be fine, but then there is no need to blow up the hydra spec with similar concepts.

Remember that while SHACL is a nice vocab that would fill the gap for non-RDF developers, RDF hardcore users would still stick to raw RDFS or OWL.

SHACL is pure RDF, isn't it? So I can't quite follow why they wouldn't use it? Nevertheless my focus is on real-world APIs and helping Web developers to build better APIs using Linked Data, that are not aware of it's strength right now. SHACL is not only able to describe the expected data shapes, but also perform validations, which is really helpful.

[angelo-v]

We should also watch the Solid-project closely, where Shapes (SHACL, Shex) are discussed as well. This may become key part for compatibility between Solid and Hydra-APIs.

[alien-mcl]

I don't think that's true. There is no sufficient tooling, especially in the browser to make
OWL compelling even to "hardcore users"

Sorry, but JavaScript/TypeScript and browsers are not the only environments hydra is supposed to work with. Java has several reasoning tools that works with RDFS/OWL fine, thus we should not disable those.

Why not? It fits the purpose. Why should we invent another vocabulary that does the same things,
just worse / not as complete as SHACL?

OWL is way more complex than SHACL to my knowledge and has many constraint related constructs.
The thing is - It's to complex for simple uses. I just don't want to elevate one external (in relation to hydra) vocabulary or the other.

SHACL is pure RDF, isn't it? So I can't quite follow why they wouldn't use it?

It is written in RDF, but it is somehow invisible for RDFS/OWL reasoning mechanisms.

Nevertheless my focus is on real-world APIs and helping Web developers to build better
APIs using Linked Data, that are not aware of it's strength right now.

Don't forget hydra aims also to be useful for automated (AI?) clients (machine only)

SHACL is not only able to describe the expected data shapes, but also perform validations,
which is really helpful.

So are OWL and reasoners.

Just to be clear - I want to support neither SHACL nor OWL in any way - I just want to ensure hydra is as generic and not-restricting as possible. I wouldn't like to see i.e. multiple hydra dialects (this API uses SHACL and another OWL and no generic client would work with both).