[OASIS Issue Tracker] (ODATA-884) Add term ErrorCodes to describe possible codes in error messages (public comment c201510e00019)

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

    [ https://issues.oasis-open.org/browse/ODATA-884?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=68457#comment-68457 ] 

Michael Pizzo commented on ODATA-884:
-------------------------------------

Updated working proposal based on discussion in 2017-12-7 meeting:
1) Added hierarchy of method, then response code, then conditions
2) Generalized to support non-error responses

Note that OpenAPI does not break out individual conditions for each status code, but does support a description for the overall status code, so added a "description" at the HttpStatusCode which would have to generalize the specific conditions listed under "Conditions".

Not yet addressed:
1) Differentiating entity set versus single entity (perhaps through Qualifier?)
2) Does not expose descriptions on method level, only status and condition
3) Add to NavigationRestrictions (or equivalent) in order to describe results from (i.e., containment) navigation properties

> Add term ErrorCodes to describe possible codes in error messages (public comment c201510e00019)
> -----------------------------------------------------------------------------------------------
>
>                 Key: ODATA-884
>                 URL: https://issues.oasis-open.org/browse/ODATA-884
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: Vocabularies
>    Affects Versions: V4.0_CSD01
>            Reporter: Ralf Handl
>            Assignee: Ralf Handl
>             Fix For: V4.0_CSD02
>
>
> Jeff Wight proposes to add a term that allows describing possible code values in OData error responses, see https://lists.oasis-open.org/archives/odata-comment/201510/msg00019.html
> Example:
> <Annotation Term="Core.ErrorCodes">
>   <Collection>
>     <Record>
>       <PropertyValue Property="HttpMethod" String="GET" />
>       <PropertyValue Property="HttpStatusCode" String="400" />
>       <PropertyValue Property="ODataErrorCode" String="QueryFilterFunctionNotSupported" />
>       <PropertyValue Property="Description"
>         String="This error indicates that a request was made with a filter function that isn’t supported on this entity set.  Please refer to the Capabilities.FilterFunctions annotation on this entity set for a list of supported functions, and the exact error message for which function usage triggered this error." />
>     </Record>
>   </Collection>
> </Annotation>
> Definition
> <Term Name="ErrorCodes" Type="Collection(Core.ErrorCodeType)" AppliesTo="EntitySet Singleton ActionImport FunctionImport Action Function">
>   <Annotation Term="Core.Description" String="Describes possible error codes in OData responses" />
>   <Annotation Term="Core.LongDescription" String="The list need not be complete. It may be used to generate API documentation, so restricting it to the most common and most important errors may increase readability." /></Term>
> <ComplexType Name="ErrorCodeType">
>   <Property Name="HttpMethod" Type="Edm.String">
>     <Annotation Term="Core.Description" String="Request verb of the HTTP request, e.g. GET, POST, PATCH, DELETE" />
>   </Property>
>   <Property Name="HttpStatusCode" Type="Edm.String">
>     <Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" />
>   </Property>
>   <Property Name="ODataErrorCode" Type="Edm.String">
>     <Annotation Term="Core.Description" String="Language-independent, machine-readable OData error code" />
>   </Property>
>   <Property Name="Description" Type="Edm.String">
>     <Annotation Term="Core.Description" String="Human-readable description of the error situation" />
>   </Property>
> </ComplexType>



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