Clarify creation choreography for media entities, recommend stream properties

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

      Proposed

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

      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.

            Assignee:
            Unassigned
            Reporter:
            handl
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: