RE: Finalizing the IriTemplate design - serialization name (ISSUE-30 & ISSUE-17)

+CC Dimitri (there's a question for you at the end of this mail)

On Thursday, October 09, 2014 9:22 PM, John Walker wrote:
>> On October 9, 2014 at 3:49 PM Markus Lanthaler wrote: 
>> On 9 Okt 2014 at 09:59, Ruben Verborgh wrote: 
>> >> hydra:ExplicitRepresentation 
>> > 
>> > +1 
>> > 
>> > Something perhaps more important than the name 
>> > (and I hope I'm not digressing by mentioning this) 
>> > is that the vocabulary should clearly explain the term. 
>> > I wonder if there is perhaps an :example property 
>> > so that we can attach human-readable examples 
>> > of instances to hydra:ExplicitRepresentation. 
>> 
>> Oh yeah, definitely. I can't remember whether we discussed this on the list 
>> or whether this is something I just discussed with Gregg offline but I'm a 
>> big fan of such an example property. Clearly, this is something that helps 
>> humans, not machines. But it allows as to build much better human-targeting 
>> documentation out of a Hydra ApiDocumentation and also opens the door to 
>> tools like mock servers etc. 
>> 
>> I just checked and apparently we didn't have an issue for this yet. We'll 
>> track this as ISSUE-74 [1] now. 
> 
> Sounds like a good idea to me. 
>   
> Is this something that could also be used to give example values for
> properties, certainly useful for mock servers.  I can easily see how
> this would work for datatype properties, but a bit less clear for
> object properties.  By this I mean how to indicate if it is expected
> to embed a description of the entity being linked to in the
> representation or just a reference to it.

I asked me the same question myself in the past. The simplest solution would be to simply limit this to strings (or typed literals to support JSON-LD/Turtle/... snippets) but that might lead to suprising results.


> I see other API definition languages like RAML give possibility to
> provide complete example of the body of a POST, not sure I'm a fan of
> that.

IMO for operations that's really the only reasonable choice as otherwise it would be impossible to, e.g., include examples with invalid JSON.

The main question here I think is really whether this needs to be granular and understandable to a machine or not. My current answer is no. This is (almost) exclusively for humans and mock servers don't need to understand the exemplary responses, they just need to send them.

What's your take on this? It would also be interesting to hear what Dimitri thinks about this as I know he used JSON-LD + Hydra + RAML in some of his projects.


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 13 October 2014 16:36:44 UTC