[Specifications] How to specify what the variables in an IriTemplate refer to? (#254)

madjar has just created a new issue for https://github.com/HydraCG/Specifications:

== How to specify what the variables in an IriTemplate refer to? ==
Hello there,

I've been looking with curiosity at hydra. The use case that I currently have in mind as I read the spec is to document an existing API with hydra, possibly as a way to see what kind of interesting clients I can generate from the hydra doc. I'm posting my question here in hope that there are still people around to answer it.

One thing I'm not clear on is, in the case where I have an url of the form `http://api.example.com/issues/{issue_id}/comments`. If I want to document the entire API, I will have to use an IriTemplate, such as

```
{
        "@type": "hydra:IriTemplate",
        "template": "/issues/{issue_id}/comments",
        "mapping": [
            {
                "variable": "issue_id",
                "property": "vocab:id",
        ]
    }
```.

The question is: how does the client know that `issue_id` (which I can say is a `vocab:id` property, that we can assume is defined on `Issue`) is indeed the id of an issue? Is there a way to document it? Because otherwise I don't see how I can document that this endpoint is how the link between issues and comments is resolved.


---

As an aside: I tried looking at http://www.markus-lanthaler.com/hydra/api-demo/ and http://www.markus-lanthaler.com/hydra/event-api/ in hope of getting some examples, but they don't seem online anymore, and I couldn't get the to run locally. Are there any known hydra server running publicly that one could query to understand how to use it?

Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/254 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 16 January 2026 13:16:17 UTC