To define an array in OpenAPI with exactly three items where two are enum values, you must use the
items keyword inside a
type: array definition. The structure requires specifying
minItems: 3 and
maxItems: 3 to enforce the length constraint. For the enum elements, you can either reference a shared
$ref or define inline
enum lists within a
oneOf or
anyOf construct depending on whether the enums share the same type or distinct schemas. This approach ensures strict validation of both the collection size and the specific allowed values for each position if necessary.
Understanding Array Constraints in OpenAPI
OpenAPI (formerly Swagger) provides robust tools for validating request and response bodies. When dealing with arrays, the primary keywords are
type,
items,
minItems, and
maxItems. To create an array that holds exactly three elements, you set both minimum and maximum item counts to 3. This prevents clients from sending arrays with fewer or more than the required number of items.
The challenge arises when you need specific elements within that array to be enums. In standard JSON Schema, which OpenAPI uses, the
items keyword applies a single schema to all elements in the array. This means every element must match the same type and constraints. If you need different enums for different positions, you cannot simply list them under a single
items object. Instead, you must use advanced schema composition techniques like
prefixItems (in Draft 2020-12) or
tuple validation logic.
For most common use cases involving simple enums, users often mean that the array contains items that are drawn from a set of enum values. If all three elements are of the same type but restricted to specific enum values, the solution is straightforward. You define the
items with an
enum list. However, if the requirement implies that the first two items must be from one enum and the third from another, or if they are distinct types, the schema becomes more complex. We will cover the most common scenario first: an array of identical enum types.
Defining a Simple Enum Array
If your goal is to have an array of three strings, where each string must be one of two possible values (e.g., "active" or "inactive"), you can define this directly. This is the simplest interpretation of "2 enums" if it means two possible values.
components:
schemas:
StatusArray:
type: array
minItems: 3
maxItems: 3
items:
type: string
enum:
- active
- inactive
In this example, the
items schema defines that every element in the array must be a string and must be either "active" or "inactive". The
minItems and
maxItems ensure the array has exactly three entries. This is valid OpenAPI 3.0 and 3.1 compliant syntax. It is clear, concise, and easy to understand for developers consuming the API.
If you are working with integer enums, the process is identical, just changing the
type to
integer. For instance, if you have status codes 1 and 2, you would list those integers in the
enum block. This method is ideal when the order of elements does not matter, and any combination of the allowed values is acceptable across the three slots.
Handling Distinct Enums per Position
Sometimes, "2 enums" might imply that the array contains items of different types or distinct enum sets at specific indices. For example, the first item might be a string enum, the second an integer enum, and the third a boolean. OpenAPI 3.0 does not natively support tuple validation in the same way JSON Schema Draft 2020-12 does with
prefixItems. However, you can simulate this using
allOf or by defining separate schemas for each position and combining them in a description, though true validation requires client-side checks or stricter server-side logic.
A more robust way to handle mixed types in OpenAPI 3.0 is to use a union type if supported by your validator, or to define a single object that contains these fields if the order is fixed. But if you strictly need an array, you might define the
items as
anyOf containing the different schemas. This allows any item to be any of the defined types, which is less strict than positional enforcement.
components:
schemas:
MixedArray:
type: array
minItems: 3
maxItems: 3
items:
anyOf:
- $ref: '#/components/schemas/StringEnum'
- $ref: '#/components/schemas/IntEnum'
This approach allows flexibility but sacrifices positional precision. If you need precise control over which enum goes where, consider restructuring your API to use an object with named properties instead of an array. Arrays are best for homogeneous data. If you must use an array, ensure your backend validation enforces the positional rules after parsing the JSON.
Common Pitfalls and Validation
When implementing these schemas, ensure your API gateway or validation library supports the specific version of OpenAPI you are using. Some older validators may not fully support
minItems and
maxItems together, or may mishandle
enum constraints. Always test your schema with a tool like Swagger Editor or OpenAPI Validator.
Another common issue is confusing
enum with
const. Use
enum when there are multiple allowed values. Use
const if the value is fixed for all items, which is rare in array contexts unless you are creating a constant-length array of identical constants.
For related technical challenges, such as managing access controls or debugging terminal issues, see
Remove Sharing Restriction: A Step-by-Step Guide and
TTY doesn't go up: Common tech support issues. These resources provide broader context on system configuration and troubleshooting.
Frequently Asked Questions
Can I use different enums for each index in an array?
OpenAPI 3.0 does not support positional validation for array items directly. You must use
anyOf or
oneOf in the
items schema, which allows any item to be any of the specified types. For strict positional validation, consider using an object with named fields instead of an array.
What happens if I send an array with only 2 items?
The API will reject the request with a 400 Bad Request error. The
minItems: 3 constraint ensures that the payload must contain at least three elements. The validation engine checks the array length before checking the item types.
How do I define an enum for integers?
Set the
type to
integer inside the
items schema and list the allowed integer values in the
enum array. For example,
enum: [1, 2] allows only the integers 1 and 2 as valid values for each item in the array.
Is it better to use an object or an array for fixed data?
An object is generally better for fixed data with distinct meanings per field, as it allows named properties. Arrays are suited for ordered collections of similar items. Using an array for distinct enums can lead to ambiguity and harder-to-maintain code.
Do I need OpenAPI 3.1 for prefixItems?
Yes,
prefixItems is a feature introduced in JSON Schema Draft 2020-12, which OpenAPI 3.1 adopts. OpenAPI 3.0 relies on older JSON Schema drafts that do not include
prefixItems, so you must use workarounds like
anyOf or restructure the data.