[OASIS Issue Tracker] (ODATA-1200) Support sample values for types, parameters, request/response bodies

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

Michael Pizzo created ODATA-1200:
------------------------------------

             Summary: Support sample values for types, parameters, request/response bodies
                 Key: ODATA-1200
                 URL: https://issues.oasis-open.org/browse/ODATA-1200
             Project: OASIS Open Data Protocol (OData) TC
          Issue Type: Sub-task
         Environment: ODATA-884 currently specifies a "CustomParameterExampleValue" for providing a sample value for a custom parameter within an HttpRequest annotation.

More generally, OpenAPI supports defining one or more sample values for each parameter and each (valid media type allowed for a) request or response payload (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#example-object), as well as a single example for each schema object (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#schema-object).

OpenAPI also supports the example value either being an (inline or referenced) Value, or an ExternalValue, where ExternalValue is an external reference to the literal value in a native (i.e., non-OpenAPI) format. This is done partially to support non-JSON media type values, but can also be useful for referencing external samples. We could support this by defining a base "Value" type and inherited "InlineValue" or "ExternalValue" types.

We could support this by allowing a new "ExampleValue" annotation on a type, parameter, or for a request or response body within an HttpRequest.

<Annotation Term="Example" Type="Core.ExampleValue" AppliesTo="EntityType,ComplexType,Parameter"/>

<ComplexType Name="ExampleValue" Abstract="true">
  <Property Name="Description" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Description of the example value" />
  </Property>
</ComplexType>

<ComplexType Name="InlineExampleValue" BaseType="ExampleValue">
  <Property Name="Value" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Example value for the custom parameter" />
  </Property>
</ComplexType>

<ComplexType Name="ExternalExampleValue" BaseType="ExampleValue">
  <Property Name="ExternalValue" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Url reference to the value in its literal format" />
  </Property>
</ComplexType>

And, within HttpRequest:
<Property Name="Example" Type="Core.ExampleValue"/>

And, within HttpResponse:
<Property Name="Example" Type="Core.ExampleValue"/>

1) OpenAPI supports the Description as CommonMark syntax (http://spec.commonmark.org/) for rich text representation. We could support this as well.
2) OpenAPI also includes a short "Summary"
3) OpenAPI supports multiple examples for request/response bodies and parameters, but not for schema objects (i.e., types).  It's unclear how you would relate individual request examples with individual response examples.
            Reporter: Michael Pizzo






--
This message was sent by Atlassian JIRA
(v7.7.2#77003)