[ODATA-980] SchemaVersion header, $SchemaVersion query option, or root URL versioning - OASIS Technical Committees Issue Tracker

XML

Word

Printable

Proposal:

Hide

Proposal: for CSD01, clarify how the type is annotated, as below, leaving the rest of the semantics as in the current draft. Annotations are a nice way for the client to know what schema version was used without having to parse a URL and get the query option. For CSD02, consider replacing the SchemaVersion request header with a query option.

Show
Proposal: for CSD01, clarify how the type is annotated, as below, leaving the rest of the semantics as in the current draft. Annotations are a nice way for the client to know what schema version was used without having to parse a URL and get the query option. For CSD02, consider replacing the SchemaVersion request header with a query option.

The SchemaVersion header and accompanying annotation are intended to allow breaking changes without having to change the service root URL.

How does this combine with type referencing in the @odata.type annotation?

We could annotate the @odata.type annotation with the @Core.SchemaVersion:

"@odata.type":"https://some.whe.re/$metadata"
"@odata.type@Core.SchemaVersion":"2.0.1",

Or we could add a system query option and make the schema version part of the URL:

"@odata.type":"https://some.whe.re/$metadata?$SchemaVersion=2.0.1",

Or we could reconsider this and fall back to root URL versioning:

"@odata.type":"https://some.whe.re;v=2.0.1/$metadata",