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

Clarify need for @odata.id in nested response structures

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_CS02
    • Fix Version/s: V4.01_CS02
    • Labels:
      None
    • Environment:

      Applied to JSON Format V4.01

    • Proposal:
      Hide

      Examples in the document should comply with the rules stated in the JSON format specification. Since the current examples throughout the document that return transient aggregated entities based on 4.0, all examples having responses with nested projections of related entities should have included an "@odata.id":null annotation.

       

      Proposal is to make a blanket statement for V4.01 that clients must be prepared to receive entities having neither @odata.id nor key fields and, in the absence of any additional information, must treat such entities as transient.

      We will update the examples in the aggregation specification to be 4.01 and thus all @odata.id:null (as well as other 4.01 simplifications).

      Mention in Aggregation that all examples are based on OData V4.01, and call out what would be different across examples for V4.0.

      Show
      Examples in the document should comply with the rules stated in the JSON format specification. Since the current examples throughout the document that return transient aggregated entities based on 4.0, all examples having responses with nested projections of related entities should have included an "@odata.id":null annotation.   Proposal is to make a blanket statement for V4.01 that clients must be prepared to receive entities having neither @odata.id nor key fields and, in the absence of any additional information, must treat such entities as transient. We will update the examples in the aggregation specification to be 4.01 and thus all @odata.id:null (as well as other 4.01 simplifications). Mention in Aggregation that all examples are based on OData V4.01, and call out what would be different across examples for V4.0.
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/64648/odata-json-format-v4.01-wd06-2019-02-01.docx

      Description

      This issue is to clarify, if nested entities included in the response to an aggregation request need to be equipped with an @odata.id control information.

      Consider example 24 from the Data Aggregation specification:

      GET ~/Sales?$apply=groupby((Customer/Country,Product/Name),aggregate(Amount with sum as Total))

      results in

      {
        "@odata.context": "$metadata#Sales(Customer(Country),Product(Name),Total)",
        "value": [
          { "@odata.id": null,
            "Customer": { "Country" : "Netherlands" },
            "Product": { "Name": "Paper" },
            "Total": 3 },
         [...]
       
      

      Top-level entities do have an @odata.id, but nested projections of related entities currently not. Is this according to rules defined in the format specs to be considered as a gap that needs to be discussed for the Data Aggregation spec?

      The JSON specification describes in section 8.3 for expanded navigation properties that the content is to be rendered according to the entity representation. Two cases exist: 1) If the nested entity is a projection of a "real" entity, this could imply mentioning its @odata.id in the response. 2) If the nested entity is a result of an aggregation and therefore transient, section 4.5.8 of the JSON spec states: "If the entity is transient (i.e. cannot be read or updated), the id annotation MUST appear and have the null value."

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              gerald.krause1 Gerald Krause
            • Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: