[ https://issues.oasis-open.org/browse/ODATA-884?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael Pizzo updated ODATA-884:
--------------------------------
Proposal:
<Term Name="HttpRequests" Type="Collection(Core.HttpRequest)" AppliesTo="EntitySet Singleton ActionImport FunctionImport Action Function">
<Annotation Term="Core.Description" String="Describes possible HTTP requests" />
<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 responses may increase readability." />
</Term>
<ComplexType Name="HttpRequest">
<Property Name="Method" Type="Edm.String">
<Annotation Term="Core.Description" String="Request verb of the HTTP request, e.g. GET, POST, PATCH, DELETE" />
</Property>
<Property Name="CustomQueryOptions" Type="Collection(Capabilities.CustomParameter)">
<Annotation Term="Core.Description" String="Custom query options that are supported/required for the annotated resource" />
</Property>
<Property Name="CustomHeaders" Type="Collection(Core.CustomParameter)">
<Annotation Term="Core.Description" String="Custom headers that are supported/required for the annotated resource" />
</Property>
<Property Name="SecuritySchemes" Type="Collection(Auth.SecurityScheme)">
<Annotation Term="Core.Description" String="At least one of the specified security schemes are required to make the request. This overrides any SecuritySchemes specified on the EntityContainer."/>
</Property>
<Property Name="HttpResponses" Type="Collection(Core.HttpResponse)">
<Annotation Term="Core.Description" String="Possible HTTP Responses returned by the request." />
</Property>
</ComplexType>
<ComplexType Name="HttpResponse">
<Property Name="ResponseCode" Type="Edm.String">
<Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Human-readable description of the response code." />
<Annotation Term="Core.IsLanguageDependent" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameter">
<Annotation Term="Core.Description" String="A custom parameter is either a header or a query option" />
<Annotation Term="Core.LongDescription" String="The type of a custom parameter is always a string. Restrictions on the parameter values can be expressed by annotating the record expression describing the parameter with terms from the Validation vocabulary, e.g. Validation.Pattern or Validation.AllowedValues." />
<Property Name="Name" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Name of the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Description of the custom parameter" />
</Property>
<Property Name="DocumentationURL" Type="Edm.String">
<Annotation Term="Core.IsURL" />
<Annotation Term="Core.Description" String="URL of related documentation" />
</Property>
<Property Name="Required" Type="Edm.Boolean" Nullable="false">
<Annotation Term="Core.Description" String="true: parameter is required, false or not specified: parameter is optional" />
</Property>
<Property Name="ExampleValues" Type="Collection(Capabilities.CustomParameterExampleValue)" Nullable="false">
<Annotation Term="Core.Description" String="Example values for the custom parameter" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameterExampleValue">
<Property Name="Value" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Example value for the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Description of the example value" />
</Property>
</ComplexType>
was:
<Term Name="HttpRequests" Type="Collection(Core.HttpRequest)" AppliesTo="EntitySet Singleton ActionImport FunctionImport Action Function">
<Annotation Term="Core.Description" String="Describes possible HTTP requests" />
<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 responses may increase readability." />
</Term>
<ComplexType Name="HttpRequest">
<Property Name="Method" Type="Edm.String">
<Annotation Term="Core.Description" String="Request verb of the HTTP request, e.g. GET, POST, PATCH, DELETE" />
</Property>
<Property Name="CustomQueryOptions" Type="Collection(Capabilities.CustomParameter)">
<Annotation Term="Core.Description" String="Custom query options that are supported/required for the annotated resource" />
</Property>
<Property Name="CustomHeaders" Type="Collection(Core.CustomParameter)">
<Annotation Term="Core.Description" String="Custom headers that are supported/required for the annotated resource" />
</Property>
<Property Name="HttpResponses" Type="Collection(Core.HttpResponse)">
<Annotation Term="Core.Description" String="Possible HTTP Responses returned by the request." />
</Property>
</ComplexType>
<ComplexType Name="HttpResponse">
<Property Name="ResponseCode" Type="Edm.String">
<Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Human-readable description of the response code." />
<Annotation Term="Core.IsLanguageDependent" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameter">
<Annotation Term="Core.Description" String="A custom parameter is either a header or a query option" />
<Annotation Term="Core.LongDescription" String="The type of a custom parameter is always a string. Restrictions on the parameter values can be expressed by annotating the record expression describing the parameter with terms from the Validation vocabulary, e.g. Validation.Pattern or Validation.AllowedValues." />
<Property Name="Name" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Name of the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Description of the custom parameter" />
</Property>
<Property Name="DocumentationURL" Type="Edm.String">
<Annotation Term="Core.IsURL" />
<Annotation Term="Core.Description" String="URL of related documentation" />
</Property>
<Property Name="Required" Type="Edm.Boolean" Nullable="false">
<Annotation Term="Core.Description" String="true: parameter is required, false or not specified: parameter is optional" />
</Property>
<Property Name="ExampleValues" Type="Collection(Capabilities.CustomParameterExampleValue)" Nullable="false">
<Annotation Term="Core.Description" String="Example values for the custom parameter" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameterExampleValue">
<Property Name="Value" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Example value for the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Description of the example value" />
</Property>
</ComplexType>
> Enable enumerating the valid requests and responses for a particular resource.
> ------------------------------------------------------------------------------
>
> 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.01_CS02, V4.0_ERRATA04
>
>
> 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)
