OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: [OASIS Issue Tracker] (ODATA-846) Add version 4.01


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

Michael Pizzo updated ODATA-846:
--------------------------------

    Proposal: 
1) Define an OData-Versions annotation that specifies the OData version(s) supported by the service:

<Term Name="ODataVersions" Type="Edm.String" AppliesTo="EntityContainer">
  <Annotation Term="Core.Description" String="A space-separated list of supported versions of the OData Protocol." />
</Term>

2) For new 4.01 features, we should:
    a) define behavior/compatibility for 4.0 clients (see below), and
    b) define vocabularies to test the presence of the new feature

Conformance Rules:

OData 4.0 Compliant JSON Payloads
-MUST not omit the odata. prefix (ODATA-630)
-MUST not omit the # prefix for @odata.type values (ODATA-561)
-SHOULD represent numeric value exceptions for single/double using "INF", "-INF", and "NaN" property values
-MAY include the numericValueException annotation for any numeric value exceptions

OData 4.01 Compliant JSON Payloads
-MUST represent numeric value exceptions using the numericValueException annotation instead of "INF", "-INF", and "NaN" for numeric property values (ODATA-920)
-MAY include or omit the odata. prefix (ODATA-630)
-MAY include or omit the # prefix from odata.type values (ODATA-561)
-MAY include related entities inline for a delta payload (ODATA-876)
-MAY exclude TargetId for a deleted link in a 0..1 relationship for a delta payload (ODATA-814)

OData 4.0 Compliant CSDL Payloads
-MUST NOT contain new CSDL elements or attributes, or new values for elements/attribute with enumerated values
-MUST NOT include properties in derived types that overwrite property of base type (ODATA-894)
-MUST NOT include EDM.Untyped (ODATA-881)
-MUST NOT include extended edm:Path expression (ODATA-786)
-MUST NOT use Edm.AnyPath and Edm.AnyPropertyPath (ODATA-516)
-MUST NOT specify referential constraints to complex types and navigation properties (ODATA-560)
-MAY include new CSDL annotations

OData 4.01 Compliant CSDL Payloads
-MAY include properties in derived types that overwrite property of base type (ODATA-894)
-MAY include EDM.Untyped (ODATA-881)
-MAY include extended edm:Path expression (ODATA-786)
-MAY include Edm.AnyPath and Edm.AnyPropertyPath (ODATA-516)
-MAY include referential constraints to complex types and navigation properties (ODATA-560)

Compliant 4.01 Services:
-MUST return 4.0 for the Edmx:Version attribute (we are not defining a new version of Edmx)
-MUST follow OData semantics or fail request for any 4.01 syntax or request payloads
-MUST return 4.0-compliant JSON payloads when requested with the OData-MaxVersion=4.0 request header
-MUST support 4.0-compliant JSON request payloads specified with the OData-Version=4.0 request header
  -MUST support property@odata.bind in PATCH, PUT, POST (ODATA-666)
-MUST return 4.01 compliant JSON payloads when requested using the OData-MaxVersion=4.01 request header
-MUST support 4.01-compliant request payloads specified with the OData-Version=4.01 request header
  -MUST support linking specified using "property":{"@odata.id":"url..."} instead of @odata.bind in PATCH, PUT, POST (ODATA-666)
  -MUST honor the @odata.etag annotation within payloads, if specified (ODATA-666)
-MUST reject a requests with an incompatible SchemaVersion header (if SchemaVersion is returned from $metadata)
-SHOULD return the new ODataVersions annotation. 
  -MUST include 4.0 if 4.01 is included.
-MUST return the AsyncResult header in the final response to an async request (ODATA-809)
-SHOULD support a non-message format for final response of an async request (ODATA-809)
-MAY support 4.01 syntax regardless of version (Does not necessitate a change in OData-Version of response)
-MAY support 4.01 behavior, including returning 4.01 content and payloads, if the client does not specify the OData-MaxVersion=4.0 request header

-MUST support 4.01 variants for supported syntax
  -MUST support both prefixed and non-prefixed variants for supported headers, preference values, and format parameters (See OData-937)
  -MUST support eq/ne comparison to null for 0..1 nav props (ODATA-617)
  -MUST support an empty object or no-content for the request body when invoking action with no non-binding parameters (See OData-938)
  -MUST support enumeration and duration literals in URLs with and without the type prefix (See OData-834)
  -MUST support invoking functions/actions with or without namespace qualification (OData-812)
  -MUST support invoking parameterless function imports with or without parens (ODATA-664)
  -MUST support casting strings to primitive types (ODATA 563)
  -MUST support the "in" operator in places where "or" would be supported (ODATA-556)
-SHOULD support "divby" (ODATA-918)
-SHOULD support negative indexes for substring function (ODATA-901)
-SHOULD support implicit aliasing of parameters (See ODATA-763)
-MAY support PUT against single entity with nested content (ODATA-9024)
-MAY support DELETE/PUT to $ref of a collection-valued nav prop (ODATA-922)
-MAY support the count of a filtered/searched collection in a common expression (ODATA-897)
-MAY support deep update and deep insert operations (ODATA-666)
-MAY support $search for all collections (ODATA-888)
-MAY support eq/ne structural comparison (ODATA-617)
-MAY support POST to collections of complex/primitive types (ODATA-616)
-MAY support PATH and DELETE with $filter (ODATA-615)
-MAY support PATCH to entity sets using the delta-response format (ODATA-613)
-MAY (SHOULD?) support Key-As-Segment url convention for single-part keys (ODATA-799)

Compliant 4.01 Clients:
-MUST send OData 4.0-compliant payloads to a services that don't advertise support for 4.01 or greater
-MUST use appropriate syntax when sending a request body that specifies OData-Version=4.01
   -MUST use "property":{"@odata.id":"url..."} instead of @odata.bind in PATCH, PUT, POST (ODATA-666)
-MUST be prepared to receive any 4.0 or 4.01-compliant payloads (according to OData-Version request header)
-MUST be prepared to receive any valid 4.01 CSDL 
-SHOULD use capabilities to determine if a 4.01 feature is supported but MAY attempt syntax (and receive either 501 not implemented or 400 bad request)


Areas of the spec that talk about versioning:
Part 1: Protocol
- Section 5.1 Protocol Versioning
- Chapter 12 Security Considerations

Part 3: CSDL
- Section 3.1.1 Attribute Version
- Sections 2.1 and 2.2 XML Namespaces

JSON Format
- Chapter 21 Security Considerations



  was:
1) Define an OData-Versions annotation that specifies the OData version(s) supported by the service:

<Term Name="ODataVersions" Type="Edm.String" AppliesTo="EntityContainer">
  <Annotation Term="Core.Description" String="A space-separated list of supported versions of the OData Protocol." />
</Term>

2) For new 4.01 features, we should:
    a) define behavior/compatibility for 4.0 clients (see below), and
    b) define vocabularies to test the presence of the new feature

Conformance Rules:

OData 4.0 Compliant JSON Payloads
-MUST not omit the odata. prefix (ODATA-630)
-MUST not omit the # prefix for @odata.type values (ODATA-561)
-SHOULD represent numeric value exceptions for single/double using "INF", "-INF", and "NaN" property values
-MAY include the numericValueException annotation for any numeric value exceptions

OData 4.01 Compliant JSON Payloads
-MUST represent numeric value exceptions using the numericValueException annotation instead of "INF", "-INF", and "NaN" for numeric property values (ODATA-920)
-MAY include or omit the odata. prefix (ODATA-630)
-MAY include or omit the # prefix from odata.type values (ODATA-561)
-MAY include related entities inline for a delta payload (ODATA-876)
-MAY exclude TargetId for a deleted link in a 0..1 relationship for a delta payload (ODATA-814)

OData 4.0 Compliant CSDL Payloads
-MUST NOT contain new CSDL elements or attributes, or new values for elements/attribute with enumerated values
-MUST NOT include properties in derived types that overwrite property of base type (ODATA-894)
-MUST NOT include EDM.Untyped (ODATA-881)
-MUST NOT include extended edm:Path expression (ODATA-786)
-MUST NOT use Edm.AnyPath and Edm.AnyPropertyPath (ODATA-516)
-MUST NOT specify referential constraints to complex types and navigation properties (ODATA-560)
-MAY include new CSDL annotations

OData 4.01 Compliant CSDL Payloads
-MAY include properties in derived types that overwrite property of base type (ODATA-894)
-MAY include EDM.Untyped (ODATA-881)
-MAY include extended edm:Path expression (ODATA-786)
-MAY include Edm.AnyPath and Edm.AnyPropertyPath (ODATA-516)
-MAY include referential constraints to complex types and navigation properties (ODATA-560)

