Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-178

Enhance abstract, distinguish its content from 1st paragraph of introduction and edit the payload object listing in 2nd para of 1 Introduction

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Trivial
    • Resolution: Fixed
    • Affects Version/s: V4.0_WD01
    • Fix Version/s: V4.0_WD01
    • Component/s: ATOM Format
    • Labels:
      None
    • Proposal:
      Hide

      Please consider changing the abstract to something like (with no additional formatting):
      """
      The OData protocol is comprised of a set of specifications for representing and interacting with structured content. A server offering an OData Service communicates with clients using that protocol and may offer respones to requests in several formats. This document describes the OData Atom Format, which is one of these possible formats. If the mime type application/atom+xml has been requested by the client, the response of any conforming server must follow the nromative rules declared in this document.
      """

      also maybe we should motivate the special ordering we had in mind for the 15 items long listing of what an OData payload might represent.

      I do not know enough about the OData model (hopefully yet to classify the special terms: single, sequence, collection or set, in the context of the listing.
      Does the imagined reader do so at this point? Could we for instance move / merge the items

      • a single link to a related entity
      • a collection of links to related entities
        also as
      • a link to a related entity
        into the first grouping below? Or is collection special, and must be preserved (but then, are collections of primitve values not possible)?

      One possible rewrite (sorry for my non-native english) for the listing in the introduction could be:
      """
      An OData payload may for instance represent single occurences or sequences of:

      • a primitive value
      • a structured ("complex") value
      • an entity (a structured type with an identity)

      Listed without any specific ordering, other objects represented by the payload may be:

      • a media resource
      • a single instance of a mime type
      • a single link to a related entity
      • a collection of links to related entities
      • a service document describing the collections (entity sets) exposed by the service an xml document describing the entity model exposed by the service
      • an error indication

      In the context of batch requests the payload may also indicate:

      • a batch of requests to be executed in a single request
      • a set of responses returned from a batch request
        """

      What do you think? If this listing is exhaustive we should state that and if is not we should also state this, shouldn't we?

      Accepted: https://www.oasis-open.org/committees/download.php/48346/odata-meeting-26_on-20130221-minutes.html#odata-178

      Show
      Please consider changing the abstract to something like (with no additional formatting): """ The OData protocol is comprised of a set of specifications for representing and interacting with structured content. A server offering an OData Service communicates with clients using that protocol and may offer respones to requests in several formats. This document describes the OData Atom Format, which is one of these possible formats. If the mime type application/atom+xml has been requested by the client, the response of any conforming server must follow the nromative rules declared in this document. """ also maybe we should motivate the special ordering we had in mind for the 15 items long listing of what an OData payload might represent. I do not know enough about the OData model (hopefully yet to classify the special terms: single, sequence, collection or set, in the context of the listing. Does the imagined reader do so at this point? Could we for instance move / merge the items a single link to a related entity a collection of links to related entities also as a link to a related entity into the first grouping below? Or is collection special, and must be preserved (but then, are collections of primitve values not possible)? One possible rewrite (sorry for my non-native english) for the listing in the introduction could be: """ An OData payload may for instance represent single occurences or sequences of: a primitive value a structured ("complex") value an entity (a structured type with an identity) Listed without any specific ordering, other objects represented by the payload may be: a media resource a single instance of a mime type a single link to a related entity a collection of links to related entities a service document describing the collections (entity sets) exposed by the service an xml document describing the entity model exposed by the service an error indication In the context of batch requests the payload may also indicate: a batch of requests to be executed in a single request a set of responses returned from a batch request """ What do you think? If this listing is exhaustive we should state that and if is not we should also state this, shouldn't we? Accepted: https://www.oasis-open.org/committees/download.php/48346/odata-meeting-26_on-20130221-minutes.html#odata-178
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/48383/odata-atom-format-v4.0-wd01-2013-02-26-RH.doc Accepted: https://www.oasis-open.org/committees/download.php/48549/odata-meeting-29_on-20130314-minutes.html#odata-178

      Description

      In the current reviion of the workproduct [odata-atom-format-v1.0-wd01-2012-11-27.doc](https://www.oasis-open.org/committees/download.php/47557/odata-atom-format-v1.0-wd01-2012-11-27.doc) the abstract reads:

      """
      The OData protocol is comprised of a set of specifications for representing and interacting with structured content. This document describes the OData Atom Format returned from an OData Service when requesting the application/atom+xml mime type.
      """
      with the terms 'application/atom+xml' formated in a different way (presumably to show this is a special token). The introduction (section 1 on page 6 of 37 in PDF-A4-Output) starts with (identical text):
      """
      The OData protocol is comprised of a set of specifications for representing and interacting with structured content. This document describes the OData Atom Format returned from an OData Service when requesting the application/atom+xml mime type.
      """

      I think we should avoid this. An abstract condenses the content of the document regardless of reader knowledge or presentation sequence. It has a passive function saying: "this is what i am". The reader is active and may decide to continue or not.

      The introduction is reader oriented and adapts for the presentation sequence in the remaining document. It tells what the author expects as prerequisites from the reader, may offer a guiding line and in summary helps the imagined reader to a good start into the subject i.e. here the rest of the document.

      Also I discourage usage of special formating in abstracts, (as with the mime type token in this case).

        Attachments

          Activity

            People

            • Assignee:
              handl Ralf Handl
              Reporter:
              sdrees Stefan Drees (Inactive)
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: