# Schema Basics: Types, Formats and Constraints — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/s-basics

> Model data with JSON Schema types, formats, required properties and validation keywords.

## 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.

![A form outline with labelled slots of different shapes, and a few sample values sliding into matching slots.](assets/figures/openapi/section-3-map.svg) — Figure 3.1 — Types, required fields and constraints in a schema.

## An order schema with constraints

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

```yaml
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.

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

- [x] readOnly
- [ ] writeOnly
- [ ] required
- [ ] deprecated

*Answer:* readOnly. readOnly properties such as server-generated ids belong only in responses.