OpenApi v3: additionalProperties false with referenced schemas

ONLINECAST

2 min read

·

06-10-2024

9

0

Share

Understanding OpenAPI v3: additionalProperties: false and Referenced Schemas

When defining complex data structures in your OpenAPI v3 specification, you might encounter the additionalProperties: false property. This property, often used in conjunction with referenced schemas, can significantly impact the structure and validation of your API. Let's explore how these concepts work together to ensure a robust and predictable API.

The Scenario: Defining a Complex Data Structure

Imagine you're designing an API for managing user profiles. Each profile has a set of core properties like name, email, and age. Additionally, each user can have a custom set of profile fields depending on their role.

Original Code (Without additionalProperties):

components:
  schemas:
    UserProfile:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        age:
          type: integer
        customFields:
          type: object

In this example, customFields is defined as a generic object, allowing users to include any arbitrary properties. However, this lacks validation and control over the structure of custom fields, potentially leading to unexpected data formats.

The Solution: additionalProperties: false and Referenced Schemas

To enforce structure and validate custom fields, we can leverage additionalProperties: false and referenced schemas.

Improved Code:

components:
  schemas:
    UserProfile:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        age:
          type: integer
        customFields:
          type: object
          additionalProperties: false
          properties:
            # Define specific properties for custom fields
            # Example: 
            role:
              type: string
            location:
              type: string
    CustomField:
      type: object
      properties:
        key:
          type: string
        value:
          type: string

Explanation:

1. additionalProperties: false: This directive explicitly forbids any properties within customFields that are not explicitly defined in the properties section.
2. Referenced Schema (CustomField): We define a separate schema (CustomField) to represent the structure of each custom field. This allows you to define specific types and validation rules for each custom field.

Benefits of this Approach

• Validation: By using additionalProperties: false and referenced schemas, your API will strictly enforce the expected structure of custom fields, preventing unexpected data formats and ensuring data consistency.
• Clarity: This approach clearly documents the expected structure of custom fields, making your API specification easier to understand and maintain.
• Flexibility: You can easily extend the CustomField schema to accommodate new custom field types or validation rules, allowing your API to evolve without breaking existing functionality.

Additional Considerations

• Default Value: You can set additionalProperties to an empty object ({}) to allow additional properties, but they will not be validated against any schema.
• Tooling Support: Many OpenAPI tools and code generators support these features, enabling you to generate code and documentation that automatically enforces these validation rules.

Conclusion

Using additionalProperties: false in conjunction with referenced schemas allows you to design APIs with well-defined data structures, even when dealing with complex and flexible custom fields. This approach enhances API security, predictability, and maintainability, leading to a more reliable and robust API experience.