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

Allow client to use OData-SchemaVersion header to indicate the metadata version it is using

    XMLWordPrintable

    Details

    • Type: New Feature
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: V4.01_WD01
    • Fix Version/s: V4.01_WD01
    • Component/s: Protocol
    • Labels:
      None
    • Proposal:
      Hide

      Moving accepted proposal from comments. Note that (as per ODATA-937 we dropped the OData- prefix):
      1) Services MUST NOT make breaking changes to $metadata responses requested without an SchemaVersion header
      2) Services MUST interpret requests (and return payloads) made without an SchemaVersion according with this unbroken $metadata
      2) Clients that retrieve $metadata containing the SchemaVersion annotation SHOULD include the SchemaVersion header in all requests for data, and MAY include SchemaVersion in requests for $metadata
      3) The value of the SchemaVersion header, if specified, MUST be a value returned in the SchemaVersion annotation in a previous request to $metadata, or the special value "Latest" to interpret the request for data or metadata according to the latest schema.
      4) If the SchemaVersion header is present in a request for data, services must interpret requests and return responses compatible that version of metadata.
      5) If the SchemaVersion header is present in a request for $metadata, services must return metadata compatible with (i.e., with no breaking changes from) the specified version.
      6) If the specified version is invalid, the service should return a 400 error.

      Client can set an OData-SchemaVersion header in requests.

      Server may (these are example possibilities, possibilities, not requirements) use this information in a number of ways:

      (1) Refuse requests from the client if the server's metadata version is now incompatible with the version the client has indicated it is using.

      (2) Include extra metadata in responses, e.g. "@odata.type" for properties which weren't in the client's versin of the metadata, but now exist in the server's version (e.g. this allows the client to correctly treat those properties as dynamic, while knowing their proper type).

      Show
      Moving accepted proposal from comments. Note that (as per ODATA-937 we dropped the OData- prefix): 1) Services MUST NOT make breaking changes to $metadata responses requested without an SchemaVersion header 2) Services MUST interpret requests (and return payloads) made without an SchemaVersion according with this unbroken $metadata 2) Clients that retrieve $metadata containing the SchemaVersion annotation SHOULD include the SchemaVersion header in all requests for data, and MAY include SchemaVersion in requests for $metadata 3) The value of the SchemaVersion header, if specified, MUST be a value returned in the SchemaVersion annotation in a previous request to $metadata, or the special value "Latest" to interpret the request for data or metadata according to the latest schema. 4) If the SchemaVersion header is present in a request for data, services must interpret requests and return responses compatible that version of metadata. 5) If the SchemaVersion header is present in a request for $metadata, services must return metadata compatible with (i.e., with no breaking changes from) the specified version. 6) If the specified version is invalid, the service should return a 400 error. Client can set an OData-SchemaVersion header in requests. Server may (these are example possibilities, possibilities, not requirements) use this information in a number of ways: (1) Refuse requests from the client if the server's metadata version is now incompatible with the version the client has indicated it is using. (2) Include extra metadata in responses, e.g. "@odata.type" for properties which weren't in the client's versin of the metadata, but now exist in the server's version (e.g. this allows the client to correctly treat those properties as dynamic, while knowing their proper type).
    • Resolution:
      Show
      https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59028/odata-v4.01-wd01-part1-protocol.docx https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59031/odata-csdl-xml-v4.01-wd01.docx https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59030/odata-json-format-v4.01-wd01.docx https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/4.01%20spec/ABNF/odata-abnf-construction-rules.txt https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/4.01%20spec/vocabularies/Org.OData.Core.V1.xml

      Description

      Once we define a standard annotation term to allow the metadata author to define a schema version, it would be extremely useful for clients to be able to indicate to the server which version of the metadata document the client is working with (since no matter when the client received the metadata, it may since have changed at the server).

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              evan.ireland.2 Evan Ireland
            • Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: