Expansion of IRI templates should be better documented

lanthaler commented 10 years ago

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "IriTemplate",
  "template": "http://api.example.com/issues{?author,topic}",
  "mappings": [
    {
      "@type": "IriTemplateMapping",
      "variable": "author",
      "property": "foaf:maker"
    },
    {
      "@type": "IriTemplateMapping",
      "variable": "topic",
      "property": "hydra:freetextQuery"
    }
  ]
}

How should a client pass the value in the template? Given the example above, ?author maps to foaf:maker. But what value should be put into the URL? The URI of the maker, that person's full name, or only last name and initial? And in any of those cases, how do we communicate that? Right now, we cannot say "the label of the foaf:maker".

And then again, which maker are we talking about? Is it the result resources which have that foaf:maker as property? If it is, that definition doesn't work with hydra:freetextQuery. Of course, I understand we don't want to go to deep, but I am actually implementing this use case now: the client has data and sees this hydra:IriTemplateMapping.

How can it translate this data into an actual HTTP request? Seems like a basic question that Hydra should be able to answer.

akuckartz commented 10 years ago

How should a client pass the value in the template?

My view: The IRI of the foaf:maker is the value which should be passed. Can it be abbreviated using a context?

RubenVerborgh commented 10 years ago

@akuckartz I do agree with you there.

However, I also see the issue on how to put a value into a URL, depending on its type. If it's an IRI, how do we distinguish it from a literal? If we abbreviate, what kind of context can we assume?

RubenVerborgh commented 10 years ago

The outcome of the issue is relevant for the @LinkedDataFragments use case, as documented on the Hydra mailing list.

gkellogg commented 10 years ago

As I mentioned in an email reply, I think this can be unambiguous:

?subject=http%3A%2F%2Fexample%2Ffoo

URI encoded, un-quoted value is a URI or BNode (although the use of a BNode vs. just unspecified ids dubious in a triple pattern.

?predicate=schema%3Aname

URI encoded, un-quoted value is a could be a compact IRI/PName. It can be distinguished from an absolute IRI if the string prefix matches a prefix name defined either as an RDFa @prefix (or default prefix from the initial context) or a prefix defined in a JSON-LD context supplied to the client, or a prefix defined in some alternative RDF serialization supplied using content-negotiation. However, this has marginal value, and is probably not necessary as a general case.

?object=%22John%20Henry%22

URI encoded, quoted value is a string literal, which would probably match any literal having that lexical value

?object=..%2Fbaz

Relative URI? Probably not necessary, but it can be determined using straight-forward IRI matching rules.

?object=%22John%20Henry%22@en

URI encoded, quoted value with language tag is a language-tagged literal

?object=%22John%20Henry%22&language=en

Alternatively, specify language as another query parameter.

RubenVerborgh commented 10 years ago

That might be workable, but I'm not in favor of the extra language parameter. That's too confusing and appears (but of course isn't) relate to the document language (as in the pre-conneg age).

RubenVerborgh commented 10 years ago

@gkellogg Concerning “unambiguous”, not that my current reason for including angular brackets < > around IRIs is to avoid confusion when dealing with prefixes. Although uncommon, strictly speaking, urn:name and <urn:name> are different things in Turtle. So with your example, I cannot know whether you mean <schema:name> or <http://schema.org/name>. And I have run into cases where this is a problem (just think about the http prefix).

So I think if we decide to support both prefixes names and IRIs (and we should at least support the latter), there should be some explicit mechanism to distinguish between them. Or we can just not support prefixed names; no harm done there.

My server currently handles this as follows:

_: or ? => blank node / variable
angular brackets? => IRI
quotes? => literal
“alphanum chars, colon, alphanum chars”? => prefixed name
none of the above? => IRI

But I'd rather not have this last step in the spec; it's essentially a fallback plan when no other solution was found. (And with this implementation mostly meaning: the user forgot angular brackets.)

gkellogg commented 10 years ago

The prefix/IRI issue is exactly that faced by RDFa, so I think the solution can be the same. Also, if a matching prefix is defined, it's a compact IRI, otherwise, it's a scheme-based IRI. The use of angle brackets is Turtle/sparql specific, and not really developer friendly for this use case, IMO.

RubenVerborgh commented 10 years ago

@gkellogg Great! That would be a good solution then.

lanthaler commented 10 years ago

PROPOSAL: By default, when expanding a IRI template, use only the lexical representation of the value or the IRI (no quoting). Add a flag expandedRepresentation to IriTemplateMapping, that, if set to true, changes the expansion to work as follows:

The lexical representation is enclosed in quotes with no escaping of the value itself
the datatype xsd:string is always omitted
language tags are appended to the lexical representation by using an @ symbol
datatypes are added using ^ (just one) and then the URL without enclosing it in <>
URLs are kept as they are

Thus, the following values in Turtle notation expand to the following strings when used in a IRI template

"""Value with a " inside""" --> "Value with a " inside" (without the """ the inner quote would have to be escaped in Turtle)
"English"@en --> "English"@en
"24"^^<xsd:integer> --> "24"^http://www.w3.org/2001/XMLSchema#integer
http://example.com/ --> http://example.com/

lanthaler commented 10 years ago

Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0083.html

jaw111 commented 10 years ago

How about adding a valueType to IriTemplateMapping that would reference to a datatype that can be used to decide how the parameter value should be interpreted by the server. This could be predefined for the common datatypes already described above, but could be used to allow for user-defined extensions. This would also clearly indicate to the client what the expected datatype for a value is.

For example:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "IriTemplate",
  "template": "http://api.example.com/issues{?author,topic}",
  "mappings": [
    {
      "@type": "IriTemplateMapping",
      "variable": "author",
      "property": "foaf:maker",
      "valueType": "xsd:anyURI"
    },
    {
      "@type": "IriTemplateMapping",
      "variable": "topic",
      "property": "hydra:freetextQuery",
      "valueType": "xsd:string"
    }
  ]
}