Compliant 4.01 Services:
-MUST return 4.0 for the Edmx:Version attribute (we are not defining a new version of Edmx)
-MUST follow OData semantics or fail request for any 4.01 syntax or request payloads
-MUST return 4.0-compliant JSON payloads when requested with the OData-MaxVersion=4.0 request header
-MUST support 4.0-compliant JSON request payloads specified with the OData-Version=4.0 request header
  -MUST support property@odata.bind in PATCH, PUT, POST (ODATA-666)
-MUST return 4.01 compliant JSON payloads when requested using the OData-MaxVersion=4.01 request header
-MUST support 4.01-compliant request payloads specified with the OData-Version=4.01 request header
  -MUST support linking specified using "property":{"@odata.id":"url..."} instead of @odata.bind in PATCH, PUT, POST (ODATA-666)
  -MUST honor the @odata.etag annotation within payloads, if specified (ODATA-666)
-MUST reject a requests with an incompatible SchemaVersion header (if SchemaVersion is returned from $metadata)
-SHOULD return the new ODataVersions annotation. 
  -MUST include 4.0 if 4.01 is included.
-MUST return the AsyncResult header in the final response to an async request (ODATA-809)
-SHOULD support a non-message format for final response of an async request (ODATA-809)
-MAY support 4.01 syntax regardless of version (Does not necessitate a change in OData-Version of response)
-MAY support 4.01 behavior, including returning 4.01 content and payloads, if the client does not specify the OData-MaxVersion=4.0 request header

-MUST support 4.01 variants for supported syntax
  -MUST support both prefixed and non-prefixed variants for supported headers, preference values, and format parameters (See OData-937)
  -MUST support eq/ne comparison to null for 0..1 nav props (ODATA-617)
  -MUST support an empty object or no-content for the request body when invoking action with no non-binding parameters (See OData-938)
  -MUST support enumeration and duration literals in URLs with and without the type prefix (See OData-834)
  -MUST support invoking functions/actions with or without namespace qualification (OData-812)
  -MUST support invoking parameterless function imports with or without parens (ODATA-664)
  -MUST support casting strings to primitive types (ODATA 563)
  -MUST support the "in" operator in places where "or" would be supported (ODATA-556)
-SHOULD support "divby" (ODATA-918)
-SHOULD support negative indexes for substring function (ODATA-901)
-SHOULD support implicit aliasing of parameters (See ODATA-763)
-MAY support PUT against single entity with nested content (ODATA-9024)
-MAY support DELETE/PUT to $ref of a collection-valued nav prop (ODATA-922)
-MAY support the count of a filtered/searched collection in a common expression (ODATA-897)
-MAY support deep update and deep insert operations (ODATA-666)
-MAY support $search for all collections (ODATA-888)
-MAY support eq/ne structural comparison (ODATA-617)
-MAY support POST to collections of complex/primitive types (ODATA-616)
-MAY support PATH and DELETE with $filter (ODATA-615)
-MAY support PATCH to entity sets using the delta-response format (ODATA-613)

Compliant 4.01 Clients:
-MUST send OData 4.0-compliant payloads to a services that don't advertise support for 4.01 or greater
-MUST use appropriate syntax when sending a request body that specifies OData-Version=4.01
   -MUST use "property":{"@odata.id":"url..."} instead of @odata.bind in PATCH, PUT, POST (ODATA-666)
-MUST be prepared to receive any 4.0 or 4.01-compliant payloads (according to OData-Version request header)
-MUST be prepared to receive any valid 4.01 CSDL 
-SHOULD use capabilities to determine if a 4.01 feature is supported but MAY attempt syntax (and receive either 501 not implemented or 400 bad request)


Areas of the spec that talk about versioning:
Part 1: Protocol
- Section 5.1 Protocol Versioning
- Chapter 12 Security Considerations

Part 3: CSDL
- Section 3.1.1 Attribute Version
- Sections 2.1 and 2.2 XML Namespaces

JSON Format
- Chapter 21 Security Considerations




> Add version 4.01
> ----------------
>
>                 Key: ODATA-846
>                 URL: https://issues.oasis-open.org/browse/ODATA-846
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: OData Protocol
>    Affects Versions: V4.0_ERRATA02
>            Reporter: Ralf Handl
>            Assignee: Michael Pizzo
>             Fix For: V4.01_WD01
>
>
> This issue tracks all places that need to reflect the new version number in the  prose text.
> We will also use this issue to track how we do version negotiation between a 4.0 and a 4.01 client and service.



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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]