[OASIS Issue Tracker] Updated: (ODATA-334) Integrate conformance concept with careful consideration of versioning semantics (into protocol work product)

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

     [ http://tools.oasis-open.org/issues/browse/ODATA-334?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Michael Pizzo updated ODATA-334:
--------------------------------

    Proposal: 
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




  was:Approve conformance statements in current documents


> Integrate conformance concept with careful consideration of versioning semantics (into protocol work product)
> -------------------------------------------------------------------------------------------------------------
>
>                 Key: ODATA-334
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-334
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData Protocol 
>    Affects Versions: V4.0_WD01
>         Environment: [Proposed]
>            Reporter: Stefan Drees
>             Fix For: V4.0_WD01
>
>
> There is a need for finding and documenting a well-weighted and working interplay of versioning and conformance levels (client and server). These dimensions are neither aligned nor orthogonal. The Service Conformance Level concept [Conformance Levels](https://www.oasis-open.org/committees/download.php/48595/OData%20Service%20Conformance%20Levels.docx)  and the latest [OData Core Part 1: Protocol, Version 4.0](https://www.oasis-open.org/committees/download.php/48604/odata-core-v4.0-wd01-part1-protocol-2013-03-20.doc)  are to be combined into a subsequent protocol work products conformance section in a way, that where applicable allows conformance levels represent fine-grained control abput each party in the communication MAY safely assume from the partner and where to further investigate.
> Versions and conformance may appear as major and minor aspects of versioning from some viewpoints. Where this is so, we should clearly state and explain the interworking. Where it is not but unrelated (layered on top) we should equally explain and document this.
> I undestand, that currently we plan to define one client related conformance level, namely 'the minimal requirements for an OData Client to be interoperable across OData services.' (everything 'more versatile' is ok, below is well not enough. Right?)
> Further we segragate the server capabilities w.r.t conformance into three levels: 'Publishing', 'Service' and 'Full' (ordered by ascending versatility).
> When it comes to versioning, the version should be negotiated on a connection (series of request-response-pairs) basis but should not depend upon attributes of the response (as I understood from discussion on the opendata.org mailing list???)
> The server we describe as somehow "being version 4.0" and conforming to level "some-level" should send the min version his response needs to be interpreted, as all clients are assumed to be equal or better than minimal conformance :-)
> If the client requested a version below the one needed for the response (may that happen?) the server will indicate this as an error somehow.
> So client sends max version she understands, server answers with error xor min version <= max version(of clients request) response.
> Does this crude collection help in seeding ammending the protocol with the content of the conformnace concept document and subsequent clean-up / rewrite of the relevant text?? I hope so.
> Also maybe matrices depicting aspects currently described as per conformance level separate itemized listings in the concept document might be helfull formats (like eg. one line in such a table would be Support for /$count with empty cell in 'Publishing' column, 'S' (for SHOULD) in 'Service' and 'M' (for MUST) in 'Full' column.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira