Schema Basics: Types, Formats and Constraints

Describing the shape of data

Schemas describe the structure of request and response payloads. OpenAPI 3.1 uses JSON Schema 2020-12 directly. Types: string, number, integer, boolean, object, array and null. Formats refine meaning and help validators and generators: date, date-time, email, uri, uuid, int32, int64, float, double, binary. Objects list properties and a required array (properties are optional unless listed); additionalProperties: false rejects unknown fields, which is strict but can hinder evolution of responses, so many teams use it on requests only. Constraints: minLength, maxLength, pattern for strings; minimum, maximum, exclusiveMinimum, multipleOf for numbers; minItems, maxItems, uniqueItems for arrays; enum and const for fixed values. readOnly properties (such as id, createdAt) appear in responses but not requests; writeOnly properties (such as password) appear in requests but never in responses. Add description and examples to properties, because schemas are the most-read part of API documentation.

A schema as a shape template

A schema states which fields exist, their types and the rules values must follow.

An order schema with constraints

Readable descriptions, formats, required fields and read-only properties.

components:
  schemas:
    Order:
      type: object
      required: [id, customerId, status, items, totalInr, createdAt]
      properties:
        id:
          type: string
          readOnly: true
          examples: [ord_7Fq2LmX0aB9c]
        customerId:
          type: string
        status:
          type: string
          enum: [PLACED, PAID, SHIPPED, CANCELLED]
        items:
          type: array
          minItems: 1
          maxItems: 50
          items: { $ref: '#/components/schemas/OrderItem' }
        totalInr:
          type: string
          pattern: '^\d+\.\d{2}$'
          description: Decimal amount as a string to avoid floating-point rounding
          examples: ['1499.00']
        couponCode:
          type: [string, 'null']        # 3.1 style nullable
          maxLength: 20
        createdAt:
          type: string
          format: date-time
          readOnly: true
    OrderItem:
      type: object
      required: [sku, quantity]
      properties:
        sku: { type: string, maxLength: 32 }
        quantity: { type: integer, minimum: 1, maximum: 99 }

Money as strings or minor units

JSON numbers are often parsed as binary floating point, so 0.1 + 0.2 issues appear in clients. Represent money as a decimal string ("1499.00") or as an integer in minor units (paise), and document the choice.

Quick check: Which keyword marks a property that appears in responses but should not be sent in requests?

• readOnly
• writeOnly
• required
• deprecated