OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: [OASIS Issue Tracker] Commented: (ODATA-20) Feedback to document revision


    [ http://tools.oasis-open.org/issues/browse/ODATA-20?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=30980#action_30980 ] 

Stefan Drees commented on ODATA-20:
-----------------------------------

Note: A HTML-version of these comments is available at URL=https://www.oasis-open.org/committees/document.php?document_id=46711&wg_abbrev=odata and in the hope, that it helps those that find markdown a bit less readable than the rendered version.

Thanks a lot for the interesting read, Martin!

As already practiced with the JSON Format document revision issue, I prefer to put my complete feedback of the first iteration into one comment, so that you may consider it as a whole and we do not drown in a flood of minor issues on a phrase level of the documents.

If there is interest in or objection against specific feedback items, I will be happy to invest the extra work and pull these into dedicated JIRA issues.

Comments are structured by bracketing the location range in the document revision [OData ATOM Format Version 1.0 Working Draft 01](https://www.oasis-open.org/committees/download.php/46705/odata-atom-format-v1.0-wd01-2012-08-17-MZ.doc) and then detailing this in globally enumerated feedback items (currently A-M).

Note: I paused reviewing around page 17 i.e. at "5.1.7.4 The title attribute of an atom:link Element Representing Relationship Links"

#1 Introduction#

##Feedback A)##

1st para, second phrase:

This document describes the OData Atom Format returned from an OData Service when requesting the application/atom+xml mime type.

**SHOULD** be replaced with eg:

This document describes the OData Atom Format `of the payload` returned from an OData Service when requesting the application/atom+xml mime type.

Benefit `is a more precise description and introduces the term payload used in the following para.`


##Feedback B)##

2nd para, 13th list item:

* an error

**SHOULD** be replace with eg:

* an error` document`

Benefit `is a more precise description of the concrete form which is described by that item`. If it is an OData type, than this should be noted accordinglye.

#1.2 Normative References#

##Feedback C)##

The `sequence of the references` **SHOULD** be realized as an `alphabetic ordering on the reflabels` (inside the square brackets). 

Benefit: `Since already a left-rooted naming convention of the reflabels is implemented, there is no reason to not sort these entries alphabetically.` Note: Otherwise a reader might expect grouping by topic or chronological ordering, which is not the case here.

##Feedback D)##

The refentries with respect to IETF RFCs **MAY** be changed to consistently bear sub entries with a space between the string "IETF RFC" and the number of the RFC like in the refentry with label **[RFC2119]**.
Eg. for **[RFC5023]** write `IETF RFC 5023` instead of  `IETF RFC5023`.

Benefit is `consistency and readability`.

##Feedback E)##

Missing reference to RFC 3629. In document section "3 Primitive Types in Atom" inside the field "Literal Form" of the ""Primitive Type" **Edm.String** it reads:

any UTF-8 character 
Note: See definition of UTF8-char in **[RFC3629]** 

but this reference is missing in the references section, thus I propose to insert a refentry like:

[RFC3629]	F. Yergeau "UTF-8, a transformation format of ISO 10646", IETF RFC 3629, November 2003. http://www.ietf.org/rfc/rfc3629.txt

Benefit should be `consistency`.

##Feedback F)##

Missing reference to xxx. In document section "3 Primitive Types in Atom" inside the field "Literal Form" of the ""Primitive Type" **Edm.Time** it reads:

Defined by the lexical representation for time at `http://www.w3.org/TR/xmlschema-2`

and for **Edm.DateTimeOffset** it reads:

Defined by the lexical representation for datetime (including timezone offset) at `http://www.w3.org/TR/xmlschema-2`

I propose to replace the URL inside these two entries by a local reflabel along the lines of **[XML-XSD-P2]** linked to a new refentry created before as eg:

**[XML-XSD-P2]** P. V. Biron, A. Malhotra "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium, W3C Recommendation, 28 October 2004. http://www.w3.org/TR/xmlschema-2/

into the references section and rewrite the table entries in the referring section accordingly.

Benfit should be `consistency`.

#4.1.3 OData Data Namespace#

##Feedback G)##

The first paragraph reads 

Elements that describe the actual data values for an entity are qualified with the OData Data Namespace: "`http://schemas.microsoft.com/ado/2007/08/dataservices`";

This URL **SHOULD** be changed to the final oasis based namespacing URL starting with `http://docs.oasis-open.org/odata/ns/` and as noted in [Issue OData-19](https://tools.oasis-open.org/issues/browse/ODATA-19), when the resolution of OData-19 is settled.

Benefit is `consistency`.

#4.1.4 OData Metadata Namespace#

##Feedback G)##

The first paragraph reads 

Attributes and elements that represent metadata (such as type, null usage, and entry-level etags) are defined within the OData Metadata Namespace: "`http://schemas.microsoft.com/ado/2007/08/dataservices/metadata`";. Custom elements or attributes MUST NOT use this namespace.

This URL **SHOULD** be changed to the final oasis based namespacing URL starting with `http://docs.oasis-open.org/odata/ns/` and as noted in [Issue OData-19](https://tools.oasis-open.org/issues/browse/ODATA-19), when the resolution of OData-19 is settled.

Benefit is `consistency`.

#5.1 Entity Instances#

##Feedback H)##

Inside the example the two occurences of namespace-like links (in the values of the rel attribute of the link elements) **SHOULD** be updated in alignment with the resolution of [Issue OData-19](https://tools.oasis-open.org/issues/browse/ODATA-19).

Also the value of the attribute should IMO be guarded by quotes, i.e. instead of 

<link rel=http://schemas.microsoft.com/ado/2007/08/dataservices/related/Category type="

it **SHOULD** read (using the old namespace as sample):

<link rel=`"`http://schemas.microsoft.com/ado/2007/08/dataservices/related/Category`"` type="

All other occurences of namespaces **should** be changed accordingly.

Benefit is `consistency` and syntactic correctness of examples.


##Feedback I)##

The sample code is not valid standalone as is. 

IMO this is ok, as long as we have a place in the document instructing the reader, how to construct a validating piece of XML from it.

In the case of this sample, the reader has to amend the element `<entry>` as `<entry xmlns:data="foo" xmlns:metadata="bar">` and (fix an error described in **Feedback J**).

Benefit is a `useful compromise between readability and usability`

##Feedback J)##
The sample code contains (I presume for historical reasons) the term `<data:ID m:type="Edm.Int32">` which **SHOULD** be corrected with regard to the correct namespace prefix `metadata` i.e. `<data:ID metadata:type="Edm.Int32">`.

Benefit is `consistency` and syntactic correctness of examples.

#5.1.1.1 The metadata:etag Attribute#

##Feedback K)##

The last sentence of the only paragraph in this subsection reads 

For details on how `ETags` are used, see to [OData-Core].

Which is the usual CamelCase notation of synthetic words and is perfectly consistent with the RFC 2616 where it says in section 

"14.19 ETag

The ETag response-header field provides the current value of the entity tag for the requested variant.[...]"

In other places of the OData-Atom document like eg. "4.1.4 OData Metadata Namespace" 1st para 1st sentence it says:

"Attributes and elements that represent metadata (such as type, null usage, and entry-level `etags`) [...]


I hereby propose to consistently write the terms either as syntethic term in the form `ETag` or as native language term `entity-tag` (or the like, I am not a hyphenation expert neither in German nor in English ;-).

Benefit is `consistency`.

#5.1.4.1 The rel attribute of a Link Representing a Stream Property#

##Feedback L)##

Please consider **rewriting** the first two paragraphs to emphasize the distinguishing element (`read`versus `write`) instead of provoking the appearance of a doubled text.

So instead of the current:

`The rel attribute for an atom:link element that can be used to retrieve a stream property is made up of the name of the OData Data Namespace, followed by the string "/mediaresource/", followed by the name of the stream property on the entity.` 

`The rel attribute for an atom:link element that can be used to write a stream property is made up of the name of the OData Data Namespace, followed by the string "/edit-media/", followed by the name of the stream property on the entity.`


please consider **writing instead** something like:

`To enable retrieval of a stream property, the rel attribute for an atom:link element is made up of the name of the OData Data Namespace, followed by the string "/mediaresource/", followed by the name of the stream property on the entity.` 

`To enable writing [to] a stream property, the rel attribute for an atom:link element is made up of the name of the OData Data Namespace, followed by the string "/edit-media/", followed by the name of the stream property on the entity.`

Note: I assume the usual shorthand that the `attribute` means the `value of the attribute` is ok, but I am not sure, if it is meant to write `a stream`or `to a stream`.

Also _optionally_ ensure in subsequent "final revisions" that the third paragraph mandating the use of absolute URLs as values of the rel-attribute of the atom:link elements is `not on a separate page`, since distributing such a small paragraph on two pages weakens readability.

Benefits are `clearness`and `readability`.

#Misc. Places#
##Feedback M)##

The wording of the relation between attributes (or their values) and the respective elements in describing paragraphs is varying as (`on`|`of`|`for`). I know that kind of prose is always tedious writing (and reading) but maybe we **should** try bo be consistent with the selection of this (relating) word.

Benefit is `consistency` (and not to vary just to vary).

#End of session#

> Feedback to document revision
> -----------------------------
>
>                 Key: ODATA-20
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-20
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData ATOM Format v1.0
>    Affects Versions: WD01
>            Reporter: Stefan Drees
>             Fix For: WD01
>
>
> Several feedback items have been identified. These are listed in the comment as one document since they are partially related and  to not flood the editor with at least 13 isolated issues.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

        


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]