Resource types / patterns for Path Item Objects

[ralfhandl]

OData services mainly consist of "entity sets" which are collections of "entities" that are uniquely identified by their key property values within their entity set.

So a "read-only entity set" will support

• GET on the set, with a predefined set of query options for paging ($top, $skip), filtering, sorting, free-text search, ...
• GET on the individual entity by specifying the entity set plus the key property values

And "updatable entity sets" will in addition support

• POST on the set to add new entities
• PATCH and DELETE on individual entities

Basically an OData-aware client only needs the entity set name, the structure definition for each entity, and the "readonly/updatable" information to know the path templates and expected request and response bodies, allowed headers, possible response codes etc.

Spelling this out for OData-unaware clients takes a lot of highly repetitive content in the /paths section.

It would be great to have resource types or parameterized templates/patterns for Path Item objects that would allow to specify

/Products:
ReadOnlyEntitySetOfType
{ $ref: #/definitions/Product }
/People:
UpdatableEntitySetOfType
{ $ref: #/definitions/Person }

Please note that we foresee (well, actually have :-) services with dozens or hundreds of entity sets, so this would significantly reduce the size of the OpenAPI documents.

[webron]

Parent issue: #560

[fehguy]

@OAI/tdc removing from OpenAPI.Next proposal and making a future consideration.

[webron]

Agreed.

[ralfhandl]

See OAI/sig-moonwalk#30

[handrews]

As noted in the previous comment, the best place to continue this is in the Moonwalk repository, in the linked discussion. Closing out of this repo - @ralfhandl if you think there's something that we might consider here for 3.x please comment and I'll be happy to re-open.

[ralfhandl]

Let's tackle it in Moonwalk first and then check whether we want to downport it to 3.x