RE: Encourage use of public vocabs, discourage use of private vocabs in Hydra

On 7 Sep 2014 at 15:52, Dietrich Schulten wrote:
> The Hydra specification document refers to an api.example.com all the
> time and quite prominently encourages people to write their
> documentation into the hydra responses. As a general practice, I think
> that is very wrong, because we would end up having many
> vendor-specific documentations, rather than using public vocabularies
> out there.

Yeah, I completely agree. We should an existing vocabulary such as
Schema.org in the spec.


> I'd like to have a discussion what is the right approach here. My
> feeling is, we might be losing one of the major points of jsonld+hydra
> here, namely that it is a way to write commonly understandable apis -
> not just another form of wadl or json-schema or raml (machine-readable
> vendor-specific apidoc).

Fully agreed. My sloppiness is the only reason for this :-)


> If hydra apis mostly evolve as vendor specific (though
> well-documented) apis, it will not be possible to write clients which
> act upon an api based on common knowledge about things in the world,
> based on vocabularies.

Exactly.


> Therefore - if you agree with me - I would like to suggest that the
> Hydra specification makes that more clear. Normally api authors SHOULD
> express the meaning of their responses in terms of schema.org or other
> public vocabs. If I have a special need, I SHOULD use a common
> extension mechanism, e.g. by deriving from existing enumerations or
> types. If in fact I am doing something unprecedented and want people
> to use it on the web, I SHOULD establish a vocabulary. (BTW if there
> is no vocab registry yet in IANA, Hydra could as well define one and
> name the ones that are currently out there :) )
> 
> I would love to hear your point of view about this.

I fully agree with what you wrote above. Are those capitalized SHOULDs are
intended to be RFC2119 keywords in the spec? I don't think we should go down
that path. It's enough to explain the pros/cons and let people decide on
their own. This is not something that affects Hydra conformance IMO.


> For starters, there is quite a rich http://schema.org/Comment. I would
> find it most interesting to describe an issue system using Comment and

Have you seen the Event API demo:

   http://bit.ly/hydra-console-event-api

I think that's even better suited as example as almost everything needed is
already in Schema.org.


> see how its potentialAction property fits in with Hydra's operations.

That would be interesting, yes.



--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 7 September 2014 21:35:03 UTC