Allow returns/expects to be expressed in terms of a media type

[alien-mcl]

This is a derivative of a PR #182 that covers #22 :

• added terms for media typed resource
• change expected/returned ranges

[tpluscode]

I think we're opening a can of worms with changes to the returns property.

The returned representation would be dependent upon the requested accept header. And so the client cannot really rely on the returns annotation. Nor should it in fact. One previously example is application/problem+json. A server can any time, in case of an error, return such response, completely disregarding what the API Documentation says.

With Postel's law in mind, I think it only makes sense to add such annotation to the expects end to let the client know that a given resource is intended for non-RDF payloads. On the receiving end any such information should be added sparingly.

[angelo-v]

With Postel's law in mind, I think it only makes sense to add such annotation to the expects end to let the client know that a given resource is intended for non-RDF payloads.

So, how would it look like to expect "image/png" for example? And wouldn't it be sufficient to use hydra:expects <https://schema.org/ImageObject> or something similar?

[alien-mcl]

I think we're opening a can of worms with changes to the returns property.

But with current hydra specification it also means that server may return something completely different than declared returns specification. Client should always check what it did receive.

Class is itself subClass of Resource. Hence, nothing really changes in principle.

It does. See that example:

some:operation hydra:returns some:mediaTypedResource .

With range of hydra:Class, you've automatically raised some:mediaTypedResource to a hydra:Class, which is untrue. I wound like to leave some:mediaTypedResource as pure hydra:Resource.

[alien-mcl]

So, how would it look like to expect "image/png" for example?
And wouldn't it be sufficient to use hydra:expects https://schema.org/ImageObject or something similar?

I don't think so. My server can process image/png only, JPEG's are off-limits due to licensing :P. I'd like to express that.

[angelo-v]

I don't think so. My server can process image/png only, JPEG's are off-limits due to licensing :P. I'd like to express that.

Agreed. We could do that if it was possible to specify it further, as ImageObject with a specific schema:encodingFormat similar to what I said in #183 (comment)

[alien-mcl]

We could do that if it was possible to specify it further,
as ImageObject with a specific schema:encodingFormat similar to what I said in #183 (comment)

Ah, I've cached that thought with my comment.

Indeed that approach with constraint-like is interesting. I think it could sit side-by-side with old hydra:Class way just not to break anything

[tpluscode]

This sounds great indeed. But I think we're way out of scope of Hydra Core...

[alien-mcl]

But I think we're way out of scope of Hydra Core

Why is that? I believe having a generic mechanism that would allow to describe precisely what kind of resources are expected/returned is mandatory in the core.

Core won't contain any mentioned image definitions, but a raw tools so other can make those definitions

[tpluscode]

I do agree. Without more concrete example it's hard to judge the intentions. I meant this remarks as precaution that schema.org for example has no place in the Core.

It could, however, be a part of an auxiliary vocabulary, to be used together with Hydra, to define image-specific constraints.

The problem as I understand it, is that we'd want to describe constraints for non-RDF payloads using RDF structures. In the example you were discussing, describe specifics of an image file using schema:ImageObject. schema.org would not be the only possibility. And similar could be done with other media files (audio, video).

[alien-mcl]

The problem as I understand it, is that we'd want to describe
constraints for non-RDF payloads using RDF structures.

We'd want to describe both that way. Currently by saying hydra:returns some:Class we're saying that the operation returns a resource that matches a specification (a specific class in that case). This shortcut seems not well understood - the specification approach could make that statement more direct.

It would also enable the vocabulary for non-RDF specifications and RDF specifications that could went far beyond simple class matching (in API documentations you could specify returned collection)

[alien-mcl]

I've changed the approach with this issue this time. This time I've dropped the resource specification and I didn't got towards request specification neither. All I did was a slight modification of returnsHeader and expectsHeader so it is possible to provide possible header values. This way it would be possible to describe an expected resource to be any of provided Content-Type header values for upload or possible Content-Type serializations of the resource.

[tpluscode]

I think I have one reservation about the current proposal, regarding possibleHeaderValue.

Naming aside, I think it's not universally sufficient as I see two distinct cases one might want to express:

• open set, especially for response headers, indicating that other values are possible
• closed set, especially for request headers, for example where a content-type would only be allowed to be one of the values provided

In the latter case, I think we'd need some way to assert that fact.

And for the name I propose more terse possibleValue

[alien-mcl]

Ok - I've added an additional predicate to indicate a closed set. I decided not to introduce i.e. possibleValue for open set and headerValue for closed set as it would be impossible to fine-tune the semantics without using some advanced OWL constructs as these should not be used simultaneously.