Proposal: add serverDefault and clientDefault keys to model spec

[spacether]

Proposal:

• add serverDefault and clientDefault keys to openapi 3.X model spec
• default becomes serverDefault
• example/examples becomes clientExample, clientExamples

Reasons

• Developer Confusion
  The current keys of default and example are ambiguous in their naming which creates developer confusion.
  People think that default values are defaults that the client will send to the server.
• Spec Ambiguity
  The swagger 2.0 spec did not scope the default value to either the server or the client.
  The openapi 3.0 spec limits the scope of the default to server side, when the parameter is omitted by the client.
  Examples are not defined relative to a client or server reference. Implicitly, should we assume a client reference?
• Spec Lacks Client Default
  In openapi 3.0 examples are not described as the client default, they are just samples.
  We are missing a location for a client default.
• Some use cases require client defaults
  • an xml/json payload with a constant key/value pair. Though this is not the best design pattern, some apis do require this.
  • headers that must always have a constant value

General note about usage.
Per https://github.com/swagger-api/swagger-codegen
Number of Clients: 38
Number of Server Stubs: 14
So we have a significant number of clients which are using this spec, where client defaults are not defined. By the numbers it looks like the client codegen is used more than the server stubs, though this could just be indicative of there being more client languages vs server languages in use generally.

Example of Developer Confusion:

• Stack Overflow Question
  https://stackoverflow.com/questions/45852383/can-a-swagger-object-passed-as-a-parameter-have-default-values-in-swagger-ui
• Python client assumes getDefault() returns the client defaults
  https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PythonClientCodegen.java
• Swagger.io site https://swagger.io/docs/specification/2-0/adding-examples/
  Do not confuse example values with the default values. An example is used to illustrate what the value is supposed to be like. A default value is something that the server uses if the value is not provided in the request.

[spacether]

Or is the below solution below better?

It seems like there are 2 kinds of defaults:

• server-side: variable is not required and server will assume a value for it if it is not given definition from OpenApi v3.0 spec
• client side: variable is required and must be only one value (for example headers)

For a client-side default, we can define it by setting required=True and enum to the only allowed value. See this example below:

swagger: "2.0"
info:
  title: "some api"
  description: "a description"
  version: "1.0.0"
host: "example.com"
basePath: "/api"
schemes:
- "http"
paths:
  /myobject:
     post:
      summary: |
        post an object.
      parameters:
        - name: myObject
          in: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/MyObject'
      responses:
        200:
          description: OK
definitions:
  MyObject:
      type: object
      description: Contains default properties
      required:
        - cats
        - dogs
      properties:
        cats:
          type: number
          enum:
            - 9
        dogs:
          type: string
          enum:
            - fido

And you can see it work in the swagger-editor here: https://editor.swagger.io/

The default parameter is a bit confusing because swagger 2.0 initially described the default parameter without specifying a server or client reference frame.

Swagger 2.0 spec
Defines schema default as

default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)

OpenAPI v3.0 spec

default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.

[MikeRalphson]

Isn't default a confusing name to use for something which can only have one value? As above, a one element enum handles this today.

[spacether]

One element enum is the solution that I will use.