[Specifications] Requiring proper ranges on supported properties (#192)

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

== Requiring proper ranges on supported properties ==
## Description

Here is a comment from HydraCG/api-examples#4 which unexpectedly reveals a point of contention regarding supported properties:

> > But, the RDFS ranges are IMO the minimum requirement for a supported property
>
> I'm keen to agree with you, but having more details explicitly available is something an API may not provide.
>
>> Without them the client has only an option to fill the operation request with plain literals.
>
> Untrue - knowing a property IRI client could i.e. de-reference it hoping to receive more details on that property, including it's range/domain declarations. It's linked data after all

_Originally posted by @alien-mcl in https://github.com/HydraCG/api-examples/pull/4#discussion_r281792888_

---

**TL;DR;**

I, rather strongly, propose that supported property ranges are made explicit in supported properties as presented below

```
{
  "@type": "SupportedProperty",
  "property": {
    "@id": "schema:duration",
    "rdfs:range": "xsd:Duration" // <- WE NEED THIS
  }
}
```

Bottom line is that by choosing any different we're opening a pandora's box for misinterpretation, slow clients and confusion.

---

I'd like to address the two replies above as I find them damaging to the practicality of Hydra:

> I'm keen to agree with you, but having more details explicitly available is something an API may not provide.

I do not understand this a single bit. The API is the precise, best place for having this information. We're talking about local schemas. Forget vocabularies/ontologies for a moment. 

Any API being developed, unless they are a sink for (un|semi)-structured data, would likely operate on a fairly well-defined model. Think Java/.NET DTO classes in particular, with their strongly typed properties. Same applies to any information system anyway. The server rarely   expects a free-for-all where any client can post any value they please to the server.

Of course, a client may not understand the semantics of a particular datatype but in any case it is in both client's and server's best interest to always provide at least that information.

> Untrue - knowing a property IRI client could i.e. de-reference it hoping to receive more details on that property, including it's range/domain declarations. It's linked data after all

This is just plain wrong and not only on one level.

First, this is just too overburdening the client. You could have a multitude of properties and types from various vocabularies used in an API. Would you really have the client dereference them all? This is precisely the verbosity of REST APIs that drove people away and into GraphQL.

We should strive for self-containedness wherever possible, especially in an element so fundamental as attribute DATA TYPES.

Second, the ranges defined in an ontology may be something not what the API really wants in their resources. As long as they are not breaking semantic rules it is fine. You will say that it can always be overridden and you will be correct. But why not make it straightforward, but simply requiring this information to be there? Any other choice makes the client logic complex.

Lastly, not to mention that some (quite a few actually) vocabularies don't even dereference or are poorly maintained. Some are served with wrong media type. Some are on slow servers. This would be a death trap for any application. 

Semantic Web community has been having this problem for years. Hence the projects like [LOV](http://lov.linkeddata.es/) exist. Heck, my company has even started work on similar tooling to closet's very gap!

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

Received on Tuesday, 7 May 2019 21:05:46 UTC