A recurring pattern of behaviour is seen among several of the protocol facets. To highlight this pattern and to make the spec easier to read the pattern should be called out early in the document and then referred to later as appropriate.
Highlighting a common idiom will make the protocol easier to understand.
Add the following text to section 2, note that this is following the form outlined in PaceProblemStatements.
2.1 The Collection Management Idiom
Several facets of the Atom Publishing Protocol have similar methods of interaction. Currently such patterns are not called out and this could end up making the text repetitive.
2.1.2 Normative Text
Several facets of the Atom Publishing Protocol fall into the same pattern of behavior. These common interaction patterns are called idioms, and the most common idiom is "Collection Management".
In this idiom we are managing a collection of resources that have the following properties:
Each resource in the collection has it's own URI. This is called the Member Resource, there is the Member Resource URI which points to the Member Resource. Each resource supports GET, PUT and DELETE for updating the resource.
There is a top level resource that represent the collection of those resources. This is called the Collection Resource and the URI for the top level resource of a collection is the Collection URI. GETting that resource returns a representation that enumerates some or all of the resources in the collection. POSTing an appropriate representation to this top level resource will create a new resource in the collection with that representation.
What we have here is a set, with the ability to add and remove elements from the set and the ability to inspect and update elements that are already in the set.
Collection membership is not an indication that a resource will return a representation with a specific media type.
2.1.3 Design Rationale
Pointing out those patterns early, giving them names, and outlining the constraints will make latter parts of the spec easier to follow (and hopefully easier to write). For example, we could start by saying that managing users follows the Collection Management Idiom where UsersURI is the Collection Item URI and UserManagementURI is the Member Resource URI. It also useful for pointing out differences, for example PaceSimpleResourcePosting follows the Collection Management idiom but it doesn't have a Collection URI. Of course, writing that may make you question why it doesn't have one, which is a good thing.
Note that the resouces in the collection might not have the same media type. For example the resource created via PaceSimpleResourcePosting may be of type gifs, jpegs, pdfs, etc. Entries in the entry collection do have the same media type: application/atom+xml. This is one of those things we will have to call out on a case-by-case basis.
[GregStein] Why not use the existing term "Member Resource" instead of "Collection Item"?
[JoeGregorio] Updated to use the term "Member Resource"