Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ODATA-1624 #225

Merged
merged 15 commits into from
May 8, 2024
Merged

ODATA-1624 #225

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
8e3cc19
Update 1 Introduction.md
ralfhandl Dec 7, 2023
11e6c25
Conformance
ralfhandl Dec 7, 2023
9446d09
Address Heiko's comment
ralfhandl Dec 11, 2023
4d7725a
Merge branch 'main' into ODATA-1624
ralfhandl Jan 11, 2024
70df71e
Reword
ralfhandl Feb 8, 2024
5c39799
Merge branch 'main' into ODATA-1624
ralfhandl Feb 8, 2024
20ebfef
Rebuilt
ralfhandl Feb 8, 2024
9e17602
Revert some changes
ralfhandl Feb 8, 2024
44b84bc
Less "either"
ralfhandl Feb 8, 2024
673a355
Merge branch 'main' into ODATA-1624
ralfhandl Feb 22, 2024
4e8a5a4
Merge branch 'main' into ODATA-1624
ralfhandl Apr 23, 2024
ef66194
Merge main, link to github
ralfhandl Apr 23, 2024
d7e3c62
Adjust section on 501
ralfhandl May 8, 2024
441be34
Relaxed requirement
ralfhandl May 8, 2024
32d9bdd
Merge branch 'main' into ODATA-1624
ralfhandl May 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/odata-protocol/odata-protocol.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -502,6 +502,11 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
<td>Setting a complex property to a different type</td>
<td><a href="https://issues.oasis-open.org/browse/ODATA-1472">ODATA-1472</a></td>
</tr>
<tr class="odd">
<td><a href="#Conformance">Section 12</a></td>
<td>Allow <code>400 Bad Request</code> for unrecognized (“future”) functionality in addition to <code>501 Not Implemented</code> for unsupported functionality</td>
<td><a href="https://issues.oasis-open.org/browse/ODATA-1624">ODATA-1624</a></td>
</tr>
</tbody>
</table>
<h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
Expand Down Expand Up @@ -2602,6 +2607,7 @@ <h4 id="11776-asynchronous-batch-requests"><a name="AsynchronousBatchRequests" h
<h1 id="12-conformance"><a name="Conformance" href="#Conformance">12 Conformance</a></h1>
<p>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.</p>
<p>To aid in client/server interoperability, this specification defines multiple levels of conformance for an OData Service, as well as the <a href="#InteroperableODataClients">minimal requirements</a> for an OData Client to be interoperable across OData services.</p>
<p>As OData itself evolves over time, the conformance clauses distinguish between <em>unsupported</em> and <em>unrecognized</em> features: unsupported features are known to the implementation (for example because they were part of OData at the time of implementation) and consciously not (yet) implemented, whereas unrecognized features are not known to the implementation (for example new query options or request patterns that were added to OData later).</p>
<h2 id="121-odata-40-service-conformance-levels"><a name="OData40ServiceConformanceLevels" href="#OData40ServiceConformanceLevels">12.1 OData 4.0 Service Conformance Levels</a></h2>
<p>OData 4.0 defines three levels of conformance for an OData Service.</p>
<p>Note: 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 <a href="#OData40MinimalConformanceLevel">OData 4.0 Minimal Conformance Level</a> without supporting any additional functionality. A service that offers more control over the data that the client retrieves may comply with the <a href="#OData40IntermediateConformanceLevel">OData 4.0 Intermediate Conformance Level</a>. Services that conform to the <a href="#OData40AdvancedConformanceLevel">OData 4.0 Advanced Conformance Level</a> can expect to interoperate with the most functionality against the broadest range of generic clients.</p>
Expand All @@ -2620,7 +2626,7 @@ <h3 id="1211-odata-40-minimal-conformance-level"><a name="OData40MinimalConforma
<li><code>OData-MaxVersion</code> (<a href="#HeaderODataMaxVersion">section 8.2.7</a>)</li>
</ol></li>
<li>MUST follow OData guidelines for extensibility (<a href="#Extensibility">section 6</a> and all subsections)</li>
<li>MUST successfully parse the request according to <a href="#ODataABNF">OData-ABNF</a> for any supported system query options and either follow the specification or return <code>501 Not Implemented</code> for any unsupported functionality (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>MUST successfully parse the request according to <a href="#ODataABNF">OData-ABNF</a> for any supported system query options and either follow the specification or fail the request, in which case it SHOULD return <code>501 Not Implemented</code> for any recognized unsupported functionality (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>MUST expose only data types defined in <a href="#ODataCSDL">OData-CSDLXML</a></li>
<li>MUST NOT require clients to understand any metadata or instance annotations (<a href="#VocabularyExtensibility">section 6.4</a>), custom headers (<a href="#HeaderFieldExtensibility">section 6.5</a>), or custom content (<a href="#PayloadExtensibility">section 6.2</a>) in the payload in order to correctly consume the service</li>
<li>MUST NOT violate any OData update semantics (<a href="#DataModification">section 11.4</a> and all subsections)</li>
Expand Down Expand Up @@ -2658,7 +2664,7 @@ <h3 id="1212-odata-40-intermediate-conformance-level"><a name="OData40Intermedia
<p>In order to conform to the OData Intermediate Conformance Level, a service:</p>
<ol type="1">
<li>MUST conform to the <a href="#OData40MinimalConformanceLevel">OData 4.0 Minimal Conformance Level</a></li>
<li>MUST successfully parse the <a href="#ODataABNF">OData-ABNF</a> and either follow the specification or return <code>501 Not Implemented</code> for any unsupported functionality (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>MUST successfully parse the request according to <a href="#ODataABNF">OData-ABNF</a> and either follow the specification or fail the request, in which case it SHOULD return <code>501 Not Implemented</code> for any recognized unsupported functionality (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>MUST support <code>$select</code> (<a href="#SystemQueryOptionselect">section 11.2.5.1</a>)</li>
<li>MUST support casting to a derived type according to <a href="#ODataURL">OData-URL</a> if derived types are present in the model</li>
<li>MUST support <code>$top</code> (<a href="#SystemQueryOptiontop">section 11.2.6.3</a>)</li>
Expand All @@ -2667,8 +2673,8 @@ <h3 id="1212-odata-40-intermediate-conformance-level"><a name="OData40Intermedia
<ol type="1">
<li>MUST support <code>eq</code>, <code>ne</code> filter operations on properties of entities in the requested entity set (<a href="#BuiltinFilterOperations">section 11.2.6.1.1</a>)</li>
<li>MUST support aliases in <code>$filter</code> expressions (<a href="#ParameterAliases">section 11.2.6.1.3</a>)</li>
<li>SHOULD support additional filter operations (<a href="#BuiltinFilterOperations">section 11.2.6.1.1</a>) and MUST return <code>501 Not Implemented</code> for any unsupported filter operations (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>SHOULD support the canonical functions (<a href="#BuiltinQueryFunctions">section 11.2.6.1.2</a>) and MUST return <code>501 Not Implemented</code> for any unsupported canonical functions (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>SHOULD support additional filter operations (<a href="#BuiltinFilterOperations">section 11.2.6.1.1</a>) and MUST return <code>501 Not Implemented</code> for any unsupported or <code>400 Bad Request</code> for any unrecognized filter operations (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>SHOULD support the canonical functions (<a href="#BuiltinQueryFunctions">section 11.2.6.1.2</a>) and MUST return <code>501 Not Implemented</code> for any unsupported or <code>400 Bad Request</code> for any unrecognized functions (<a href="#ResponseCode501NotImplemented">section 9.3.1</a>)</li>
<li>SHOULD support <code>$filter</code> on expanded entities (<a href="#ExpandOptions">section 11.2.5.2.1</a>)</li>
</ol></li>
<li>SHOULD publish metadata at <code>$metadata</code> according to <a href="#ODataCSDL">OData-CSDLXML</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
Expand Down
17 changes: 10 additions & 7 deletions docs/odata-protocol/odata-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,7 @@ Section | Feature / Change | Issue
--------|------------------|------
[Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)
[Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [ODATA-1472](https://issues.oasis-open.org/browse/ODATA-1472)
[Section 12](#Conformance)| Allow `400 Bad Request` for unrecognized ("future") functionality in addition to `501 Not Implemented` for unsupported functionality| [ODATA-1624](https://issues.oasis-open.org/browse/ODATA-1624)

## <a name="Glossary" href="#Glossary">1.2 Glossary</a>

Expand Down Expand Up @@ -6316,6 +6317,8 @@ multiple levels of conformance for an OData Service, as well as the
[minimal requirements](#InteroperableODataClients) for an OData Client
to be interoperable across OData services.

As OData itself evolves over time, the conformance clauses distinguish between _unsupported_ and _unrecognized_ features: unsupported features are known to the implementation (for example because they were part of OData at the time of implementation) and consciously not (yet) implemented, whereas unrecognized features are not known to the implementation (for example new query options or request patterns that were added to OData later).

## <a name="OData40ServiceConformanceLevels" href="#OData40ServiceConformanceLevels">12.1 OData 4.0 Service Conformance Levels</a>

OData 4.0 defines three levels of conformance for an OData Service.
Expand Down Expand Up @@ -6360,8 +6363,8 @@ request
([section 6](#Extensibility) and all subsections)
7. MUST successfully parse the request according to
[OData-ABNF](#ODataABNF) for any supported system query options and
either follow the specification or return
`501 Not Implemented` for any
either follow the specification or fail the request, in which case it SHOULD return
`501 Not Implemented` for any recognized
unsupported functionality ([section 9.3.1](#ResponseCode501NotImplemented))
8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL)
9. MUST NOT require clients to understand any metadata or instance
Expand Down Expand Up @@ -6428,9 +6431,9 @@ service:

1. MUST conform to the [OData 4.0 Minimal Conformance
Level](#OData40MinimalConformanceLevel)
2. MUST successfully parse the [OData-ABNF](#ODataABNF) and either
follow the specification or return `501 Not Implemented` for any
unsupported functionality ([section 9.3.1](#ResponseCode501NotImplemented))
2. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) and either
follow the specification or fail the request, in which case it SHOULD return `501 Not Implemented` for any
recognized unsupported functionality ([section 9.3.1](#ResponseCode501NotImplemented))
3. MUST support `$select` ([section 11.2.5.1](#SystemQueryOptionselect))
4. MUST support casting to a derived type according to
[OData-URL](#ODataURL) if derived types are present in the model
Expand All @@ -6441,10 +6444,10 @@ unsupported functionality ([section 9.3.1](#ResponseCode501NotImplemented))
in the requested entity set ([section 11.2.6.1.1](#BuiltinFilterOperations))
2. MUST support aliases in `$filter` expressions ([section 11.2.6.1.3](#ParameterAliases))
3. SHOULD support additional filter operations ([section 11.2.6.1.1](#BuiltinFilterOperations))
and MUST return `501 Not Implemented` for any unsupported filter
and MUST return `501 Not Implemented` for any unsupported or `400 Bad Request` for any unrecognized filter
operations ([section 9.3.1](#ResponseCode501NotImplemented))
4. SHOULD support the canonical functions ([section 11.2.6.1.2](#BuiltinQueryFunctions)) and
MUST return `501 Not Implemented` for any unsupported canonical
MUST return `501 Not Implemented` for any unsupported or `400 Bad Request` for any unrecognized
functions ([section 9.3.1](#ResponseCode501NotImplemented))
5. SHOULD support `$filter` on expanded entities ([section 11.2.5.2.1](#ExpandOptions))
8. SHOULD publish metadata at `$metadata` according to
Expand Down
3 changes: 3 additions & 0 deletions odata-protocol/1 Introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ Response code `204 No Content` after successful data modification if requested r
[Section ##UpdateaComplexProperty]|
Setting a complex property to a different type|
[ODATA-1472](https://issues.oasis-open.org/browse/ODATA-1472)
[Section ##Conformance]|
Allow `400 Bad Request` for unrecognized ("future") functionality in addition to `501 Not Implemented` for unsupported functionality|
[ODATA-1624](https://issues.oasis-open.org/browse/ODATA-1624)

## ##subsec Glossary

Expand Down
16 changes: 9 additions & 7 deletions odata-protocol/12 Conformance.md
View file
Open in desktop
HeikoTheissen marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ multiple levels of conformance for an OData Service, as well as the
[minimal requirements](#InteroperableODataClients) for an OData Client
to be interoperable across OData services.

As OData itself evolves over time, the conformance clauses distinguish between _unsupported_ and _unrecognized_ features: unsupported features are known to the implementation (for example because they were part of OData at the time of implementation) and consciously not (yet) implemented, whereas unrecognized features are not known to the implementation (for example new query options or request patterns that were added to OData later).

## ##subsec OData 4.0 Service Conformance Levels

OData 4.0 defines three levels of conformance for an OData Service.
Expand Down Expand Up @@ -59,8 +61,8 @@ request
([section ##Extensibility] and all subsections)
7. MUST successfully parse the request according to
[OData-ABNF](#ODataABNF) for any supported system query options and
either follow the specification or return
`501 Not Implemented` for any
either follow the specification or fail the request, in which case it SHOULD return
`501 Not Implemented` for any recognized
unsupported functionality ([section ##ResponseCode501NotImplemented])
8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL)
9. MUST NOT require clients to understand any metadata or instance
Expand Down Expand Up @@ -127,9 +129,9 @@ service:

1. MUST conform to the [OData 4.0 Minimal Conformance
Level](#OData40MinimalConformanceLevel)
2. MUST successfully parse the [OData-ABNF](#ODataABNF) and either
follow the specification or return `501 Not Implemented` for any
unsupported functionality ([section ##ResponseCode501NotImplemented])
2. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) and either
follow the specification or fail the request, in which case it SHOULD return `501 Not Implemented` for any
recognized unsupported functionality ([section ##ResponseCode501NotImplemented])
3. MUST support `$select` ([section ##SystemQueryOptionselect])
4. MUST support casting to a derived type according to
[OData-URL](#ODataURL) if derived types are present in the model
Expand All @@ -140,10 +142,10 @@ unsupported functionality ([section ##ResponseCode501NotImplemented])
in the requested entity set ([section ##BuiltinFilterOperations])
2. MUST support aliases in `$filter` expressions ([section ##ParameterAliases])
3. SHOULD support additional filter operations ([section ##BuiltinFilterOperations])
and MUST return `501 Not Implemented` for any unsupported filter
and MUST return `501 Not Implemented` for any unsupported or `400 Bad Request` for any unrecognized filter
operations ([section ##ResponseCode501NotImplemented])
4. SHOULD support the canonical functions ([section ##BuiltinQueryFunctions]) and
MUST return `501 Not Implemented` for any unsupported canonical
MUST return `501 Not Implemented` for any unsupported or `400 Bad Request` for any unrecognized
functions ([section ##ResponseCode501NotImplemented])
5. SHOULD support `$filter` on expanded entities ([section ##ExpandOptions])
8. SHOULD publish metadata at `$metadata` according to
Expand Down