Making representations a first class concept to address a number of structural concerns

This is a proposal to address a number of the issues aggregated under #560. Specifically:

• Having multiple schemas for requests and responses #270
• It removes the produces/consumes ambiguity described here #581
• It extends on @jasonh-n-austin 's addition of the RequestBody object #670
• It avoids some of the issues around formData by making it obsolete #222

The basic premise is that OpenAPI models operations that interact with resources using a specific HTTP method. The interaction involves sending representations and retrieving those representations. A single operation may support different representations identified by a media-type.

Consider the following GET operation that returns one of two representations.

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      representations: 
         application/json:
            schema:
              type: array
              items:
                $ref: '#/definitions/Pet'
         text/html:
    default:
      description: error payload
      representations: 
        application/json:
          schema:
            $ref: '#/definitions/ErrorModel'
        text/html:
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  type: array
  items:
    type: string
  collectionFormat: csv

The description and headers properties of a response object stay, but the schema and examples move under the representation object that is defined as a property of the representations object. The examples property will need to change to either an array of objects, or a single object because all examples would be for the same media type.

By defining the supported media types on the representations object, there is no longer a need for a produces array.

It is important to note that different representations should not be semantically different when accompanied with the same class of status code. A request to a resource should always the same thing (for some unfortunately nebulous definition of thing). However, the syntax of that representation may be different and the amount of information contained may be different, but from a consumer’s perspective. it is same concept, regardless of the representation. This is why the description property is the same for all representations.

The following is an example of a POST request that may send a HTML form as a request body.

tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  type: string
requestbody:
  description: Updated status of the pet
  required: false
  representations:
    application/x-www-form-urlencoded:
      schema: 
        properties:
          name: 
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
        required: 
          - status
responses:
  '200':
    description: Pet updated.
    representations: 
      application/json:        
      application/xml:
  '405':
    description: Invalid input
    representations:
      application/json:        
      application/xml:    
security:
- petstore_auth:
  - write:pets
  - read:pets

The structure of the HTML form that is passed as a body are no longer intermixed with the URI parameters and are described by a schema object in the representation object. This enables us to support all the different form related media types. There would no longer be any need for the formData parameter type and no need for the consumes array.

One open question is whether there is a value to allowing representation objects (media type, schema and examples) to be defined within the reusable components section.

[ralfhandl]

In #333 a schemaType or schemaLanguage property was proposed to describe the type/language used in the schema property. The default/fallback could be the OpenAPI subset of JSON Schema.

That way tools can skip schemas whose language they can’t cope with.

[fehguy]

representing the schema for non-JSON structures is something we’ll tackle outside of this PR. but I do think that this fixes the association between the content format and consumes and produces, by coupling them together. So +1 to this.