Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expansion of IRI templates should be better documented #30

Closed
lanthaler opened this issue Feb 3, 2014 · 14 comments
Closed

Expansion of IRI templates should be better documented #30

lanthaler opened this issue Feb 3, 2014 · 14 comments

Comments

@lanthaler
Copy link
Member

@lanthaler lanthaler commented Feb 3, 2014

_Raised by Ruben Verborgh:_

{
  "@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
Copy link

@akuckartz akuckartz commented Feb 9, 2014

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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Feb 11, 2014

@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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Mar 14, 2014

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

@gkellogg
Copy link

@gkellogg gkellogg commented Mar 14, 2014

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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Mar 14, 2014

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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Mar 16, 2014

@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:

  1. _: or ? => blank node / variable
  2. angular brackets? => IRI
  3. quotes? => literal
  4. “alphanum chars, colon, alphanum chars”? => prefixed name
  5. 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
Copy link

@gkellogg gkellogg commented Mar 16, 2014

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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Mar 16, 2014

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

@lanthaler
Copy link
Member Author

@lanthaler lanthaler commented Apr 19, 2014

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
Copy link
Member Author

@lanthaler lanthaler commented Jul 16, 2014

@jaw111
Copy link
Contributor

@jaw111 jaw111 commented Jul 26, 2014

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
Copy link
Contributor

@RubenVerborgh RubenVerborgh commented Jul 26, 2014

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.

RubenVerborgh referenced this issue in rdfjs/N3.js Aug 10, 2014
This is a breaking interface change.
@lanthaler
Copy link
Member Author

@lanthaler lanthaler commented Oct 20, 2014

@lanthaler lanthaler added the resolved label Oct 27, 2014
@lanthaler
Copy link
Member Author

@lanthaler lanthaler commented Oct 27, 2014

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
RubenVerborgh added a commit that referenced this issue Dec 22, 2014
lanthaler added a commit that referenced this issue Dec 29, 2014
- Removed second example as they only differed in the property used
- Add variableRepresentation to the example
- Converted the description of BasicRepresentation and ExplicitRepresentation from a definition list to a simple paragraph to be consistent with the rest of the document
- Moved warning up
- Added an exemplary IRI Template to the example comparing the two representation formats

This addresses #30.
lanthaler added a commit that referenced this issue Dec 29, 2014
…tation to the context

... and minor tweaks to their description.

This addresses #30
RubenVerborgh added a commit that referenced this issue Dec 30, 2014
- Add variable representations to Core Vocabulary.
- Append regular template example before free text.
- When introducing the concept of template variables, it's more instructive to show the regular case first. Also, this will make the explanation of representations more clear.
- Explain variable representations.
- Add representation examples.
- Warn about ExplicitRepresentation versus Turtle.

This addresses #30
@lanthaler lanthaler closed this in 98a2e7d Dec 30, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.