• Type: Sub-task
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: CN01
    • Fix Version/s: CN02
    • Component/s: Vocabularies
    • Labels:
    • 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 (, as well as a single example for each 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.

      <Term Name="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" />
      <ComplexType Name="PrimitiveExampleValue" BaseType="ExampleValue">
       <Property Name="Value" Type="Edm.PrimitiveType" Nullable="false">
       <Annotation Term="Core.Description" String="Example value for the custom parameter" />
      <ComplexType Name="ComplexExampleValue" BaseType="ExampleValue">
       <Property Name="Value" Type="Edm.ComplexType" Nullable="false">
       <Annotation Term="Core.Description" String="Example value for the custom parameter" />
      <ComplexType Name="EntityExampleValue" BaseType="ExampleValue">
       <Property Name="Value" Type="Edm.EntityType" Nullable="false">
       <Annotation Term="Core.Description" String="Example value for the custom parameter" />
      <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" />

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

      1) OpenAPI supports the Description as CommonMark syntax ( 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.




            • Assignee:
              handl Ralf Handl
              mikep Michael Pizzo
            • Watchers:
              1 Start watching this issue


              • Created: