JSON Schema default Keyword: Ajv useDefaults, OpenAPI, and Forms

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

The JSON Schema default keyword annotates a property with its default value — validators like Ajv can optionally apply it to missing properties when useDefaults: true is set. default is an annotation, not a validation constraint; a value that differs from defaultstill validates. Ajv's useDefaults: true mutates the validated object in-place — useful for config normalization but a side-effect to be aware of.

This guide covers the defaultkeyword spec, Ajv's useDefaults option, OpenAPI default semantics, JSON Schema form libraries, and common pitfalls like shared mutable defaults. You will leave with a clear mental model of when and how to apply defaults — and where they silently bite you.

What the JSON Schema default keyword actually does

The default keyword is defined in the JSON Schema meta-data vocabulary — the same vocabulary as title, description, examples, deprecated, readOnly, and writeOnly. All of these keywords are annotations: they attach information to a schema without influencing the pass/fail outcome of validation. See the JSON Schema annotations guide for the full vocabulary.

A validator that encounters default must not use it to reject data. If a property declares default: 20 and the instance provides 99, the validator evaluates 99 against type, minimum, maximum, and so on — ignoring default entirely. If the property is absent from the instance, the validator does not write 20 into the data — it simply skips the property.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Number of results per page. Assumed to be 20 when omitted."
    },
    "sortOrder": {
      "type": "string",
      "enum": ["asc", "desc"],
      "default": "asc"
    }
  }
}

// Both of these validate successfully — default is not a constraint:
// { "pageSize": 50, "sortOrder": "desc" }   ✓ normal case
// {}                                          ✓ empty object also valid
// { "pageSize": 1 }                           ✓ sortOrder absent — no error

The value of defaultshould itself be valid against the property's schema — putting a string in a default on an integer property is a schema authoring error, not a validation error. Tools that read default for documentation or UI rendering will display a confusing value if it does not match the declared type.

Because default is an annotation, Ajv and other validators may collect and expose it in their output (along with title, description, andexamples) but they do not act on it unless explicitly configured.

Ajv useDefaults: populate missing fields automatically

Ajv is the most widely used JSON Schema validator for JavaScript and TypeScript. Out of the box it treats default as a read-only annotation. To make Ajv write defaults into your data during validation, pass { useDefaults: true } to the constructor. See the Ajv JSON Schema validator guide for a broader introduction to Ajv configuration.

import Ajv from 'ajv'

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

const schema = {
  type: 'object',
  properties: {
    pageSize:  { type: 'integer', default: 20 },
    sortOrder: { type: 'string',  default: 'asc' },
    role:      { type: 'string',  default: 'viewer' },
  },
}

const validate = ajv.compile(schema)

const data = { sortOrder: 'desc' }   // pageSize and role are absent

validate(data)

console.log(data)
// { sortOrder: 'desc', pageSize: 20, role: 'viewer' }
//
// Ajv mutated the object in place — the two missing fields now have their defaults

The mutation happens before Ajv runs validation checks, which means the injected defaults are also validated against the schema. If a default value fails the schema's own constraints (for example, a default string that is too short), Ajv will report a validation error.

There is also a useDefaults: "empty" variant: instead of filling only absent properties, it also replaces properties whose value is undefined (distinct from null). This is useful in environments where JSON deserialization produces undefined for missing keys rather than omitting them.

Defaults in nested objects and arrays with Ajv

Ajv applies defaults depth-first. If a nested object property is present in the data, Ajv descends into it and fills defaults for its missing sub-properties. If the nested object itself is absent, Ajv does not create it — unless you declare a default on the parent property as well.

import Ajv from 'ajv'

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

const schema = {
  type: 'object',
  properties: {
    // Parent has default: {} so Ajv creates it when absent
    notifications: {
      type: 'object',
      default: {},
      properties: {
        email: { type: 'boolean', default: true },
        push:  { type: 'boolean', default: false },
        sms:   { type: 'boolean', default: false },
      },
    },
    theme: { type: 'string', default: 'light' },
  },
}

const validate = ajv.compile(schema)

// Case 1: notifications is absent entirely
const data1 = {}
validate(data1)
console.log(data1)
// { notifications: { email: true, push: false, sms: false }, theme: 'light' }
// Step 1: Ajv writes notifications: {} (parent default)
// Step 2: Ajv descends and fills email, push, sms defaults

// Case 2: notifications present but partially filled
const data2 = { notifications: { email: false } }
validate(data2)
console.log(data2)
// { notifications: { email: false, push: false, sms: false }, theme: 'light' }
// email kept as false (present); push and sms filled from defaults

For arrays, Ajv does not fill in defaults for missing array items. The useDefaults option only applies to object properties. If you need default items in an array, you must pre-populate the array in application code before passing it to the validator, or use a custom Ajv keyword.

Default in OpenAPI 3.x: parameters, requestBody, response schemas

OpenAPI 3.x uses default in two distinct contexts that are easy to confuse. Understanding both is essential when writing API specifications. See the JSON Schema and OpenAPI guide for deeper coverage.

1. default on a Parameter Object — This is a behavioral API contract. When a client omits a query, header, or cookie parameter, the server must behave as if the client had sent the declared default value. This is not just documentation: it is a semantic commitment that the server will apply the default server-side.

# OpenAPI 3.1 — default on a Parameter Object (behavioral contract)
paths:
  /products:
    get:
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20   # Server uses 20 when client omits ?pageSize
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: asc  # Server sorts ascending when client omits ?sortOrder

2. default on a Schema Object (inside requestBody or responses) — This is a JSON Schema annotation, the same as in a standalone JSON Schema document. It informs documentation tools and client generators about the assumed value when the property is absent, but imposes no server-side behavior requirement.

# OpenAPI 3.1 — default inside a Schema Object (annotation only)
components:
  schemas:
    CreateProductRequest:
      type: object
      properties:
        name:
          type: string
        currency:
          type: string
          default: USD        # Documentation annotation — no server obligation
        taxIncluded:
          type: boolean
          default: false      # Swagger UI pre-fills false in Try-it-out form
      required:
        - name

Swagger UI and Redoc use schema-level default to pre-fill the Try-it-out form fields. OpenAPI 3.1 aligns Schema Objects with JSON Schema Draft 2020-12, so schema-level default is a pure annotation in 3.1. In OpenAPI 3.0, the behavior is the same in practice but the specification was less explicit about the annotation vs. constraint distinction.

JSON Schema form libraries and default values

Form libraries that generate UI from JSON Schema read default to pre-fill fields. This is one of the most practical use cases for the keyword outside of validators. See the JSON Schema for forms guide for a full walkthrough.

react-jsonschema-form (rjsf) is the most widely used JSON Schema form library for React. It reads default and populates the form field with that value when no formData value is provided. Nested object defaults are applied recursively.

import Form from '@rjsf/core'
import validator from '@rjsf/validator-ajv8'

const schema = {
  type: 'object',
  title: 'User Preferences',
  properties: {
    theme: {
      type: 'string',
      enum: ['light', 'dark', 'system'],
      default: 'system',        // rjsf pre-selects 'system' in the dropdown
      title: 'Color Theme',
    },
    language: {
      type: 'string',
      default: 'en',
      title: 'Language',
    },
    emailDigest: {
      type: 'string',
      enum: ['daily', 'weekly', 'never'],
      default: 'weekly',
      title: 'Email Digest Frequency',
    },
  },
}

export default function PreferencesForm() {
  return (
    <Form
      schema={schema}
      validator={validator}
      onSubmit={({ formData }) => savePreferences(formData)}
    />
  )
  // rjsf renders a form with 'system', 'en', and 'weekly' pre-filled
}

json-forms (from EclipseSource) and Uniforms follow the same pattern: the default value is applied as the initial field value. Both support nested object defaults through their schema traversal logic.

A critical distinction: rjsf applies defaults from the schema only when formData is undefined or does not contain the field. If you pass partial formData, rjsf merges the defaults for the missing fields. This mirrors Ajv's useDefaults behavior and means you can use the same schema for both form rendering and server-side validation.

Common pitfalls: mutable defaults, $ref + default, and required vs default

The default keyword has several footguns that cause subtle, hard-to-debug bugs. Understanding them upfront saves hours of debugging.

Pitfall 1: Shared mutable defaults

When Ajv compiles a schema, it stores the default values from the schema object in memory. With useDefaults: true, Ajv writes a reference to that stored default into each validated data object. For primitives (strings, numbers, booleans), this is safe. For arrays and objects, every validated instance receives a reference to the same object. Mutating one instance mutates all future instances:

import Ajv from 'ajv'

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

const schema = {
  type: 'object',
  properties: {
    // DANGER: array default is a shared reference
    tags: { type: 'array', items: { type: 'string' }, default: [] },
  },
}

const validate = ajv.compile(schema)

const a = {}
const b = {}

validate(a)
validate(b)

a.tags.push('urgent')   // mutates the shared default array!

console.log(b.tags)     // ['urgent'] — b.tags is the same array object as a.tags

// FIX: deep-clone after validation, or use a factory function
import structuredClone from '@ungap/structured-clone'
const safeA = structuredClone({})
validate(safeA)
safeA.tags.push('urgent')
console.log(b.tags)     // [] — b is unaffected

Pitfall 2: $ref and default

In JSON Schema, a $ref replaces the schema at that location — sibling keywords next to a $ref are ignored in Draft-07 and earlier. This means placing default next to a $ref has no effect:

// Draft-07: default is ignored — $ref replaces the schema
{
  "$ref": "#/$defs/Role",
  "default": "viewer"   // silently ignored in Draft-07
}

// Draft 2019-09+: $ref is a keyword, siblings are merged — default works
{
  "$ref": "#/$defs/Role",
  "default": "viewer"   // applied in Draft 2019-09+ and JSON Schema 2020-12
}

// Safe approach in any draft: put default inside the $def
{
  "$defs": {
    "Role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"],
      "default": "viewer"   // always works regardless of draft
    }
  }
}

Pitfall 3: required vs default

Declaring a field as both required and giving it a defaultis contradictory outside of Ajv's useDefaults mode. Without useDefaults, if the field is absent, validation fails on required before the default annotation is ever consulted. The default never gets applied. The correct pattern: use default without required for fields the system can fill in; use required without default for fields the client must always provide explicitly.

Design patterns: config normalization, partial objects, and TypeScript defaults

The most practical use of default with Ajv's useDefaults is config normalization — accepting a partial configuration object and filling in all missing values with sensible defaults before the application uses it. See the JSON Schema guide for foundational concepts.

import Ajv from 'ajv'
import type { JSONSchemaType } from 'ajv'

// Full config type — all fields are required after normalization
interface AppConfig {
  port: number
  host: string
  maxConnections: number
  timeout: number
  logging: {
    level: 'debug' | 'info' | 'warn' | 'error'
    format: 'json' | 'text'
  }
}

const schema: JSONSchemaType<AppConfig> = {
  type: 'object',
  properties: {
    port:           { type: 'integer', default: 3000 },
    host:           { type: 'string',  default: '0.0.0.0' },
    maxConnections: { type: 'integer', default: 100 },
    timeout:        { type: 'integer', default: 30000 },
    logging: {
      type: 'object',
      default: {},
      properties: {
        level:  { type: 'string', enum: ['debug', 'info', 'warn', 'error'], default: 'info' },
        format: { type: 'string', enum: ['json', 'text'], default: 'json' },
      },
      required: ['level', 'format'],
    },
  },
  required: ['port', 'host', 'maxConnections', 'timeout', 'logging'],
}

const ajv = new Ajv({ useDefaults: true })
const validate = ajv.compile(schema)

// Accept partial config from user — only override what they specify
function normalizeConfig(partial: Partial<AppConfig>): AppConfig {
  // Deep-clone to avoid mutable default contamination
  const config = JSON.parse(JSON.stringify(partial))
  if (!validate(config)) {
    throw new Error('Invalid config: ' + ajv.errorsText(validate.errors))
  }
  return config as AppConfig  // useDefaults guarantees all required fields present
}

const config = normalizeConfig({ port: 8080 })
// { port: 8080, host: '0.0.0.0', maxConnections: 100, timeout: 30000,
//   logging: { level: 'info', format: 'json' } }

The JSON.parse(JSON.stringify(partial)) deep-clone on line before validation prevents the shared mutable default problem. It also converts undefined values to omitted keys, which useDefaults then fills.

For TypeScript, the key insight is that after validate(config) returns true with useDefaults: true, all required fields are guaranteed to be present — so the as AppConfig assertion is safe. If you want to avoid the assertion, wrap the function to return AppConfig | null and check the Ajv result.