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

> On October 9, 2014 at 3:49 PM Markus Lanthaler <markus.lanthaler@gmx.net>
> 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 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.

John