How to define an OpenAPI ordered array of different objects?

Question

I am trying to define my API using OpenAPI version 3.0. I am trying to generate a YAML file which has four maps, and each map contains a different information. How can I create a YAML file to achieve that goal? I know that my components are not right because of which I am not getting the right result.

Request body should be like this:

[
  UserInformation{FirstName, LastName},
  AddressInformation{Phone, Address},
  ContactInformation{Email, Phone}
]

openapi: 3.0.0
info:
  version: 1.0.0
  title: 'INPUT-FORM-API'

paths:
  /api/v1/test/healthcheck:
    get:
      summary: Health check for the test api services. Used Internally
      operationId: Externalhealthcheck
      description: healthcheck for the test services status.
      responses:
        '200':
          description: This status is always returned when service is Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthcheckObject'

  /api/v1/test/newformentry:
    post:
      summary: End Point to insert data into the new table.
      operationId: NewFormEntry
      description: EndPoint to insert data for new form.
      requestBody:
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NewFormEntry'
      responses:
        '200':
          description: This status is always returned when service is Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthcheckObject'

components:
  schemas:
    NewFormEntry:
        $ref: '#/components/schemas/UserInformation'
        $ref: '#/components/schemas/AddressInformation'
        $ref: '#/components/schemas/ContactInformation'
        $ref: '#/components/schemas/MessageFromBene'
    UserInformation:
      required:
        - FirstName
        - LastName
      properties:
        FirstName:
          type: string
        LastName:
          type: string
          
    AddressInformation:
      required:
        - StreetAddress
        - City
        - State
        - ZipCode
      properties:
        StreetAddress:
          type: string
        StreetAddress2:
          type: string
        City:
          type: string
        State:
          type: string  
        ZipCode:
          type: integer
          format: int64
          
    ContactInformation:
      required:
        - PhoneNumber
        - Email
      properties:
        PhoneNumber:
          type: integer
          format: int64
          maximum: 9
        Email:
          type: string
        HomePhone:
          type: integer
          format: int64
          maximum: 9
        Cell:
          type: integer
          format: int64
          maximum: 9
        WorkPhone:
          type: integer
          format: int64
          maximum: 9
    
    MessageFromBene:
      required:
        - Message
      properties:
        PhoneNumber:
          type: integer
          format: int64
          maximum: 9
        Message:
          type: string
    
    HealthcheckObject:
      required:
        - Status
        - ErrorMessage
      properties:
        Status:
          type: string
        ErrorMessage:
          type: string

`NewFormEntry` definition is incorrect. What is that object supposed to be? E.g. a merger of `UserInformation`, `AddressInformation` and other objects into one; or _one_ of these objects; or something else? — Helen, Aug 20 '21 at 17:28
It should be an array of these objects. Request should be [ {First Name, Last Name}, {Phone Number, Address, Email}] @Helen — Will789, Aug 20 '21 at 18:10

Helen · Answer 1 · 2021-09-08T21:48:47.427

So the NewFormEntry schema must be an array containing 3 objects, where the 1st object must be UserInformation, the second object must be AddressInformation, and the 3rd object mube be ContactInformation. This is like a tuple, i.e. an ordered sequence of elements where each element has a specfic type. Tuple definitions are slightly different in different OpenAPI versions.

OpenAPI 3.1

If or when you migrate to OAS 3.1, such an array can be defined using prefixItems. This keyword specifies the schema for each element position (in other words, it specifies the order of elements in the array):

components:
  schemas:
    NewFormEntry:
      type: array
      prefixItems:
        - $ref: '#/components/schemas/UserInformation'    # type of the 1st element
        - $ref: '#/components/schemas/AddressInformation' # type of the 2nd element
        - $ref: '#/components/schemas/ContactInformation' # type of the 3rd element
      minItems: 3
      maxItems: 3
      additionalItems: false   # can be omitted if `maxItems: 3` is specified

OpenAPI 3.0

In OAS 3.0, you can define the array length (i.e. 3 items) and the possible types of array items (i.e. each item can be either A, B, or C), but there's no way to define a specific order of objects in the array. So the most you can do is this:

components:
  schemas:
    NewFormEntry:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/UserInformation'
          - $ref: '#/components/schemas/AddressInformation'
          - $ref: '#/components/schemas/ContactInformation'
      minItems: 3
      maxItems: 3

Note that this definition allows arbitrary order of objects in the array and also multiple instances of the same object (e.g. [UserInformation, UserInformation, UserInformation]). You might want to implement additional backend validations to verify the desired order of objects in this array.

How to define an OpenAPI ordered array of different objects?

1 Answers1

OpenAPI 3.1

OpenAPI 3.0