Filter enumeration

[Nek-]

Hello,

Imagine the following call (inspired by filtering events):

GET /api/events

HTTP 200 OK

{
    "@context": "/api/context.jsonld",
    "@id": "/api/events",
    "@type": "PartialCollection",
    "manages": {
      "property": "rdf:type",
      "object": "schema:Event"
    },
    "totalItems": 150000,
    "members": [
        {
            "@id": "/api/events/1",
            "eventName": "Event 1",
            "eventDescription": "Some event 1",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19",
            "manager": "/api/managers/8"
        },
        {
            "@id": "/api/events/2",
            "eventName": "Event 2",
            "eventDescription": "Some event 2",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19",
            "manager": "/api/managers/34"
        },
        {
            "@id": "/api/events/3",
            "eventName": "Event 3",
            "eventDescription": "Some event 3",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19",
            "manager": "/api/managers/9"
        },
        {
            "@id": "/api/events/4",
            "eventName": "Event 4",
            "eventDescription": "Some event 4",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19",
            "manager": "/api/managers/12"
        },
        {
            "@id": "/api/events/4",
            "eventName": "Event 1",
            "eventDescription": "Some event 1",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19",
            "manager": "/api/managers/50"
        }
    ],
    // Pagination markup missing, let's imagine it's here :)
    "search": {
        "@type": "IriTemplate",
        "template": "http://example.com/api/events{?eventName}",
        "variableRepresentation": "BasicRepresentation",
        "mapping": [
            {
                "@type": "IriTemplateMapping",
                "variable": "manager",
                "property": "???",
                "required": false
            }
        ]
    }
}

How can the client be aware of what manager he can ask for ? Considering it may be many kind of manager and he can't access to the endpoint /api/managers for security reasons (imagine not all manager are public or related to events).

[alien-mcl]

If that knowledge (managers) is not exposed by the server, I believe there are few limited options here:

• client has that knowledge hardcoded (the ugliest but the most obvious)
• there is other place that can provide that knowledge
• server can provide that knowledge within returned (partial) collection's payload - it's an RDF graph, thus it may contain several resources
• client can obtain that knowledge from the end-user (i.e. with some kind of form or input field)
• client can use any value - server will return with non-2XX response if something goes wrong or just empty result set if no match is found so the client will discover on the fly that the value used was somehow incorrect.

Generally, variable mapping only says on which property given value will be used by the server for filtering - it does not say where this value should come from.

[tpluscode]

I remember now my problem with current way of filling in the IRI templates.

What if the search query for managers was using concrete URIs but manager's name?

{
  "mapping": [{
    "variable": "managerName",
    "property": "schema:name" // ??
  }]
}

Almost like a free text query but the managerName/schema:name property would not represent a property of Event but of Manager instead?

[alien-mcl]

Yep - we had this discussion on last call. I've got a branch with implementation of a strategy used for filling IRI templates in operations here that expects two objects - resource used as a body and auxiliary resource with values from outside of the payload context. Not perfect, but we need to start with something.

[lanthaler]

Yeah, this is a known issue. The semantics of IRI template variables aren't well defined at the moment. See also #45.

[elf-pavlik]

In this use case, I probably would prefer Triple Pattern Fragment https://www.hydra-cg.com/spec/latest/triple-pattern-fragments/#controls rather than approach it as filtering a collection using some crazy IriTemplate

What if the search query for managers was using concrete URIs but manager's name?

You can see LDF client http://client.linkeddatafragments.org/ having something similar as the default example: DIrectors of movies starring 'Brad Pitt'

Use case you mention here seems even simpler and comparable to just Movies starring 'Brad Pitt' - Events managed by 'Jane Doe'

[tpluscode]

What's crazy about IRI Templates? It's a standard way for letting client mint the URIs. While imposing TPF/LDF is just dumping another load of knowledge required on top of JSON-LD/Hydra. I don't think it's useful to devs coming outside of our circle

[elf-pavlik]

I didn't call IRI Templates crazy in general. TPF/LDF use IRI Template but rather simple one and seems to cover use case: Events managed by 'Jane Doe' in IMO elegant way. I would like to see example of mapping which tries to cover the same use case with just one template. I think such mapping could get crazy compared to how TPF handles it. Could you provide a snippet for how you imagine such mapping?

[alien-mcl]

I strongly agree with @tpluscode. I'd prefer to move towards some more generic request templating mechanism, where server would define what goes where (i.e. this value goes into the body, this into the header and that into an URL). I recall we've touched this approach during the last call as it would bind all pieces altogether (operation extended with a body/header template as a description of the request, IRI template as description of the URL and action as semantic description of what is going to happen). Such approach will allow server to define whether it prefers i.e. HTTP LINK/UNLINK or some specific class expected within the body or some other variation.