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

Comments

Projects
None yet
5 participants
@lanthaler
Member

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

This comment has been minimized.

Show comment
Hide comment
@akuckartz

akuckartz 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?

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Feb 11, 2014

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Mar 14, 2014

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@gkellogg

gkellogg 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.

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Mar 14, 2014

Contributor

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).

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Mar 16, 2014

Contributor

@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.)

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@gkellogg

gkellogg 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.

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Mar 16, 2014

Contributor

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

Contributor

RubenVerborgh commented Mar 16, 2014

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

@lanthaler

This comment has been minimized.

Show comment
Hide comment
@lanthaler

lanthaler Apr 19, 2014

Member

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/
Member

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

This comment has been minimized.

Show comment
Hide comment
Member

lanthaler commented Jul 16, 2014

@jaw111

This comment has been minimized.

Show comment
Hide comment
@jaw111

jaw111 Jul 26, 2014

Contributor

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"
    }
  ]
}
Contributor

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

This comment has been minimized.

Show comment
Hide comment
@RubenVerborgh

RubenVerborgh Jul 26, 2014

Contributor

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.

Contributor

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

Remove angular brackets from types.
This is a breaking interface change.
@lanthaler

This comment has been minimized.

Show comment
Hide comment
Member

lanthaler commented Oct 20, 2014

@lanthaler lanthaler added the resolved label Oct 27, 2014

@lanthaler

This comment has been minimized.

Show comment
Hide comment
@lanthaler

lanthaler Oct 27, 2014

Member

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
Member

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

Minor edits to the variableRepresentation section
- 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

Add variableRepresentation, BasicRepresentation, and ExplicitRepresen…
…tation to the context

... and minor tweaks to their description.

This addresses #30

RubenVerborgh added a commit that referenced this issue Dec 30, 2014

Detail IRI template expansion in vocabulary and spec
- 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