Closed lanthaler closed 9 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?
@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?
The outcome of the issue is relevant for the @LinkedDataFragments use case, as documented on the Hydra mailing list.
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.
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).
@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:
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.)
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.
@gkellogg Great! That would be a good solution then.
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:
@
symbol^
(just one) and then the URL without enclosing it in <>
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/
Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0083.html
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"
}
]
}
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
.
Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Oct/0119.html
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
_Raised by Ruben Verborgh:_
How should a client pass the value in the template? Given the example above,
?author
maps tofoaf: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 withhydra: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 thishydra:IriTemplateMapping
.How can it translate this data into an actual HTTP request? Seems like a basic question that Hydra should be able to answer.