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

Clarify creation choreography for media entities, recommend stream properties

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_CS01
    • Fix Version/s: V4.01_CS02
    • Component/s: CSDL JSON, CSDL XML, Protocol
    • Labels:
      None
    • Environment:

      Proposed

    • Proposal:
      Hide

      Add

      • as a second paragraph to Protocol, section 11.2.3 Requesting the Media Stream of a Media Entity using $value, and
      • after the second sentence to first paragraph of CSDL JSON/XML, section 6.4 Media Entity Type

      the following guidance

      Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just structured additional information attached to the stream. Use a normal entity with one or more stream properties if the structured data of the entity is the main topic of interest and the stream data is just additional non-structured information attached to the structured data.

      Add green text to first paragraph of Protocol, section 11.4.7.1 Create a Media Entity

      A POST request to a media entity's entity set creates a new media entity. The request body MUST contain the media value (for example, the photograph) whose media type MUST be specified in a Content-Type header. The request body is always interpreted as the media value, even if it has the media type of an OData format supported by the service, such as application/json. It is not possible to set the structural properties of the media entity when creating the media entity.

      Show
      Add as a second paragraph to Protocol, section 11.2.3 Requesting the Media Stream of a Media Entity using $value, and after the second sentence to first paragraph of CSDL JSON/XML, section 6.4 Media Entity Type the following guidance Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just structured additional information attached to the stream. Use a normal entity with one or more stream properties if the structured data of the entity is the main topic of interest and the stream data is just additional non-structured information attached to the structured data. Add green text to first paragraph of Protocol, section 11.4.7.1 Create a Media Entity A POST request to a media entity's entity set creates a new media entity. The request body MUST contain the media value (for example, the photograph) whose media type MUST be specified in a Content-Type header. The request body is always interpreted as the media value, even if it has the media type of an OData format supported by the service, such as application/json . It is not possible to set the structural properties of the media entity when creating the media entity.
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/65433/odata-v4.01-wd06-part1-protocol-2019-06-07.docx https://www.oasis-open.org/committees/download.php/65434/odata-csdl-json-v4.01-wd05-2019-06-07.docx https://www.oasis-open.org/committees/download.php/65435/odata-csdl-xml-v4.01-wd06-2019-06-07.docx  

      Description

      Media entities are a somewhat obscure heirloom from AtomPub, and the "atomic pair" nature of a media resource and its media entity is not clearly explained and not very intuitive.

      For example implementations differ in how they treat the content-type:application/json  in POST requests to a media entity set:

      • some implementations create a media entity using the POST body and do not create a media resource
      • some implementations create a JSON media resource using the POST body, plus a media entity pointing to that JSON media resource

      We should give guidance on when to use media entities and when to use "normal" entities with stream properties.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              handl Ralf Handl
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: