Way for API to announce any extensions they use in addition to Hydra Core
tpluscode opened this issue · 3 comments
Introduce hydra vocabulary profiles or levels, i.e. level 0 and 1 where level 1 would be a default current hydra version and level 0 would be an alternative that does not imply a hydra:Resource is de-referencable (or event RDF based). This could also enable hydra for future profiles/levels using external schema vocabularies like SCHAL, OWL and non-rdf based ones.
Originally posted by @alien-mcl in #216 (comment)
The third point however I find rather orthogonal. I'm not sure the "profiles" have anything to do with dereferencability of the API descriptions. More about the requirements from the client. I would see this as an open-ended set of "feature-packs" that a server may implement in addition to core. Here are some ideas:
-
Hydra Core
- Only the base terms to put an API together
-
Standard Profile
- hydra:Class
-
SHACL profile
- Shapes for
expects
/returns
- maybe also
supportedClass
- Shapes for
-
JSON Schema profile
- like SHACL, uses a different vehicle to describe requests and responses
-
IANA Media types profile
- Uses IANA-registered media types. for example the snippet below might denote an operation where PNG and JPG are allowed to be uploaded
<> hydra:expects <https://www.iana.org/assignments/media-types/image/png> , <https://www.iana.org/assignments/media-types/image/jpeg> ,
-
Multi-part profile
- Something we discussed in #199 where an operation is described as expediting a
multipart/form-data
body. - Individual parts could then be individually describe using the other profiles. For example to have one part image (IANA profile) and the other a plain RDF resource (Standard profile)
- Something we discussed in #199 where an operation is described as expediting a
Each profile would be free to define its specific processing rules.
The required changes would be to:
- Add an optional property on
ApiDocumentation
to assert which profiles a server uses - Relax some
rdfs:range
statements of extension points - Move the "Standard Profile" to a separate spec document. Would probably keep
So as effect a server might announce itself as
<> a hydra:ApiDocumentation ;
// SHACL might potential be maintained by Hydra CG
hydra:profile <http://www.w3.org/ns/hydra/profile#SHACL> ;
// a vendor-specific profile which somehow bridges Open API
hydra:profile <http://example.com/hydra-profile#OpenAPI>
Originally posted by @tpluscode in #216 (comment)
I agree with the general idea - it was presented some time ago and it would solve a couple of the issues in this GH (i.e. #190 or #148).
The hydra:profile
sounds promising - the only thing to decide on what kind of IRI should be here. Shall it be some custom URI pointing to extension or URI pointing just to vocabulary in use.
Mayby a PREFER
header could be also used to negotiate possible profiles and extensions where possible