REST Profile - Document Structure

[Hal Lockhart <hal.lockhart@oracle.com>]

I have a number of different kinds of comments about the REST Profile and Media types which will post separately to allow the discussion to take place in distinct threads.

The Conformance Section of an OASIS Standards-Track document is not intended to include all the normative material in the specification. Instead it is intended to be a short, easy to find and clear set of statements about what kinds of conformance can be claimed to the document and precisely what parts of the document you have to implement in order to claim that conformance. Further, in this TC we have adopted the custom of associating an identifier (URN) with each type of conformance, with the idea that it may be used to announce the capabilities of a software component.

For example, in the REST Profile as it currently stands, you could say that an implementation could conform as a PDP by implementing such and such or could conform as a PAP by implementing such and such. Anything required of both PAP and PDP would be listed under both. Alternatively, you could say that conformance requires implementation of all normative sections (listing them).

It is usual to design the document structure with this in mind, e.g. separating normative material from examples, describing distinct forms of behavior in different sections, so they can be identified in the Conformance section.

Hal