Usage of IriTemplate

[tpluscode]

I've started implementing IriTemplate in Alcaeus, the old Heracles.

My API is simple:

const iriTemplate = new IriTemplate(); // part of representation/docs
const variables = {};

const expanded = iriTemplate.expand(variables);

Taking the example from specs:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "IriTemplate",
  "template": "http://api.example.com/issues{?q}",
  "variableRepresentation": "BasicRepresentation",
  "mapping": [
    {
      "@type": "IriTemplateMapping",
      "variable": "q",
      "property": "hydra:freetextQuery",
      "required": true
    }
  ]
}

My question is about the actual contents of the variables dictionary.

I understand it should use property URIs as keys, which are they placed in the template variables?

{
  "http://www.w3.org/ns/hydra/core#freetextQuery": "search criteria"
}

To produce http://api.example.com/issues?q=search%20criteria?

[alien-mcl]

I'd put my bet on variable instead.

{
  "q": "search criteria"
}

This won't get non-RDF developers scared and seams cleaner. This also enables you to use existing libraries that handle URI templating. Having the mapping details you can translate predicates to variables.

[tpluscode]

Yes, I'd though similar until today but see this comment under #30.

@lanthaler's examples look like the values from JSON-LD. It made me thing that maybe I was wrong after all.

I was also thinking that maybe both should be supported. So that I'd look for either http://www.w3.org/ns/hydra/core#freetextQuery or q.

[alien-mcl]

Well, being prompt for both is still doable. I'd be careful with using raw JSON-LD structures. Some strongly typed API would be better, i.e.

new IriTemplateBuilder()
    .withVariable("q").setTo("search criteria")
    .withVariable("http://some.uri/).setTo("text")
    .withVariable("f").setTo("me", "en")
    .asObject();

[lanthaler]

Both are fine. Eventually I'd prefer to lean on the property URLs but for that to make sense, we need to specify in much more detail what they actually mean and what their relationship to the operation/target is.