Can I Specify a Flexible Properties of Any Type on a Schema?

[jake-xie-sfdc]

Hi OpenAPI-Specification team,
We are on OpenAPI Specification 3.0.1. We have a highly customizable platform that allows users to create custom fields on a schema. For example, let's say we provide a schema called "Order" out of the box:

Order:
      type: object
      properties:
        id:
          type: integer
          format: int64
        shipDate:
          type: string
          format: date-time
        status:
          type: string
          description: Order Status
          enum:
          - placed
          - approved
          - delivered
        complete:
          type: boolean
          default: false
      xml:
        name: Order

Let's say the customer retrieve an OpenAPI specification (OAS) that contains the above schema. They generate a client library using the OAS and can use it in code to populate the field value like following:

order.setShipDate("10/29/2021");

Now let's say they add a new custom field call "quantity" to the order schema:

quantity:
  type: integer
  format: int32

But they don't regenerate client library using the updated OAS. , so they can't do order.setQuantity(2); in their code.

If possible, we would like to reduce the number of times that customers need to regenerate OAS and client library. We are thinking about defining a flexible field on the schema that can support any number of properties of any type. For example, something like

properties:
  anyPropertyName:
     type: anyType

And by doing so, we hope to enable following capability in client code:

order.setShipDate("10/29/2021");  // "ShipDate" is a property provided out of the box, so customers can directly do setShipDate
order.setField("quantity", 2);  // "quantity" is a customer-defined field, not a property provided out of the box, so customers need to use setField(fieldName, fieldValue) to populate the object
order.setField("shippingCity", "San Francisco");  // "shippingCity" is a customer-defined field, not a property provided out of the box, so customers need to use setField(fieldName, fieldValue) to populate the object

So, my question: Is there anything in OpenAPI specification 3.0.1 that allow us to specify a flexible property under schema that allow us to do object.setField(fieldName, fieldValue) ?

Thanks!

[webron]

Technically, starting OpenAPI 3.0 and up, all Schema Objects are open ended. That means that by default, all schemas allow for any additional properties with any types. This is coming from JSON Schema's additionalProperties property, which by default is set to true (see https://spec.openapis.org/oas/v3.0.3#properties).

The issue is with the code generator as they more commonly tend to treat schemas as close ended and not support additional properties, especially when it comes to strongly type languages. The code generator may have a configuration to support it. That's something you'd need to check with the code generator you're using, and if they don't support it, you'll need to file an issue with them.

[handrews]

Answered, closing.