OpenAPI Array of Objects

In OpenAPI, you can define arrays of objects in various ways using the type as array and the property items. You can define them inline or utilize referenced components.

Here is an example JSON with an array of User objects with id, firstname, lastname, and email properties. We’ll use it to demonstrate three ways to represent an array of objects in an  OpenAPI definition.

Inline Array of Objects

Defining your array of objects inline in OpenAPI involves directly defining an array of objects within the API specification without creating a separate component for the object schema.

When to Use

• Small and Simple Objects:  Use the inline approach when the object structure is small, simple, and doesn't need to be reused.
• Prototyping:  Useful for quick prototyping or when exploring the API design.
• Single Usage:  If the object is used only in a specific endpoint and isn't reused elsewhere in the API.

When to Avoid

• Complex Objects: Consider using referenced components for better organization and reusability for complex object structures.
• Reusability Needed:  If the same object schema is used in multiple places, consider creating a separate component for better maintainability.

Considerations for OpenAPI Tools:

• Code Generation: when generating code based on an OpenAPI definition, the inline approach can result in poorly named classes that negatively affect the developer experience. In larger API definitions, you may end up with generic or similar class names like status1, status2, and inlineResponse200.

Referenced Array of Objects

Referencing an array of objects in OpenAPI involves defining an object schema separately as a component and referencing that component within an array definition.

When to Use

• Reusability Needed: Use the referenced approach when the same object schema is used in multiple places throughout the API.
• Complex Objects: Ideal for complex object structures where maintaining a single definition is more manageable.
• Maintainability: Recommended for larger APIs where maintainability is a crucial factor.

When to Avoid

• Small and Simple Objects: The additional structure introduced by the referenced approach might be considered overkill for very simple object structures.
• Quick Prototyping: If you're in the early stages of prototyping and the object schema is subject to frequent changes, you might choose a more straightforward inline approach.

Considerations for OpenAPI Tools:

Code Generation: Most tools that generate code from OpenAPI specifications handle referenced components well with class names derived from component names, meaning you can follow proper naming conventions for more readable code.

Inline Array of Objects with Object Reference (Recommended)

The inline array of objects with object reference blends inline and referenced objects. The array is inline, but the items are defined as a referenced schema component.

When to Use or Avoid

• See the reasons for Reference Array of Objects as they are similar.

Considerations for OpenAPI Tools:

Generating code from an OpenAPI specification with an inline array of objects using object references, the resulting code typically represents the array as a native collection type in the target programming language. For example, generated Java code would use  List<User> to represent the array of User objects. This is more idiomatic and preferred by Java developers.

Alternatively, code generated where the array is a referenced schema object may generate a class with a getter and setter for the array. The code would function but be less idiomatic for Java developers.

Conclusion

These examples demonstrate three different ways to define arrays of objects in OpenAPI, both inline and with referenced components. Choose the approach that best fits your requirements and improves the readability and maintainability of your API documentation.

Looking to improve the quality of your OpenAPI definition? Try APIMatic's  VS Code extension with over 1200 validation and linting rules.