Re: [Specifications] Simplify discovery of collections that contain resources of a certain type

During last telecon I took action to extend current use cases in a way that provides clear reason for *discovery of collections that contain resources of a certain type*. Taking another look at [EntryPoint from our Use Case](https://github.com/HydraCG/Specifications/blob/master/drafts/use-cases/1.entry-point.md) it seems for me that having `examplevocab:events` and not using collection of all events itself as entry point already suggests need for such discovery. Currently also [client in Creating a new event step](https://github.com/HydraCG/Specifications/blob/master/drafts/use-cases/5.creating-new-event.md) uses `.getLink('http://example.com/vocab#events')` on EntryPoint to discover that collection of events. If we just follow the guiding principle from our last telecon (captured in previous comment) and start by defining preferred terms in `hydra:` namespace. Would changes below make sense?

```json
{
    "@context": "/api/context.jsonld",
    "@id": "/api",
    "@type": "hydra:EntryPoint",
    "partition": {
        "@id": "/api/events",
        "title": "List of events",
        "@type": "hydra:Collection",
        "memberType": "schema:Event",
        "operation": [
            {
                "@type": ["hydra:Operation", "schema:CreateAction"],
                "title": "Create new event",
                "method": "POST",
                "expects": "schema:Event"
            }
        ]
    }
}
```

```javascript
var event = { ... };
var client = new HydraClient();
var operation = client.get("http://example.com")
    .getApiDocumentation()
    .getEntryPoint()
    .getPartitionByMemberType('http://schema.org/Event')
    .getOperationOfType('http://schema.org/CreateAction');
client.invoke(operation, event);
```

We should keep in mind that [proposed on a wiki page Collection Design](https://www.w3.org/community/hydra/wiki/Collection_Design) already partially addresses the requirement to discover collection of entities related by particular predicate (property) with some given entity. In our case here we have different case where **we need to relate the *EntryPoint* to a *Collection* with has members of particular type**. If we use for that some property like `hydra:partition` (or whatever we may want to call it) we should possible possibly define that it SHOULD NOT reference more then one collection with the same `hydra:memberType` (or whatever we may want to call it). I can't really think of a use case where one would want to reference more then one with members of the same type, and still expect client to choose between those collections in some meaningful way.

To further clarify our need for discovery of such 'member type based partitions', we could add venues to our api (`schema:Place`) which would give use following EntryPoint:

```json
{
    "@context": "/api/context.jsonld",
    "@id": "/api",
    "@type": "hydra:EntryPoint",
    "partition": [
      {
        "@id": "/api/events",
        "title": "List of events",
        "@type": "hydra:Collection",
        "memberType": "schema:Event",
        "operation": [
            {
                "@type": ["hydra:Operation", "schema:CreateAction"],
                "title": "Create new event",
                "method": "POST",
                "expects": "schema:Event"
            }
        ]
      },
      {
        "@id": "/api/venues",
        "title": "List of venues",
        "@type": "hydra:Collection",
        "memberType": "schema:Place",
        "operation": [
            {
                "@type": ["hydra:Operation", "schema:CreateAction"],
                "title": "Create new venue",
                "method": "POST",
                "expects": "schema:Place"
            }
        ]
      }
    ]
}
```

-- 
GitHub Notification of comment by elf-pavlik
Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/126#issuecomment-315932048 using your GitHub account

Received on Tuesday, 18 July 2017 01:32:03 UTC