Enum/oneOf of object type in request body property

[mheh]

Question

Trying to achieve

I'm having an issue trying to understand correct syntax or if it's possible to use the oneOf declaration within a property of a requestBody. My main goal would be in this codebase having a POST request that accepts input on a property 'cost' of oneOf the available objects. The resulting code would allow me to do something like this in a Vapor server

guard case .json(let body) = input.body else { throw Abort(.badRequest) }
switch body.cost {
case .productCostId(let costRequest):
  // guard let foundCost = try await ProductCost.find(costRequest.id, on: req.db) else {
  // throw Abort(.notFound)
  // }
case .manualCostAmount(let manualCostAmount):
  // let myCost = try make decimal from string
}

What have I tried

I'm looking at this code right now for the entirety of the request, however I've gone through iterations of moving the type: object to the enum cases, to the property itself. Using schema: or oneOf: or enum: in various fashion. I also tried comparing what I was doing to the parameters usage of the request. The section I'm having difficulty with is the final property: cost

post:
  operationId: inventoryProductItemCreate
  summary: Create a new inventory product item
  tags:
    - Inventory
  requestBody:
    description: Inventory product item object to be created
    required: true
    content:
      application/json:
        schema:
          required:
            - productId
            - boxId
            - cost
          properties:
            productId:
              type: integer
              description: User defined name of the inventory location
            boxId:
              type: integer
              description: The ID of the box where the product item is created at
            cost:
              description: The cost of the product item
              enum:
                - name: productCostId
                  schema:
                    type: object
                    required:
                      - productCostId
                    properties:
                      productCostId:
                        type: integer
                        description: The ID of a product cost to use for the product item. If specified the manual cost amount is ignored.
                - name: manualCostAmount
                  schema:
                    type: object
                    required:
                      - manualCostAmount:
                    properties:
                      manualCostAmount:
                        type: string
                        description: A manual cost amount to enter for the product item

What didn't work as expected

I believe this is just a syntax issue but felt like it was a bit obscure in comparison to the enum types where single instances look like:

type: string
- UK
- US

The result is an empty ValueContainer or Object that I can't use.

[czechboy0]

Hi @mheh,

I believe a slight change in your OpenAPI doc should get you what you need:

openapi: 3.1.0
info:
  title: Product service
  version: 1.0.0
paths:
  /inventory/productItem:
    post:
      operationId: inventoryProductItemCreate
      summary: Create a new inventory product item
      tags:
        - Inventory
      requestBody:
        description: Inventory product item object to be created
        required: true
        content:
          application/json:
            schema:
              required:
                - productId
                - boxId
                - cost
              properties:
                productId:
                  type: integer
                  description: User defined name of the inventory location
                boxId:
                  type: integer
                  description: The ID of the box where the product item is created at
                cost:
                  description: The cost of the product item
                  oneOf:
                    - $ref: '#/components/schemas/ProductCostId'
                    - $ref: '#/components/schemas/ManualCostAmount'
components:
  schemas:
    ProductCostId:
      type: object
      required:
        - productCostId
      properties:
        productCostId:
          type: integer
          description: The ID of a product cost to use for the product item. If specified the manual cost amount is ignored.
    ManualCostAmount:
      type: object
      required:
        - manualCostAmount
      properties:
        manualCostAmount:
          type: string
          description: A manual cost amount to enter for the product item

It uses oneOf, which is how you get enums with associated values in Swift. The enum feature in OpenAPI only results in String/Int-backed raw enums in Swift.

While not necessary above, because each of the cases of your oneOf has some unique required properties, you could make this even more explicit by adding a discriminator to the oneOf cases, which will make the decoding more efficient, as it won't have to iterate through all the possible schemas and try to decode them until one works. Instead, the discriminator gets decoded first and it looks up the schema to decode the full payload as. It does require a bit more syntax, though, so pick whichever works better for you.

Here's the variant with a discriminator:

openapi: 3.1.0
info:
  title: Product service
  version: 1.0.0
paths:
  /inventory/productItem:
    post:
      operationId: inventoryProductItemCreate
      summary: Create a new inventory product item
      tags:
        - Inventory
      requestBody:
        description: Inventory product item object to be created
        required: true
        content:
          application/json:
            schema:
              required:
                - productId
                - boxId
                - cost
              properties:
                productId:
                  type: integer
                  description: User defined name of the inventory location
                boxId:
                  type: integer
                  description: The ID of the box where the product item is created at
                cost:
                  description: The cost of the product item
                  oneOf:
                    - $ref: '#/components/schemas/ProductCostId'
                    - $ref: '#/components/schemas/ManualCostAmount'
                  discriminator:
                    propertyName: costType
components:
  schemas:
    CommonCostProperties:
      type: object
      properties:
        costType:
          type: string
          enum:
            - ProductCostId
            - ManualCostAmount
      required:
        - costType
    ProductCostProperties:
      type: object
      required:
        - productCostId
      properties:
        productCostId:
          type: integer
          description: The ID of a product cost to use for the product item. If specified the manual cost amount is ignored.
    ProductCostId:
      allOf:
        - $ref: '#/components/schemas/CommonCostProperties'
        - $ref: '#/components/schemas/ProductCostProperties'
    ManualCostProperties:
      type: object
      required:
        - manualCostAmount
      properties:
        manualCostAmount:
          type: string
          description: A manual cost amount to enter for the product item
    ManualCostAmount:
      allOf:
        - $ref: '#/components/schemas/CommonCostProperties'
        - $ref: '#/components/schemas/ManualCostProperties'

Hope this helps!

[mheh]

That worked perfectly and is very nice to use. Thanks!

I'm still a bit confused why the first example of the cost property with oneOf using $ref works at the root of that property. I feel like I tried that but without $ref. Is there a reason with $ref that works? Is it because schema definitions include a schema name? Can I achieve single use object definitions in a oneOf instance and have the generator make the enum types for me (discriminator or not).

Thank you again, that should keep me going for a while :D

[czechboy0]

Yes it works with inline types too, the enum case name just will be slightly uglier.