Re: [odata] Organization of OData Documents

[Stefan Drees <stefan@drees.name>]

On 19.09.12 02:08, Michael Pizzo wrote:

I had agreed to take offline a discussion on how we would ideally organize the set of OData documents.

 

According to the OASIS categorization of documents, I believe we are best served by identifying three related Work Products as follows:

1.       Multi-part OData Core

a.       Part 0: Core protocol document (includes normative reference to ABNF text document)

b.      Part 1: URL conventions document

c.       Part 2: CSDL document (includes non-normative reference to textual XSD for CSDL)

2.       Standalone OData Atom format

3.       Standalone OData JSON format

 

Batch processing (which is small) should be incorporated into 1a).

This proposed organization seeks to:

1)      Clearly identify the core information that a reader needs to read to understand the specification (1a)

2)      Clearly identify the complete set of information that an implementer needs to implement the core specification (1)

3)      Identify multiple formats that may be used with (1)

4)      While minimizing the total number of documents

 

Thoughts?

thanks for the organizational breakdown of work products. Taking into account the feedback/questions of Robin and Ralf, I would suggest the following
modified structure:

Structure of Work Products:

1. Multi-part OData Core
1. Part 1: Core protocol document (includes Batch processing "content" and the normative reference to ABNF [minus URL minus JSON rules] text document if and only if file is not empty after "refactoring")
   
2. Part 2: URL conventions document (includes normative reference to URL conventions ABNF text document)
3. Part 3: CSDL document (includes non-normative references to CSDL schema text documents and hopefully hints, why this is not normative?)
2. Standalone OData Atom format (is there also a schema, which might be factored out to aid implementers in validating?)
   
3. Standalone OData JSON format (includes normative references to ABNF JSON format text document)

(I marked up changes and "questions" as italic in the HTML.)

What do you think?

All the best,
Stefan.

Attachment: smime.p7s
Description: S/MIME Kryptografische Unterschrift