search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
138 stars 26 forks source link

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

Closed alien-mcl closed 3 years ago

alien-mcl commented 5 years ago

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

angelo-v commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 https://github.com/HydraCG/Specifications/pull/183#issuecomment-463675355

alien-mcl commented 5 years ago

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 commented 5 years ago

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

alien-mcl commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 3 years ago

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 commented 3 years ago

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:

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 commented 3 years ago

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.