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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

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.

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).

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.

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.

Best regards,
Dietrich

- -- 
Dietrich Schulten
Escalon System-Entwicklung
Bubenhalde 10
74199 Untergruppenbach
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (MingW32)

iEYEARECAAYFAlQMYxQACgkQuKLNitGfiZNzpQCdE8bBSarC/l89Z5DHLFgsDhnZ
OWsAoO0MH0RttW+Ik7rfbgrDe/yeOTXy
=DmSq
-----END PGP SIGNATURE-----

Received on Sunday, 7 September 2014 13:53:05 UTC