Skip to content

OpenAPI Schemas — Reusable Data Models for Request and Response Bodies

DodaTech Updated 2026-06-28 2 min read

In this tutorial, you will learn about OpenAPI Schemas. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI schemas are reusable data type definitions stored in components/schemas that describe the structure, validation constraints, and format of API data.

What You'll Learn

  • Defining reusable schema components
  • JSON Schema data types and validation
  • Schema composition with allOf, oneOf, anyOf

Why It Matters

Reusable schemas keep your OpenAPI spec DRY and ensure consistent data structures across all endpoints.

Code Examples

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, editor, viewer]
          default: viewer
        createdAt:
          type: string
          format: date-time
          readOnly: true

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true

    PaginatedResponse:
      type: object
      required:
        - data
        - total
        - page
        - pageSize
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/User"
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer

    # Schema composition
    Animal:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer

    Dog:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
          properties:
            breed:
              type: string

    Cat:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
          properties:
            indoor:
              type: boolean

# Validating data against OpenAPI schemas
from jsonschema import validate, ValidationError

user_schema = spec['components']['schemas']['User']
user_data = {"id": 1, "name": "Alice", "email": "alice@example.com"}

try:
    validate(user_data, user_schema)
    print("Valid user data")
except ValidationError as e:
    print(f"Validation error: {e.message}")

Common Mistakes

1. Not Breaking Down Complex Schemas

Large schemas are hard to maintain. Use $ref to compose smaller schemas.

2. Missing Read-Only Fields

Mark server-generated fields (id, createdAt) as readOnly: true.

3. No Enum Constraints

Use enums to restrict string fields to valid values.

4. Ignoring Nullable Fields

If a field can be null, add nullable: true.

5. Not Using Descriptions

Every schema and property should have a description explaining its purpose.

Practice Questions

  1. Where are reusable schemas stored in OpenAPI?
  2. How do you mark a field as read-only?
  3. What does allOf do in schema composition?
  4. How do you reference a schema from another component?
  5. What JSON Schema types are available?

Answers:

  1. In components/schemas.
  2. Set readOnly: true on the property.
  3. It combines multiple schemas into one (inheritance-like).
  4. Use $ref: "#/components/schemas/SchemaName".
  5. string, number, integer, boolean, array, object.

Challenge: Design a schema hierarchy for an e-commerce API with Product, Order, LineItem, Customer, and Address schemas. Use composition where appropriate.

FAQ

Can schemas reference other schemas?

: Yes, using $ref to reference any schema in the components section.

What is the difference between allOf and oneOf?

: allOf requires all schemas to match; oneOf requires exactly one to match.

Can I use external JSON Schema files?

: Yes, with relative $ref paths to external files.

← Previous OpenAPI Responses — Defining Success and Error Response Structures Next → OpenAPI Security — Defining Authentication and Authorization

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation