[OASIS Issue Tracker] Issue Comment Edited: (ODATA-7) Minor editorial changes to contribution during import into OASIS template

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

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

Stefan Drees edited comment on ODATA-7 at 8/8/12 2:13 PM:
----------------------------------------------------------

Very interesting read and I second the submitters proposal to accept this draft (including the changes) as baseline.
My comment has two parts. Both do not seem to justify the noise of an extra ticket. The first is not related to the extension document but to the core itself. The second might be to unimportant. If it is the explicit will of other tc members, that these should be transformed into single tickets, I will love to do so. 

SHOULD:
1. I  suggest, that the OData protocol version we will describe in the Standard v1 should indeed become 4.0. 
Reasoning:
a. This leaves room for substantial changes we might have to commit along the way, 
b. eases the lengthy standardization process for the tc members (especially in the later phases) and it last not least 
c. helps implementers (client and server) of the existing OData protocol 3.0 as published on odata.org in the case of efficient changes in our "redressed core version". 

MAYBE:
2. At the first occurence of the token "__metadata" (inside "3.1 Representing an Entity") it might be explicitely stated, that these are two leading underscores since this is buried inside the "ligature" even in the fixed space font used. And _metadata should be a perfectly legal name in a property's name/value pair, shouldn't it? Probably the section "3.1.1 Entity Metadata" is a better place for clarifying this.
Reasoning:
a. Readability and clarity.


      was (Author: sdrees):
    Very interesting read and I second the submitters proposal to accept this draft (including the changes) as baseline.

SHOULD:
1. I  suggest, that the OData protocol version we will describe in the Standard v1 should indeed become 4.0. 
Reasoning:
a. This leaves room for substantial changes we might have to commit along the way, 
b. eases the lengthy standardization process for the tc members (especially in the later phases) and it last not least 
c. helps implementers (client and server) of the existing OData protocol 3.0 as published on odata.org in the case of efficient changes in our "redressed core version". 

MAYBE:
2. At the first occurence of the token "__metadata" (inside "3.1 Representing an Entity") it might be explicitely stated, that these are two leading underscores since this is buried inside the "ligature" even in the fixed space font used. And _metadata should be a perfectly legal name in a property's name/value pair, shouldn't it? Probably the section "3.1.1 Entity Metadata" is a better place for clarifying this.
Reasoning:
a. Readability and clarity.

  
> Minor editorial changes to contribution during import into OASIS template
> -------------------------------------------------------------------------
>
>                 Key: ODATA-7
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-7
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData JSON Format v1.0
>    Affects Versions: WD01
>            Reporter: Ralf Handl
>            Assignee: Ralf Handl
>            Priority: Trivial
>             Fix For: WD01
>
>
> I've imported the part "OData JSON Verbose Format" of the "OData Version 3.0 Contribution" (https://www.oasis-open.org/apps/org/workgroup/odata/download.php/46557/ODataV3Core.zip) into the OASIS template. 
> The resulting document is "OData JSON Format Version 1.0 Working Draft 01", Kavi document revision 0 (https://www.oasis-open.org/apps/org/workgroup/odata/download.php/46641/odata-json-format-v1.0-wd01-2012-08-08-RHA.doc).
> During the import I did the following minor changes:
>  - Corrected a few obvious typos, high-lighted these changes in yellow, and added a paragraph starting with CHANGE: after the changed paragraph. 
>  - Inserted a few PROPOSAL: paragraphs (high-lighted in yellow)
>  - Inserted a few ISSUE: paragraphs (high-lighted in yellow), with links to the corresponding JIRA issues in two cases
>  - Harmonized capitalization of the OData terms "property" and "link": the majority of occurrences of these words and all occurrences of other OData terms like "entity" were in lower case, so I consistently lower-cased "property" and "link" without especially marking it

-- 
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