{"action":"created","comment":{"url":"https://api.github.com/repos/OData/vocabularies/pulls/comments/28019385","id":28019385,"diff_hunk":"@@ -0,0 +1,448 @@\n+﻿#Service Versioning for OData Services \r\n+\r\n+##A mechanism for OData services with dynamic or evolving data models to communicate the current version of their data models to clients, and for clients to communicate data model version requirements to the service.\r\n+\r\n+##1\tIntroduction\r\n+\r\n+###1.1\tSummary\r\n+This document details a proposal for an OData v4 vocabulary and a convention for header and query string usage to support communication of service version capabilities and requirements between services and their clients.\r\n+\r\n+###1.2\tBackground\r\n+The current protocol spec for OData v4 discusses data model versioning and recommends that: \r\n+\r\n+>“Breaking changes, such as removing properties or changing the type of existing properties, require that a new service version is provided at a different service root URL for the new model.”\r\n+\r\n+Some services, however, prefer to maintain stable addresses to their resources or prefer to maintain a stable service root address.   In addition, other services may be extensible and therefore expose what can be considered “dynamic” data models that depend on the current state of 3rd party or customer extensions currently hosted in the service instance.\r\n+\r\n+For these services, various strategies are used today to allow the data model at the service root address to evolve over time in ways that would be considered breaking changes.  One common pattern is to have clients provide a “version” as a string value in a header or in a query string parameter.\r\n+\r\n+This document attempts to formalize that pattern in a way that clients can discover, understand, and implement successfully.\r\n+\r\n+###1.3\tFurther Reading\r\n+OData v4 specifications:  http://www.odata.org/documentation/\r\n+ \r\n+##2\tService Versioning\r\n+###2.1\tClient requests service metadata \r\n+When metadata-aware clients first retrieve metadata from a service to discover its data model (often for the purpose of generating proxy classes to simplify interaction with the service), the service can include in its response an annotation on the EntityContainer that describes the version information associated with the provided metadata.  This annotation also provides instructions to the client on how the version dependency that the client has established should be communicated to the service.\r\n+\r\n+####2.1.1\tServiceVersionInfo Annotation\r\n+The service may return a “ServiceVersionInfo” annotation on the EntityContainer containing a complex type named VersionInfo with the following structure:\r\n+\r\n+|Property\t|Type\t|Description\r\n+|--------   |----   |-----------\r\n+|CurrentVersion\t|Edm.String\t|The version of the service associated with the returned metadata.  Required.\r\n+|Required\t|Edm.Boolean\t|Indicates whether the service requires that this version be included in client requests.  If true, either VersionHeaderName or VersionQueryStringParameterName should be provided.  Optional.  Defaults to false.\r\n+|VersionHeaderName\t|Edm.String\t|The name of the header clients can use to communicate version information.  Optional.  Nullable.  Services should provide either a header name or a query string parameter name if clients are expected to provide version information in requests.\r\n+|VersionQueryStringParameterName\t|Edm.String\t|The name of the query string parameter clients can use to communicate version information.  Optional.  Nullable.  Services should provide either a header name or a query string parameter name if clients are expected to provide version information in requests.\r\n+\r\n+####2.1.2\tExample: Simple, Optional Service Version\r\n+The following annotation in a $metadata response would indicate that the metadata returned represents service version 7.2, that the service supports communicating the required service version via a query string parameter named “api-version”, and that this parameter is optional:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"Org.OData.ServiceVersioning.V1.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"CurrentVersion\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+####2.1.3\tExample: Simple, Required Service Version\r\n+The following annotation in a $metadata response would indicate that the metadata returned represents service version 7.2, that the service supports communicating the required service version via a header named “api-version”, and that this header is required:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"Org.OData.ServiceVersioning.V1.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"Version\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"Required\" Bool=\"true\" />\r\n+      <PropertyValue Property=\"VersionHeaderName\" String=\"Accept-Version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+###2.2\tClient calls a service with version information\r\n+After a client has received the service version information from the service, it should configure itself to transmit the appropriate version information to the service in each call.\r\n+\r\n+####2.2.1\tVersion transmission logic\r\n+When service version information is provided at code generation time, client frameworks should default to sending that service version information with each request.\r\n+\r\n+When scope version information is provided, and indicated as required, client frameworks should default to sending version information for those scopes with each request.\r\n+\r\n+Developers should be provided the ability to override the default setting and control the transmission of version information for the service and for individual scopes.\r\n+\r\n+If a service supports both header-based and query-based versioning, the client frameworks should default to passing version information over query strings, but allow developers to override this setting and chose the method of transmission they prefer.  Client frameworks should not transmit version information using both header and query strings.\r\n+\r\n+####2.2.2\tVersion Information Format\r\n+When transmitting version information to the service, the string value of the requested header or query string parameter should be the exact string provided by the service in the ServiceVersionInfo annotation’s CurrentVersion property.  \r\n+\r\n+####2.2.3\tHeader Version Format\r\n+When providing version information in a header, services must provide a Header Name that meets the http requirements for header names.  The client should include in requests a header with the requested header name with a value of the version information format above.\r\n+\r\n+For example, given the version information in the previous example and a requested version header name of “api-version”:\r\n+\r\n+```http\r\n+api-version: 7.2\r\n+```\r\n+\r\n+When version information is allowed to be passed in headers, services must provide version string values that meet the HTTP requirements for header values.\r\n+\r\n+####2.2.4\tQuery String Parameter Version Format\r\n+When providing version information in a query string parameter, services must provide Query String Parameter Names that meets the http requirements for query string parameter names.  The client should include in requests a query string parameters with the requested name with a value of the version format above.\r\n+\r\n+When version information is allowed to be passed in query string parameters, version strings will be encoded as any other query string value.\r\n+\r\n+For example, given the version information in the previous example and a requested query string parameter name of “api-version”:\r\n+\r\n+```http\r\n+http://service/root/entity(123)?api-version=7.2\r\n+```\r\n+\r\n+####2.2.5\tExample: Client calls a service with service version information in Header\r\n+Given the following service version annotations in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"Org.OData.ServiceVersioning.V1.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"Version\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"Required\" Bool=\"true\" />\r\n+      <PropertyValue Property=\"VersionHeaderName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the api-version header as follows:\r\n+\r\n+```http\r\n+GET /service/Customers HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+api-version: 7.2\r\n+```\r\n+\r\n+####2.2.6\tExample: Client calls a service with service version information in Query String\r\n+Given the following service version annotations in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"Org.OData.ServiceVersioning.V1.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"CurrentVersion\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the api-version query string parameter as follows:\r\n+\r\n+```http\r\n+GET /service/Customers?api-version=7.2  HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+```\r\n+\r\n+###2.3\tService Responses\r\n+When services communicate that their Version Information is required in requests, but a request is received without it, a service is expected to respond with an HTTP error status such as `400 Bad Request` with a message indicating that the version header or query string parameter is required.\r\n+\r\n+When a client requests a version of the service that the service understands but cannot respond compatibly with, the service is expected to respond with HTTP error status such as `501 Not Implemented` or `400 Bad Request`.  Error message text should also communicate that the requested version of the service is not available.\r\n+\r\n+When the client requests a version that the service is compatible with, the service is expected to return a version of results that includes only non-breaking changes from the metadata that would have been provided for the requested version of the service.\r\n+\r\n+##3\tScoped Service Versioning\r\n+Complex services may contain data models that are generated from multiple sub-systems or components.  For example, a service may allow the deployment of “extensions” to a service instance that add to the available data model or functionality.  Scoped service versioning is intended to support these advanced scenarios by allowing the communication of specific version information for each of these “scopes”.\r\n+\r\n+###3.1\tClient requests service metadata\r\n+When metadata-aware clients first retrieve metadata from a service to discover its data model (often for the purpose of generating proxy classes to simplify interaction with the service), the service can include in its response an annotation on the EntityContainer that describes the version information for a set of “scopes” associated with the provided metadata.  This annotation also provides instructions to the client on how a version dependency that the client has established to those scopes should be communicated to the service.\r\n+\r\n+####3.1.1\tScopedServiceVersionInfo Annotation\r\n+The service may return a “ScopedServiceVersionInfo” annotation on the EntityContainer containing a collection of the ScopedVersionInfo complex type (based in the above VersionInfo) which has the following additional property:\r\n+\r\n+|Property\t|Type\t|Description\r\n+|--------   |----   |-----------\r\n+|Scope\t|Edm.String\t|The scope to which this version information applies.  Each ScopedServiceVersionInfo annotation should provide a unique scope value.\r\n+\r\n+####3.1.2\tExample: Scope Version Information\r\n+The following annotation in a $metadata response would indicate that the metadata returned represents 2 named scopes, that the service supports communicating the required service version via a query string parameter named “solution-versions”, and that returning this version information is optional:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+####3.1.3\tExample: Service and Scope Version Information\r\n+The following annotation in a $metadata response would indicate that the metadata returned represents service version 7.2, and includes 2 named scopes, that the service supports communicating the required service version via query string parameter named “api-version”, and the optional scope version information via a query string parameter named \"solution-versions\":\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"CurrentVersion\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"Required\" Bool=\"true\" />\r\n+      <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+        \r\n+</EntityContainer>\r\n+```\r\n+\r\n+###3.2\tClient calls a service with scope version information\r\n+After a client has received the service version information from the service, it should configure itself to transmit the appropriate scope version information to the service in each call.\r\n+\r\n+####3.2.1\tVersion transmission logic\r\n+When scope version information is provided in metadata, client frameworks should default to sending version information for those scopes with each request.\r\n+\r\n+Developers should be provided the ability to override the default setting and control the transmission of version information for individual scopes so they can avoid unnecessary scope version dependencies.  Services should document how developers can map scopes to particular parts of the data model.\r\n+\r\n+If a service supports both header-based and query-based versioning, the client frameworks should default to passing version information over query strings, but allow developers to override this setting and chose the method of transmission they prefer.  Client frameworks should not transmit version information using both header and query strings.\r\n+\r\n+####3.2.2\tScope Version Information Format\r\n+When transmitting scope version information to the service, the string value for the requested header or query string parameter should be a comma separated list of scope version terms for each defined header or query string parameter.\r\n+\r\n+Each scope version term should me made up of the scope name, a forward-slash (“/”), and then the exact version string provided for that scope in the ScopedServiceVersionInfo annotation’s CurrentVersion property.  \r\n+\r\n+For example, given 2 scopes: solutionA with version 5.0 and solutionB with verion 3.0, the version information should be formatted as:\r\n+\r\n+```\r\n+solutionA/5.0,solutionB/3.0\r\n+```\r\n+\r\n+####3.2.3\tHeader Version Format\r\n+When providing version information in a header, services must provide a Header Name that meets the http requirements for header names.  The client should include in requests a header with the requested header name with a value of the version information format above.\r\n+\r\n+For example, given the scopes in the previous example with a requested scope version header name of “solution-versions”, the header should be crafted as:\r\n+\r\n+```\r\n+solution-versions: solutionA/5.0,solutionB/3.0\r\n+```\r\n+\r\n+When version information is allowed to be passed in headers, services must provide version string values that meet the HTTP requirements for header values.\r\n+\r\n+####3.2.4\tQuery String Parameter Version Format\r\n+When providing version information in a query string parameter, services must provide Query String Parameter Names that meets the http requirements for query string parameter names.  The client should include in requests a query string parameters with the requested name with a value of the version or scope version information format above.\r\n+\r\n+When version information is allowed to be passed in query string parameters, version strings will be encoded as any other query string value.\r\n+\r\n+For example, given the version information in the previous example and a requested query string parameter name of “solution-versions”:\r\n+\r\n+Scope versions: \r\n+\r\n+```http\r\n+http://service/root/entity(123)?solution-versions=solutionA%2F5.0%2CsolutionB%2F3.0\r\n+```\r\n+\r\n+Services must not include comma (“,”) or forward slash “/” characters in their scope version strings.\r\n+\r\n+####3.2.5\tProviding Service Version and Scope Version together\r\n+If a service requests that a service version and scope versions be provided using the same header or query string parameter, clients should provide them in the same comma-separated list, but with the service version listed first, having no scope, and no forward slash.  For example:\r\n+\r\n+```\r\n+7.2,solutionA/5.0,solutionB/3.0\r\n+```\r\n+\r\n+When provided in a common header this would take the form:\r\n+\r\n+```\r\n+api-version: 7.2,solutionA/5.0,solutionB/3.0\r\n+```\r\n+\r\n+When provided in a query string:\r\n+\r\n+```http\r\n+http://service/root/entity(123)?api-version= 7.2%2CsolutionA%2F5.0%2CsolutionB%2F3.0\r\n+```\r\n+\r\n+####3.2.6\tExample: Client calls a service with scope version information only in a header\r\n+Given the following version information in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionHeaderName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\" VersionHeaderName \" String=\"solution-versions\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the solution-versions header as follows:\r\n+\r\n+```http\r\n+GET /service/Customers HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+solution-versions: isvsolution1/5.0,isvsolution2/3.1\r\n+```\r\n+\r\n+####3.2.7\tExample: Client calls a service with scope version information only in a query string parameter\r\n+Given the following version information in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the solution-versions query string parameter as follows:\r\n+\r\n+```http\r\n+GET /service/Customers?solution-versions=isvsolution1%2F5.0%2Cisvsolution2%2F3.1 HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+```\r\n+\r\n+####3.2.8\tExample: Client calls a service with service and scope version information\r\n+Given the following version information in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"CurrentVersion\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"Required\" Bool=\"true\" />\r\n+      <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"solution-versions\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+        \r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the solution-versions query string parameter as follows:\r\n+\r\n+```http\r\n+GET /service/Customers?api-version=7.2&solution-versions=isvsolution1%2F5.0%2Cisvsolution2%2F3.1 HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+```\r\n+\r\n+####3.2.9\tExample: Client calls a service with service and scope version in shared query string parameter\r\n+Given the following version information in metadata:\r\n+\r\n+```xml\r\n+<EntityContainer Name=\"DefaultContainer\">\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ServiceVersionInfo\">\r\n+    <Record>\r\n+      <PropertyValue Property=\"CurrentVersion\" String=\"7.2\" />\r\n+      <PropertyValue Property=\"Required\" Bool=\"true\" />\r\n+      <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+    </Record>\r\n+  </Annotation>\r\n+\r\n+  <Annotation Term=\"ServiceVersioning.ScopedServiceVersionInfo\">\r\n+    <Collection>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution1\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"5.0\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+      </Record>\r\n+      <Record>\r\n+        <PropertyValue Property=\"Scope\" String=\"isvsolution2\" />\r\n+        <PropertyValue Property=\"CurrentVersion\" String=\"3.1\" />\r\n+        <PropertyValue Property=\"VersionQueryStringParameterName\" String=\"api-version\" />\r\n+      </Record>\r\n+    </Collection>\r\n+  </Annotation>\r\n+        \r\n+</EntityContainer>\r\n+```\r\n+\r\n+The client should add the solution-versions query string parameter as follows:\r\n+\r\n+```http\r\n+GET /service/Customers?api-version=7.2%2Cisvsolution1%2F5.0%2Cisvsolution2%2F3.1 HTTP/1.1\r\n+Host: odata.org\r\n+OData-Version: 4.0 \r\n+OData-MaxVersion: 4.0 \r\n+Content-Type: application/json\r\n+```\r\n+\r\n+###3.3\tService Responses\r","path":"OData.Community.ServiceVersioning.V1.md","position":443,"original_position":443,"commit_id":"5a52be8d290077a5a7e875f50c9d90fe46b2f45c","original_commit_id":"5a52be8d290077a5a7e875f50c9d90fe46b2f45c","user":{"login":"cbrooksmsft","id":9362227,"avatar_url":"https://avatars.githubusercontent.com/u/9362227?v=3","gravatar_id":"","url":"https://api.github.com/users/cbrooksmsft","html_url":"https://github.com/cbrooksmsft","followers_url":"https://api.github.com/users/cbrooksmsft/followers","following_url":"https://api.github.com/users/cbrooksmsft/following{/other_user}","gists_url":"https://api.github.com/users/cbrooksmsft/gists{/gist_id}","starred_url":"https://api.github.com/users/cbrooksmsft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cbrooksmsft/subscriptions","organizations_url":"https://api.github.com/users/cbrooksmsft/orgs","repos_url":"https://api.github.com/users/cbrooksmsft/repos","events_url":"https://api.github.com/users/cbrooksmsft/events{/privacy}","received_events_url":"https://api.github.com/users/cbrooksmsft/received_events","type":"User","site_admin":false},"body":"This behavior would depend on the \"Required\" property.  The default is not required, and the expectations would be as you describe.  \r\n\r\nBut for some services, having version resilient client calls is a requirement, and so the point of this vocabulary is to allow those services to communicate this requirement in a standard way.","created_at":"2015-04-08T22:14:08Z","updated_at":"2015-04-08T22:14:08Z","html_url":"https://github.com/OData/vocabularies/pull/7#discussion_r28019385","pull_request_url":"https://api.github.com/repos/OData/vocabularies/pulls/7","_links":{"self":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/comments/28019385"},"html":{"href":"https://github.com/OData/vocabularies/pull/7#discussion_r28019385"},"pull_request":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/7"}}},"pull_request":{"url":"https://api.github.com/repos/OData/vocabularies/pulls/7","id":32819663,"html_url":"https://github.com/OData/vocabularies/pull/7","diff_url":"https://github.com/OData/vocabularies/pull/7.diff","patch_url":"https://github.com/OData/vocabularies/pull/7.patch","issue_url":"https://api.github.com/repos/OData/vocabularies/issues/7","number":7,"state":"open","locked":false,"title":"Service Versioning vocabulary","user":{"login":"cbrooksmsft","id":9362227,"avatar_url":"https://avatars.githubusercontent.com/u/9362227?v=3","gravatar_id":"","url":"https://api.github.com/users/cbrooksmsft","html_url":"https://github.com/cbrooksmsft","followers_url":"https://api.github.com/users/cbrooksmsft/followers","following_url":"https://api.github.com/users/cbrooksmsft/following{/other_user}","gists_url":"https://api.github.com/users/cbrooksmsft/gists{/gist_id}","starred_url":"https://api.github.com/users/cbrooksmsft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cbrooksmsft/subscriptions","organizations_url":"https://api.github.com/users/cbrooksmsft/orgs","repos_url":"https://api.github.com/users/cbrooksmsft/repos","events_url":"https://api.github.com/users/cbrooksmsft/events{/privacy}","received_events_url":"https://api.github.com/users/cbrooksmsft/received_events","type":"User","site_admin":false},"body":"Initial files for ServiceVersioning vocabulary","created_at":"2015-04-08T00:45:19Z","updated_at":"2015-04-08T22:14:08Z","closed_at":null,"merged_at":null,"merge_commit_sha":"35a55050bdd89e08f64a0f6f373b379117cd9800","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/OData/vocabularies/pulls/7/commits","review_comments_url":"https://api.github.com/repos/OData/vocabularies/pulls/7/comments","review_comment_url":"https://api.github.com/repos/OData/vocabularies/pulls/comments{/number}","comments_url":"https://api.github.com/repos/OData/vocabularies/issues/7/comments","statuses_url":"https://api.github.com/repos/OData/vocabularies/statuses/5a52be8d290077a5a7e875f50c9d90fe46b2f45c","head":{"label":"cbrooksmsft:ServiceVersioning","ref":"ServiceVersioning","sha":"5a52be8d290077a5a7e875f50c9d90fe46b2f45c","user":{"login":"cbrooksmsft","id":9362227,"avatar_url":"https://avatars.githubusercontent.com/u/9362227?v=3","gravatar_id":"","url":"https://api.github.com/users/cbrooksmsft","html_url":"https://github.com/cbrooksmsft","followers_url":"https://api.github.com/users/cbrooksmsft/followers","following_url":"https://api.github.com/users/cbrooksmsft/following{/other_user}","gists_url":"https://api.github.com/users/cbrooksmsft/gists{/gist_id}","starred_url":"https://api.github.com/users/cbrooksmsft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cbrooksmsft/subscriptions","organizations_url":"https://api.github.com/users/cbrooksmsft/orgs","repos_url":"https://api.github.com/users/cbrooksmsft/repos","events_url":"https://api.github.com/users/cbrooksmsft/events{/privacy}","received_events_url":"https://api.github.com/users/cbrooksmsft/received_events","type":"User","site_admin":false},"repo":{"id":33572733,"name":"vocabularies","full_name":"cbrooksmsft/vocabularies","owner":{"login":"cbrooksmsft","id":9362227,"avatar_url":"https://avatars.githubusercontent.com/u/9362227?v=3","gravatar_id":"","url":"https://api.github.com/users/cbrooksmsft","html_url":"https://github.com/cbrooksmsft","followers_url":"https://api.github.com/users/cbrooksmsft/followers","following_url":"https://api.github.com/users/cbrooksmsft/following{/other_user}","gists_url":"https://api.github.com/users/cbrooksmsft/gists{/gist_id}","starred_url":"https://api.github.com/users/cbrooksmsft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cbrooksmsft/subscriptions","organizations_url":"https://api.github.com/users/cbrooksmsft/orgs","repos_url":"https://api.github.com/users/cbrooksmsft/repos","events_url":"https://api.github.com/users/cbrooksmsft/events{/privacy}","received_events_url":"https://api.github.com/users/cbrooksmsft/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/cbrooksmsft/vocabularies","description":"OData vocabulary definitions and usage","fork":true,"url":"https://api.github.com/repos/cbrooksmsft/vocabularies","forks_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/forks","keys_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/teams","hooks_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/hooks","issue_events_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/issues/events{/number}","events_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/events","assignees_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/assignees{/user}","branches_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/branches{/branch}","tags_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/tags","blobs_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/git/refs{/sha}","trees_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/statuses/{sha}","languages_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/languages","stargazers_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/stargazers","contributors_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/contributors","subscribers_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/subscribers","subscription_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/subscription","commits_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/commits{/sha}","git_commits_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/git/commits{/sha}","comments_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/comments{/number}","issue_comment_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/issues/comments{/number}","contents_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/contents/{+path}","compare_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/merges","archive_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/downloads","issues_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/issues{/number}","pulls_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/pulls{/number}","milestones_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/milestones{/number}","notifications_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/labels{/name}","releases_url":"https://api.github.com/repos/cbrooksmsft/vocabularies/releases{/id}","created_at":"2015-04-07T23:01:21Z","updated_at":"2015-03-27T17:00:39Z","pushed_at":"2015-04-08T21:45:29Z","git_url":"git://github.com/cbrooksmsft/vocabularies.git","ssh_url":"git@github.com:cbrooksmsft/vocabularies.git","clone_url":"https://github.com/cbrooksmsft/vocabularies.git","svn_url":"https://github.com/cbrooksmsft/vocabularies","homepage":null,"size":108,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"OData:master","ref":"master","sha":"639f05ba6a8d708ecfdc39207057cb8abe6c2bf6","user":{"login":"OData","id":916520,"avatar_url":"https://avatars.githubusercontent.com/u/916520?v=3","gravatar_id":"","url":"https://api.github.com/users/OData","html_url":"https://github.com/OData","followers_url":"https://api.github.com/users/OData/followers","following_url":"https://api.github.com/users/OData/following{/other_user}","gists_url":"https://api.github.com/users/OData/gists{/gist_id}","starred_url":"https://api.github.com/users/OData/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OData/subscriptions","organizations_url":"https://api.github.com/users/OData/orgs","repos_url":"https://api.github.com/users/OData/repos","events_url":"https://api.github.com/users/OData/events{/privacy}","received_events_url":"https://api.github.com/users/OData/received_events","type":"Organization","site_admin":false},"repo":{"id":9152516,"name":"vocabularies","full_name":"OData/vocabularies","owner":{"login":"OData","id":916520,"avatar_url":"https://avatars.githubusercontent.com/u/916520?v=3","gravatar_id":"","url":"https://api.github.com/users/OData","html_url":"https://github.com/OData","followers_url":"https://api.github.com/users/OData/followers","following_url":"https://api.github.com/users/OData/following{/other_user}","gists_url":"https://api.github.com/users/OData/gists{/gist_id}","starred_url":"https://api.github.com/users/OData/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OData/subscriptions","organizations_url":"https://api.github.com/users/OData/orgs","repos_url":"https://api.github.com/users/OData/repos","events_url":"https://api.github.com/users/OData/events{/privacy}","received_events_url":"https://api.github.com/users/OData/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/OData/vocabularies","description":"OData vocabulary definitions and usage","fork":false,"url":"https://api.github.com/repos/OData/vocabularies","forks_url":"https://api.github.com/repos/OData/vocabularies/forks","keys_url":"https://api.github.com/repos/OData/vocabularies/keys{/key_id}","collaborators_url":"https://api.github.com/repos/OData/vocabularies/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/OData/vocabularies/teams","hooks_url":"https://api.github.com/repos/OData/vocabularies/hooks","issue_events_url":"https://api.github.com/repos/OData/vocabularies/issues/events{/number}","events_url":"https://api.github.com/repos/OData/vocabularies/events","assignees_url":"https://api.github.com/repos/OData/vocabularies/assignees{/user}","branches_url":"https://api.github.com/repos/OData/vocabularies/branches{/branch}","tags_url":"https://api.github.com/repos/OData/vocabularies/tags","blobs_url":"https://api.github.com/repos/OData/vocabularies/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/OData/vocabularies/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/OData/vocabularies/git/refs{/sha}","trees_url":"https://api.github.com/repos/OData/vocabularies/git/trees{/sha}","statuses_url":"https://api.github.com/repos/OData/vocabularies/statuses/{sha}","languages_url":"https://api.github.com/repos/OData/vocabularies/languages","stargazers_url":"https://api.github.com/repos/OData/vocabularies/stargazers","contributors_url":"https://api.github.com/repos/OData/vocabularies/contributors","subscribers_url":"https://api.github.com/repos/OData/vocabularies/subscribers","subscription_url":"https://api.github.com/repos/OData/vocabularies/subscription","commits_url":"https://api.github.com/repos/OData/vocabularies/commits{/sha}","git_commits_url":"https://api.github.com/repos/OData/vocabularies/git/commits{/sha}","comments_url":"https://api.github.com/repos/OData/vocabularies/comments{/number}","issue_comment_url":"https://api.github.com/repos/OData/vocabularies/issues/comments{/number}","contents_url":"https://api.github.com/repos/OData/vocabularies/contents/{+path}","compare_url":"https://api.github.com/repos/OData/vocabularies/compare/{base}...{head}","merges_url":"https://api.github.com/repos/OData/vocabularies/merges","archive_url":"https://api.github.com/repos/OData/vocabularies/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/OData/vocabularies/downloads","issues_url":"https://api.github.com/repos/OData/vocabularies/issues{/number}","pulls_url":"https://api.github.com/repos/OData/vocabularies/pulls{/number}","milestones_url":"https://api.github.com/repos/OData/vocabularies/milestones{/number}","notifications_url":"https://api.github.com/repos/OData/vocabularies/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/OData/vocabularies/labels{/name}","releases_url":"https://api.github.com/repos/OData/vocabularies/releases{/id}","created_at":"2013-04-01T17:58:50Z","updated_at":"2015-03-27T17:00:39Z","pushed_at":"2015-04-08T21:47:46Z","git_url":"git://github.com/OData/vocabularies.git","ssh_url":"git@github.com:OData/vocabularies.git","clone_url":"https://github.com/OData/vocabularies.git","svn_url":"https://github.com/OData/vocabularies","homepage":null,"size":276,"stargazers_count":3,"watchers_count":3,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":2,"mirror_url":null,"open_issues_count":5,"forks":2,"open_issues":5,"watchers":3,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/7"},"html":{"href":"https://github.com/OData/vocabularies/pull/7"},"issue":{"href":"https://api.github.com/repos/OData/vocabularies/issues/7"},"comments":{"href":"https://api.github.com/repos/OData/vocabularies/issues/7/comments"},"review_comments":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/7/comments"},"review_comment":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/OData/vocabularies/pulls/7/commits"},"statuses":{"href":"https://api.github.com/repos/OData/vocabularies/statuses/5a52be8d290077a5a7e875f50c9d90fe46b2f45c"}}}}