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

> On October 13, 2014 at 6:36 PM Markus Lanthaler <markus.lanthaler@gmx.net>
> wrote:
>
>
> +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.
>

I guess the question is whether one would wish to capture the example body in
the API docs to enable a mock server, or link out to some existing example
resource (like a Gist)... or allow for both.
Could we re-use existing RDF vocabs like http: [1] and cnt: [2] to model this
information?

John

[1] http://www.w3.org/TR/HTTP-in-RDF10/
[2] http://www.w3.org/TR/Content-in-RDF10/

>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>
>