APIGit
Native Git RepositoryVersioned, Git-native API repositoryAPI DesignOpenAPI, AsyncAPI and GraphQL editingAPI DocumentationPublish versioned docs from GitAPI GovernanceCheck OpenAPI and AsyncAPI standardsMock ServerFrom OpenAPI, GraphQL or Express.js codeTeam CollaborationOrganizations, teams, permissions and reviewsAI AgentsMCP server, llms.txt and Copy page for agentsCLILocal-first: lint, mock and publish from a terminal

Your API and docs are a Git repository

Specs and Markdown guides in one repository, reviewed like code and published as a docs site, mocks and agent-ready endpoints from any commit.

Start for freeView pricing

Learning

DocumentationGetting StartedVideo TutorialsBlog

Support

Contact UsRequest a DemoReport an Issue
DocsPricingAbout
Sign inStart for free
APIGit

The Git-native, local-first API platform, ready for AI agents.

Product

  • Git repository
  • API design
  • API documentation
  • API governance
  • Mock server
  • Team collaboration
  • AI agents
  • CLI

Resources

  • Documentation
  • Get started
  • CLI reference
  • MCP server
  • Blog
  • Video tutorials
  • Pricing

Company

  • About
  • Careers
  • Contact
  • Privacy policy
  • Terms of service
  • Service level agreement
  • Cookie policy

© 2026 APIGit. All rights reserved.

Blog/API Design

An introduction to oneOf, allOf and anyOf in OpenAPI

Mar 15, 20244 min readAPIGit Team

When designing or documenting an API with OpenAPI Specification (OAS), you'll often encounter the need to describe complex data structures. These structures might require the definition of various scenarios, such as different object structures for different conditions, a combination of multiple objects into one, or specifying that an object could match any one of several types. This is where oneOf, allOf, and anyOf shine, offering the flexibility and precision needed for these tasks.

Understanding allOf

allOf is used to combine multiple schemas into a single schema that includes all properties from the combined schemas. It's particularly useful when you want to create a complex schema that inherits properties from several other schemas.

For example, if you have a Person schema with common properties like name and age, and a Student schema that should include all properties of Person plus a studentId, you can use allOf to create the Student schema without repeating the Person properties.

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            studentId:
              type: string

Exploring oneOf

oneOf specifies that the data should match exactly one of the referenced schemas. It's useful for defining different possible structures for a data object, where only one structure is valid for any given instance.

Consider an API endpoint that accepts a payment method, which could be either a credit card or a bank account, but not both. Using oneOf, you can define these options clearly:

components:
  schemas:
    CreditCard:
      type: object
      properties:
        number:
          type: string
        expiryDate:
          type: string
        cvv:
          type: string
    BankAccount:
      type: object
      properties:
        accountNumber:
          type: string
        routingNumber:
          type: string
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CreditCard'
        - $ref: '#/components/schemas/BankAccount'

Deciphering anyOf

anyOf allows the data to match any (one or more) of the referenced schemas. It provides flexibility when the data could be in several forms, and there's no need for exclusivity as with oneOf.

For instance, if an API endpoint accepts a contact object that could be either a phone number, an email address, or both, you can use anyOf to represent this:

components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        phone:
          type: string
    EmailAddress:
      type: object
      properties:
        email:
          type: string
    Contact:
      anyOf:
        - $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/schemas/EmailAddress'

Conclusion

The allOf, oneOf, and anyOf keywords add essential versatility to OpenAPI specifications, enabling the definition of complex and nuanced data models. By understanding and using these tools effectively, API designers and documenters can create more accurate and flexible API specifications. Whether you're inheriting properties, specifying exclusive types, or allowing multiple structures, these keywords ensure your API's data contracts are clear and robust.

More posts

  • Nov 13, 2026AsyncAPI governance, GraphQL mocks and agent pages are liveAPI Design
  • Nov 13, 2026AsyncAPI and GraphQL join OpenAPI in APIGitAPI Design
  • Jul 25, 2023From Swagger to OpenAPI: Editing and trying APIs in APIGitAPI Design
All posts

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Start for free Book a demo

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish