JSON Schema Annotations: title, description, examples, default

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

JSON Schema annotations are keywords that carry metadata about a schema or property without influencing whether data passes validation. They exist to communicate intent — to developers reading raw JSON Schema files, to documentation generators like Swagger UI and Redoc, to form builders that auto-generate UI, and to SDK generators that produce client code. Getting annotations right pays dividends across every tool in the API lifecycle.

This guide covers every annotation keyword in detail: title and description for documentation, default for default values and how Ajv handles them, examples for showing valid inputs, readOnly and writeOnly for access control semantics, deprecated for migration signaling, and how OpenAPI 3.1 consumes all of these.

title and description Keywords

title provides a short human-readable label for a schema or property. description provides a longer explanation — purpose, constraints, edge cases, and usage notes. Both are string values and both are pure annotations: removing them has no effect on validation.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "description": "A registered user account. Email is the login identifier.",
  "type": "object",
  "properties": {
    "id": {
      "title": "User ID",
      "description": "UUID v4 assigned by the server on account creation.",
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "email": {
      "title": "Email Address",
      "description": "Primary login email. Must be unique across all accounts.",
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "displayName": {
      "title": "Display Name",
      "description": "Publicly visible name shown in the UI. 2–50 characters.",
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    }
  },
  "required": ["email", "displayName"]
}

Swagger UI and Redoc use title as the field label in rendered documentation. When title is absent, tools fall back to the property key name. The description appears as help text or a tooltip. Writing good descriptions pays forward — a well-annotated schema makes generated documentation indistinguishable from hand-written API docs.

Both keywords apply at every level of the schema: the root object, individual properties, array items, and $defs entries. Annotating $defs entries is especially valuable because those definitions are reused across multiple endpoints, and the description travels with every $ref that references them.

default: Specifying Default Values

The default keyword declares what value should be assumed when the property is absent from the data. It is an annotation — a JSON Schema validator does not fail data that omits a property with a default, nor does it automatically write the default into the data object. The value is informational only, unless you explicitly configure the validator to apply it.

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"],
      "default": "viewer",
      "description": "Access role. Defaults to read-only viewer if not specified."
    },
    "active": {
      "type": "boolean",
      "default": true
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  }
}

To actually populate defaults during Ajv validation, pass { useDefaults: true } to the Ajv constructor. Ajv then writes the default value into the data object for any missing property — mutating the input in place:

import Ajv from 'ajv'

const ajv = new Ajv({ useDefaults: true })

const schema = {
  type: 'object',
  properties: {
    role:     { type: 'string', default: 'viewer' },
    active:   { type: 'boolean', default: true },
    pageSize: { type: 'integer', default: 20 },
  },
}

const validate = ajv.compile(schema)

const data = { role: 'editor' }  // active and pageSize are absent

validate(data)

console.log(data)
// { role: 'editor', active: true, pageSize: 20 }
// Ajv wrote the defaults into the object

Important caveats with useDefaults: it only applies defaults for missing object properties, not missing array items. It mutates the original object, so clone your input first if you need to preserve it. Defaults are applied depth-first — nested object defaults are filled before the parent is validated. If a property is present but set to null, Ajv does not replace it with the default.

examples: Showing Valid Values

The examples keyword (introduced in Draft-07) holds an array of values that are valid against the schema. It is distinct from default: a default is what the system uses when the field is absent; examples are illustrative inputs for documentation. All example values should be valid against the schema they annotate, though validators do not verify this.

{
  "type": "object",
  "title": "Create Order Request",
  "properties": {
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "ISO 4217 currency code.",
      "examples": ["USD", "EUR", "GBP", "JPY"]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku":      { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        },
        "required": ["sku", "quantity"]
      },
      "examples": [
        [{ "sku": "WIDGET-001", "quantity": 2 }],
        [{ "sku": "WIDGET-001", "quantity": 1 }, { "sku": "GADGET-007", "quantity": 3 }]
      ]
    }
  },
  "required": ["currency", "items"],
  "examples": [
    {
      "currency": "USD",
      "items": [{ "sku": "WIDGET-001", "quantity": 2 }]
    }
  ]
}

Note that examples at the root of the schema shows a complete valid request body, while examples on individual properties shows valid values for that field. Swagger UI renders the first entry from examples as the default example in the Try-it-out form.

OpenAPI 2.0 and 3.0 use example (singular string, not an array) on the Schema Object — this is a Swagger extension that predates JSON Schema's examplesarray. In OpenAPI 3.1 (aligned with JSON Schema Draft 2020-12), examples (the JSON Schema array) is preferred. When migrating from OpenAPI 3.0 to 3.1, replace example: "USD" with examples: ["USD"].

readOnly and writeOnly

readOnly: true marks a property that is returned by the server but must not be sent by the client. writeOnly: true marks a property that can be sent by the client but is never returned by the server. Both are boolean annotations — validators do not enforce them at validation time.

{
  "title": "User",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true,
      "description": "Server-assigned unique identifier. Do not include in POST/PUT requests."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Account creation timestamp. Set by the server."
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 12,
      "writeOnly": true,
      "description": "Account password. Accepted in registration and password-change requests. Never returned."
    },
    "displayName": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    }
  },
  "required": ["email", "displayName"]
}

The practical effect of these annotations depends entirely on the tooling consuming the schema. OpenAPI generators use them as follows: readOnly properties are excluded from generated request body schemas and pre-filled request examples. writeOnly properties are excluded from generated response schemas and response examples. SDK generators like openapi-typescript and openapi-generator mark readOnly properties as readonly in TypeScript interfaces and read-only in Java/C# classes.

If you want a validator to actually reject a readOnly field in a request body, you need to use a different schema for requests vs responses — or write a custom keyword. A common pattern in OpenAPI is to define two schemas: a UserInput schema (no id, no createdAt) for request bodies, and a UserResponse schema (all fields) for response bodies.

deprecated Keyword

deprecated: true signals that a property or schema is obsolete and should no longer be used, even though it is still present for backward compatibility. This keyword was introduced in Draft 2019-09. Like all annotations, it has no effect on validation.

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated since v2. Use 'email' as the login identifier instead.",
      "x-deprecatedSince": "2025-01-01",
      "x-replacement": "email"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Primary login identifier as of v2."
    },
    "phone": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated. Use the separate /phone-verify endpoint to manage phone numbers."
    }
  }
}

Swagger UI renders deprecated fields with a strike-through style. Code generators emit deprecation warnings or @Deprecated / @deprecated annotations in the generated code. The deprecated keyword is most useful when you annotate $defs entries — tools that dereference $ref will see the deprecation annotation wherever the definition is used.

Best practice: combine deprecated: true with a description that explains what to use instead and, optionally, a custom extension field (prefixed with x-) such as x-deprecatedSince or x-replacement. JSON Schema ignores unknown keywords unless you're in Ajv strict mode, so custom extensions are safe in Draft 2019-09+ schemas.

Annotations in OpenAPI 3.1

OpenAPI 3.1 is the first version fully aligned with JSON Schema (Draft 2020-12). All JSON Schema annotation keywords are first-class citizens and are consumed by the entire OpenAPI toolchain.

# openapi: 3.1.0 — Schema Object with full annotation support
components:
  schemas:
    Product:
      title: Product
      description: |
        A catalog product. Prices are in the currency specified at the account level.
        Inventory is updated asynchronously and may lag by up to 60 seconds.
      type: object
      properties:
        id:
          title: Product ID
          type: string
          format: uuid
          readOnly: true
          examples:
            - "550e8400-e29b-41d4-a716-446655440000"
        name:
          title: Product Name
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - "Wireless Ergonomic Mouse"
            - "USB-C Hub 7-in-1"
        price:
          title: Price (USD cents)
          type: integer
          minimum: 0
          description: Price in the smallest currency unit (cents for USD).
          default: 0
          examples:
            - 2999
            - 14999
        sku:
          title: SKU
          type: string
          pattern: "^[A-Z]{3}-[0-9]{6}$"
          deprecated: true
          description: "Deprecated in v3. Use 'productCode' instead."
          examples:
            - "WID-001234"
        productCode:
          title: Product Code
          type: string
          description: "Replaces 'sku' as of API v3. Format: CATEGORY-XXXXXX."
          examples:
            - "MOUSE-001234"
      required:
        - name
        - price

In OpenAPI 3.1, examples on a Schema Object is the JSON Schema array (as shown above). The OpenAPI-specific examples map (in the Media Type Object) is a separate construct for providing named, full request/response body examples — these are different and serve different purposes. The schema-level examples provides per-field illustration; the media-type-level examples provide complete payload examples for the Try-it-out interface.

Collecting Annotations with Ajv

Ajv does not collect or report annotation values by default. Its primary purpose is validation — determining pass or fail — rather than metadata extraction. To work with annotation values programmatically, you have two main approaches.

The first is the useDefaults option, which is Ajv's built-in annotation behavior — it writes default values into the validated data object:

import Ajv from 'ajv'

// useDefaults: true — the only annotation Ajv acts on automatically
const ajv = new Ajv({ useDefaults: true, allErrors: true })

const schema = {
  type: 'object',
  properties: {
    theme:    { type: 'string', enum: ['light', 'dark'], default: 'light' },
    language: { type: 'string', default: 'en' },
    timezone: { type: 'string', default: 'UTC' },
    notifications: {
      type: 'object',
      properties: {
        email: { type: 'boolean', default: true },
        push:  { type: 'boolean', default: false },
      },
    },
  },
}

const validate = ajv.compile(schema)

// User only specified theme; all other properties are missing
const userPrefs = { theme: 'dark' }
validate(userPrefs)

console.log(userPrefs)
// {
//   theme: 'dark',
//   language: 'en',
//   timezone: 'UTC',
//   notifications: { email: true, push: false }
// }
// Nested defaults are also applied

The second approach is to traverse the schema directly to extract any annotation value. Use json-schema-traverse or a recursive walk to collect all title, description, examples, or deprecated values alongside their JSON paths:

// Minimal annotation extractor — no dependencies required
function extractAnnotations(schema, path = '') {
  const result = []

  const annotations = ['title', 'description', 'default', 'examples', 'deprecated', 'readOnly', 'writeOnly']
  const found = {}
  for (const key of annotations) {
    if (key in schema) found[key] = schema[key]
  }
  if (Object.keys(found).length > 0) {
    result.push({ path, ...found })
  }

  if (schema.properties) {
    for (const [prop, subSchema] of Object.entries(schema.properties)) {
      result.push(...extractAnnotations(subSchema, `${path}/${prop}`))
    }
  }
  if (schema.items && typeof schema.items === 'object') {
    result.push(...extractAnnotations(schema.items, `${path}/items`))
  }

  return result
}

const annotations = extractAnnotations(schema)
// [
//   { path: '/email', title: 'Email Address', description: '...' },
//   { path: '/id', title: 'User ID', readOnly: true },
//   ...
// ]

For production use, prefer a library like json-schema-traverse (which handles all subschema locations including allOf, anyOf, $defs, and if/then/else) rather than the manual recursive walk above, which only covers flat properties and items.