Integrate conformance concept with careful consideration of versioning semantics (into protocol work product)

Approve conformance statements in current documents: In Protocol: 12 Conformance OData is designed as a set of conventions that can be layered on top of existing standards to provide common representations for common functionality. Not all services will support all of the conventions defined in the protocol; services choose those conventions defined in OData as the representation to expose that functionality appropriate for their scenarios. To aid in client/server interoperability, this specification defines multiple levels of conformance for an OData Service, as well as the minimal requirements for an OData Client to be interoperable across OData services. 12.1 OData Service Conformance Levels OData defines three levels of conformance for an OData Service. The conformance levels are design to correspond to different service scenarios. For example, a service that publishes data compliant with one or more of the OData defined formats may comply with the OData Minimal Conformance Level without supporting any additional functionality. A service that supports finer grained query functionality may comply with the OData Intermediate Conformance Level. Services that conform to the OData Advanced Conformance Level can expect to interoperate with the most functionality against the broadest range of generic clients. Services are encouraged to support as much additional functionality beyond their level of conformance as is appropriate for their intended scenario. 12.1.1 OData Minimal Conformance Level In order to conform to the OData Minimal conformance level, a service: • MUST publish a service document at the service root • MUST return data according to at least one of the OData defined formats • MUST support server-driven paging when returning partial results • MUST return the appropriate OData-Version header • MUST honor the semantics the following headers, or fail the request o Accept o OData-MaxVersion • MUST follow OData guidelines for extensibility • MUST successfully parse the request according to [OData-ABNF] for any supported system query string options and either follow the specification or return 501 Not Implemented for any unsupported functionality • MUST expose only data types defined in this specification • MUST NOT require clients to understand any metadata or instance annotations, custom headers, or custom content in the payload in order to correctly consume the service • MUST NOT violate any OData update semantics • SHOULD support $expand specifically to enable clients to define the extent of the graph to retrieve • MUST NOT violate any other OData defined semantics In addition, to be considered an Updatable OData Service, the service: • MUST include edit links (explicitly or implicitly) for all updatable or deletable resources • MUST support POST of new entities to insertable entity sets • MUST support POST of new related entities to updatable navigation properties • MUST support POST to $ref to add an existing entity to an updatable related collection • MUST support PUT to $ref to set an existing single updatable related entity • MUST support PATCH to all edit links for updatable resources • MUST support DELETE to all edit links for deleteable resources • MUST support DELETE to $ref to remove an entity from an updatable navigation property • MUST support if-match header in update/delete of any resources returned with an ETag • MUST return a Location header from POST with the edit-link or self-link of the created resource • MUST include the OData-EntityId header in response to any POST/PATCH that returns 204 No Content • MUST support Upserts • SHOULD support PUT and PATCH to an individual primitive or complex property (respectively) • SHOULD support DELETE to set an individual property to null • SHOULD support deep inserts 12.1.2 OData Intermediate Conformance Level In order to conform to the OData Intermediate Conformance level, a service: • MUST conform to the OData Minimal level • SHOULD publish metadata at /$metadata according to [OData-CSDL] • SHOULD support the OData JSON format • MUST successfully parse the [OData ABNF] and either follow the specification or return 501 Not Implemented for any unsupported functionality • MUST support $select • MUST support casting to a derived type if present in the model • MUST support $top • MUST support /$value on media entities and individual properties • MUST support $filter o MUST support eq, ne filter operations on filterable properties o MUST support aliases in $filter expressions o SHOULD support additional filter operations and MUST fail on any unsupported filter operations o SHOULD support the canonical functions and MUST fail on any unsupported canonical functions • SHOULD support $search • SHOULD support $skip • SHOULD support /$count • SHOULD support $expand for expandable navigation properties o SHOULD support $filter on expanded properties • SHOULD support the canonical functions any and all on navigation and collection-valued properties • SHOULD support /$count on navigation, collection properties within a $filter expression • SHOULD support $orderby asc and desc on individual properties 12.1.3 OData Advanced Conformance Level In order to conform to the OData Advanced Conformance level, a service: • MUST conform to at least the OData Intermediate Conformance Level • MUST publish metadata at /$metadata according to [OData-CSDL] • MUST support the OData JSON format • MUST support /$count on navigation and collection properties within a $filter expression • MUST support the canonical functions any and all on navigation and collection-valued properties • MUST support $skip • MUST support /$count on collection valued resource paths • MUST support $inlinecount • MUST support $orderby asc and desc on individual properties • MUST support $expand for expandable navigation properties o MUST support returning references for expanded properties o MUST support $filter on filterable properties of expanded entities o MUST support cast segment in expand with derived types o SHOULD support $orderby asc and desc on individual properties o SHOULD support $inlinecount of expanded properties o SHOULD support $top and $skip on expanded properties o SHOULD support $search on expanded properties o SHOULD support $levels for recursive expand • MUST support $search • MUST support $batch • MUST support the resource path conventions defined in [OData-URL] • SHOULD support Asynchronous operations • SHOULD support Delta change tracking • SHOULD support queries rooted at the entity container • SHOULD support a conforming OData service interface over metadata 12.2 Interoperable OData Clients To be generally interoperable, OData Clients: • MUST specify the Odata-MaxVersion header in request • MUST specify OData-Version and Content-Type in any request with a payload • MUST be a conforming consumer of OData as defined in [OData-JSON] • MUST follow redirects • MUST be correctly handle next links • MUST be a conformant client of metadata as defined in [OData-CSDL] • MUST support instances returning properties and navigation properties not specified in metadata • MUST support entity instances with external metadata • MUST support properties with externally defined data types • MAY request entity references in place of entities previously returned in the response • MAY support deleted entries, link entries, deleted link entries in a delta response • MAY support asynchronous responses • MAY support odata.metadata=minimal in a JSON response • MAY support odata.streaming To support updates, OData Clients: • MUST generate PATCH requests for updates In CSDL: The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol] , are gratefully acknowledged. Atom: Conforming clients MUST be prepared to consume a service that uses any or all of the constructs defined in this specification, including custom annotations defined by the service, and MUST ignore any constructs not defined in this version of the specification. A conforming OData service MUST comply with one of the conformance levels defined in [OData-Protocol] . In order to conform to the OData Atom format, a service: • MUST support the application/atom+xml, application/xml and application/atomsvc+xml media types in the Accept header • SHOULD support the $format system query option • MUST include the next link in feeds containing partial results • MUST return service documents as Atom service documents • MUST return XML responses in well formed XML according to this specification • MUST return well-formed Atom payloads with the following exceptions: o The next link MAY be returned at the end of the payload o The delta link MAY be returned at the end of the payload • MUST NOT violate any other aspects of this OData Atom specification In order to be a conforming consumer of the OData Atom format, a client or service: • MUST be prepared to receive all data types o defined in this specification defined in [OData-CSDL] (client) o exposed by the service (service) • MUST be prepared to receive custom annotations JSON: A conforming OData service MUST comply with one of the conformance levels defined in [OData-Protocol] . In order to conform to the OData JSON format, a service: • MUST support the application/json media type in the Accept header • SHOULD support the $format system query option • MAY support the odata.streaming=true parameter in the Accept header • MUST return well-formed JSON payloads • MUST support odata.metadata=full • MAY return full metadata regardless of odata.metadata • MUST include the odata.nextLink annotation in the feed for partial results • MUST NOT violate any other aspects of this OData JSON specification In order to be a conforming consumer of the OData JSON format, a client or service: • MUST understand odata.metadata=minimal OR explicitly specify no odata.metadata=none or odata.metadata=full in request • MUST be prepared to consume a response with full metadata • MUST NOT require odata.streaming=true in the Content-Type header • MUST be prepared to receive all data types o defined in this specification (client) o exposed by the service (service) • MUST support entities returned as entity references • MUST interpret all odata annotations defined according to the version of the response • MUST be prepared to receive any annotations, including odata annotations, not defined in the OData version of the response • MUST be prepared to receive custom annotations CSDL: Conforming services MUST follow all rules of this specification for the types, sets, operations, containers and annotations they expose. Conforming clients MUST be prepared to consume a model that uses any or all of the constructs defined in this specification, including custom annotations defined by the service, and MUST ignore any elements or attributes not defined in this version of the specification. Plus Comments: Protocol: Call out that you interoperate with any service that complies at least to OData Minimal and implements JSON. Atom: don't need to understand deltas to be interoperable

https://www.oasis-open.org/committees/document.php?document_id=48966&wg_abbrev=odata https://www.oasis-open.org/committees/document.php?document_id=48965&wg_abbrev=odata https://www.oasis-open.org/committees/document.php?document_id=48963&wg_abbrev=odata https://www.oasis-open.org/committees/download.php/48964/odata-core-v4.0-wd01-part2-url-conventions-current.docx https://www.oasis-open.org/committees/download.php/48962/odata-core-v4.0-wd01-part3-csdl-current.docx Accepted: https://www.oasis-open.org/committees/download.php/49055/odata-meeting-35_on-20130502-minutes.html#odata-334