[OASIS Issue Tracker] (ODATA-928) Allow client to use OData-SchemaVersion header to indicate the metadata version it is using

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ https://issues.oasis-open.org/browse/ODATA-928?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=62460#comment-62460 ] 

Michael Pizzo commented on ODATA-928:
-------------------------------------

For 4.0 compatibility, services would have to returning a backward-compatible $metadata and, in the absence of an OData-SchemaVersion or OData-MaxVersion header of 4.01 or greater, would have to interpret requests and return responses according to that $metadata.

As long as the clients specify the OData-SchemaVersion header for any service that returns the new annotation in $metadata (see OData-925), and services interpret requests and return responses compliant with that schema version, services could introduce breaking changes.  But that puts additional requirements on 4.01 clients to read the additional information from $metadata and add the header to each request.  Better (and perhaps simpler for the service) might be to only allow returning incompatible $metadata if the client specifies a special OData-SchemaVersion value; i.e., "Latest".

Draft proposal:
1) Services MUST NOT make breaking changes to $metadata responses requested without an OData-SchemaVersion header
2) Services MUST interpret requests (and return payloads) made without an OData-SchemaVersion according with this unbroken $metadata
2) Clients that retrieve $metadata containing the SchemaVersion annotation SHOULD include the OData-SchemaVersion header in all requests for data, and MAY include OData-SchemaVersion in requests for $metadata
3) The value of the OData-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 OData-SchemaVersion header is present in a request for data, services must interpret requests and return responses compatible that version of metadata.  
5) If the OData-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.

> Allow client to use OData-SchemaVersion header to indicate the metadata version it is using
> -------------------------------------------------------------------------------------------
>
>                 Key: ODATA-928
>                 URL: https://issues.oasis-open.org/browse/ODATA-928
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: New Feature
>          Components: OData Protocol
>    Affects Versions: V4.01_WD01
>            Reporter: Evan Ireland
>            Priority: Minor
>             Fix For: V4.01_WD01
>
>
> 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).



--
This message was sent by Atlassian JIRA
(v6.2.2#6258)