description

The description keyword provides a detailed, human-readable explanation of the schema. It is used to document the purpose and usage of the data described by the schema.

Syntax

The value of description must be a string.

{
  "description": "string"
}

Purpose

The description keyword is a metadata annotation that:

Provides detailed explanation about the purpose of the instance described by the schema
Enhances documentation with contextual information
Helps developers understand the intended use of data fields
Can be displayed in user interfaces to guide users
Has no effect on validation (it is purely informational)

A description provides comprehensive explanation, whereas a title is preferably short and concise.

Examples

Basic Usage

{
  "type": "string",
  "title": "Email",
  "description": "The user's primary email address used for account notifications and password recovery",
  "format": "email"
}

This schema includes both a short title and a detailed description explaining the purpose of the email field.

Complex Object Documentation

{
  "type": "object",
  "title": "User Account",
  "description": "Represents a user account in the system. Each account must have a unique email address and username. Accounts can be created via the registration API or imported from external identity providers.",
  "properties": {
    "username": {
      "type": "string",
      "description": "Unique username for the account. Must be 3-20 characters long and contain only alphanumeric characters, hyphens, and underscores.",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "email": {
      "type": "string",
      "description": "Primary email address. Must be unique across all accounts. Used for login and account recovery.",
      "format": "email"
    },
    "createdAt": {
      "type": "string",
      "description": "Timestamp indicating when the account was created, in ISO 8601 format",
      "format": "date-time"
    }
  },
  "required": ["username", "email"]
}

Detailed descriptions help developers understand business rules and constraints for each field.

API Endpoint Parameter

{
  "type": "integer",
  "title": "Page Size",
  "description": "Number of items to return per page. Default is 20. Maximum allowed value is 100 to prevent excessive load on the server.",
  "minimum": 1,
  "maximum": 100,
  "default": 20
}

The description explains both the purpose and the reasoning behind the constraints.

Configuration Schema

{
  "type": "object",
  "title": "Database Configuration",
  "description": "Configuration options for database connection pooling and timeout settings",
  "properties": {
    "maxConnections": {
      "type": "integer",
      "description": "Maximum number of concurrent database connections in the pool. Higher values allow more concurrent requests but consume more memory. Recommended range is 10-50 for most applications.",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "connectionTimeout": {
      "type": "integer",
      "description": "Maximum time in milliseconds to wait for a connection from the pool before timing out. If all connections are busy and this timeout is reached, the request will fail.",
      "minimum": 1000,
      "default": 30000
    },
    "idleTimeout": {
      "type": "integer",
      "description": "Time in milliseconds that a connection can remain idle in the pool before being closed. Set to 0 to disable idle timeout.",
      "minimum": 0,
      "default": 600000
    }
  }
}

Descriptions provide operational context and best practices for configuration values.

Validation Rules Documentation

{
  "type": "string",
  "title": "Product SKU",
  "description": "Stock Keeping Unit identifier following the format: [CATEGORY]-[SUBCATEGORY]-[ITEM_NUMBER]. Example: ELEC-COMP-00123 for electronics/computers/item 123. Must be unique across all products.",
  "pattern": "^[A-Z]{4}-[A-Z]{4}-\\d{5}$"
}

The description explains the format pattern in human-readable terms with examples.

Enum Values Explanation

{
  "type": "string",
  "title": "Order Status",
  "description": "Current status of the order in the fulfillment pipeline. Orders progress from 'pending' to 'processing' to 'shipped' to 'delivered'. Orders can be 'cancelled' at any stage before shipping.",
  "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
}

The description provides workflow context for the enumerated values.

Best Practices

Include Usage Context

Good descriptions explain not just what the field is, but how it’s used:

{
  "type": "boolean",
  "title": "Email Notifications",
  "description": "Enable or disable email notifications for this user. When enabled, the user will receive emails for account activities, security alerts, and promotional messages based on their notification preferences.",
  "default": true
}

Document Defaults and Edge Cases

{
  "type": "number",
  "title": "Discount Percentage",
  "description": "Percentage discount to apply to the order total. Must be between 0 and 100. A value of 0 means no discount. Discounts are applied before tax calculation.",
  "minimum": 0,
  "maximum": 100
}

Provide Examples When Helpful

{
  "type": "string",
  "title": "Phone Number",
  "description": "International phone number in E.164 format, including country code. Examples: +14155552671 (US), +442071234567 (UK), +81312345678 (Japan)",
  "pattern": "^\\+[1-9]\\d{1,14}$"
}

Core Keywords

Applicator Keywords

Validation Keywords

Meta-Data

Syntax

Purpose

Examples

Basic Usage

Complex Object Documentation

API Endpoint Parameter

Configuration Schema

Validation Rules Documentation

Enum Values Explanation

Best Practices

Include Usage Context

Document Defaults and Edge Cases

Provide Examples When Helpful

​Syntax

​Purpose

​Examples

​Basic Usage

​Complex Object Documentation

​API Endpoint Parameter

​Configuration Schema

​Validation Rules Documentation

​Enum Values Explanation

​Best Practices

​Include Usage Context

​Document Defaults and Edge Cases

​Provide Examples When Helpful

Syntax

Purpose

Examples

Basic Usage

Complex Object Documentation

API Endpoint Parameter

Configuration Schema

Validation Rules Documentation

Enum Values Explanation

Best Practices

Include Usage Context

Document Defaults and Edge Cases

Provide Examples When Helpful