RubenVerborgh commented 10 years ago

I think that's a lot of freedom and complexity. Can't we just be consistent within one template? Note that this information actually belongs in the rdfs:range of the property.

lanthaler commented 9 years ago

Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Oct/0119.html

lanthaler commented 9 years ago

RESOLVED: Introduce a new property hydra:variableRepresentation that can be used on a hydra:IriTemplate to define how a client replaces variables in the IRI template with values. For the time being, Hydra will support two representations: hydra:BasicRepresentation and hydra:ExplicitRepresentation. The former, hydra:BasicRepresentation, serializes just the lexical form, but omits language and type information. hydra:ExplicitRepresentation on the other hand includes language and type information.

The difference between the two variable representation formats is illustrated by the following examples.

_hydra:BasicRepresentation_

<http://example.com>
{ "@id": "http://example.com" }
  ----> http://example.com

"A simple string"
{ "@value": "A simple string" }
  ----> A simple string

"""Also this " works"""
{ "@value": "Also this \" works" }
  ----> Also this " works

"A language-tagged string"@en
{ "@value": "A language-tagged string", "@language": "en" }
  ----> A language-tagged string

"5.5"^^xsd:xsd:decimal
{ "@value": "5.5", "@language": "xsd:decimal" }
  ----> 5.5

_hydra:ExplicitRepresentation_

<http://example.com>
{ "@id": "http://example.com" }
  ----> http://example.com

"A simple string"
{ "@value": "A simple string" }
  ----> "A simple string"
  or -> "A simple string"^^http://www.w3.org/2001/XMLSchema#string

"""Also this " works"""
{ "@value": "Also this \" works" }
  ----> "Also this " works"
  or -> "Also this " works"^^http://www.w3.org/2001/XMLSchema#string

"A language-tagged string"@en
{ "@value": "A language-tagged string", "@language": "en" }
  ----> "A language-tagged string"@en

"5.5"^^xsd:xsd:decimal
{ "@value": "5.5", "@language": "xsd:decimal" }
  ----> "5.5"^^http://www.w3.org/2001/XMLSchema#decimal

HydraCG / Specifications

Expansion of IRI templates should be better documented #30