deprecated

The deprecated keyword indicates that applications should refrain from using the declared property or schema. It signals that a feature may be removed in future versions.

Syntax

The value of deprecated must be a boolean.

{
  "deprecated": true
}

Purpose

The deprecated keyword is a metadata annotation that:

Marks properties or schemas as deprecated
Signals that a feature may be removed in future versions
Helps developers migrate away from outdated fields
Can be used by tools to warn about deprecated usage
Has no effect on validation (it is purely informational)

When multiple occurrences of this keyword are applicable to a single sub-instance, applications should consider the instance location to be deprecated if any occurrence specifies a true value.

Behavior

Property Deprecation

The deprecated keyword applies to each instance location to which the schema object containing the keyword successfully applies. This can result in scenarios where every array item or object property is deprecated even though the containing array or object is not.

Root Schema Deprecation

A root schema containing deprecated with a value of true indicates that the entire resource being described may be removed in the future.

Default Behavior

Omitting this keyword has the same behavior as a value of false.

Examples

Deprecated Property

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "username": {
      "type": "string",
      "deprecated": true,
      "description": "Username field is deprecated. Use email for authentication instead."
    }
  }
}

The username property is marked as deprecated, signaling that developers should use email instead.

Migration Path Documentation

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "fullName": {
      "type": "string",
      "deprecated": true,
      "description": "DEPRECATED: Use firstName and lastName instead. This field will be removed in v3.0."
    }
  }
}

Clear migration instructions help developers update their code.

API Versioning

{
  "type": "object",
  "title": "User API Response",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "profile_image": {
      "type": "string",
      "format": "uri",
      "deprecated": true,
      "description": "Deprecated. Use profileImageUrl instead."
    },
    "profileImageUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's profile image"
    }
  }
}

API evolution using deprecation to guide users to new field names.

Multiple Deprecated Fields

{
  "type": "object",
  "title": "Product",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "price": {
      "type": "number"
    },
    "cost": {
      "type": "number",
      "deprecated": true,
      "description": "Deprecated: Internal cost information will no longer be exposed in API v2."
    },
    "vendor_id": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated: Use vendorId (camelCase) instead."
    },
    "vendorId": {
      "type": "string"
    }
  }
}

Multiple deprecated fields during a transition period.

Deprecated Enum Value (Pattern)

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending", "suspended"],
      "description": "Account status. Note: 'suspended' is deprecated and will be removed in the next major version."
    }
  }
}

While you cannot deprecate individual enum values directly, you can document it in the description.

Deprecated Configuration Option

{
  "type": "object",
  "title": "Server Configuration",
  "properties": {
    "port": {
      "type": "integer",
      "default": 3000
    },
    "enableHttp": {
      "type": "boolean",
      "deprecated": true,
      "description": "Deprecated: HTTP support is being removed. Use HTTPS only.",
      "default": false
    },
    "enableHttps": {
      "type": "boolean",
      "description": "Enable HTTPS server",
      "default": true
    }
  }
}

Configuration options deprecated for security reasons.

Deprecated with Timeline

{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "deprecated": true,
      "description": "DEPRECATED (as of v2.0, removed in v4.0): Use OAuth 2.0 authentication instead. See migration guide: https://api.example.com/docs/auth-migration"
    },
    "accessToken": {
      "type": "string",
      "description": "OAuth 2.0 access token"
    }
  }
}

Deprecation notice with version timeline and migration documentation link.

Entire Schema Deprecated

{
  "type": "object",
  "title": "Legacy User Object",
  "deprecated": true,
  "description": "This entire schema is deprecated. Use the User v2 schema instead.",
  "properties": {
    "user_id": {
      "type": "string"
    },
    "user_name": {
      "type": "string"
    }
  }
}

Marking an entire schema as deprecated when replacing it with a new version.

Array Items Deprecated

{
  "type": "object",
  "properties": {
    "roles": {
      "type": "array",
      "description": "User roles. The 'super_admin' role is deprecated.",
      "items": {
        "type": "string",
        "enum": ["user", "admin", "moderator", "super_admin"]
      }
    }
  }
}

Deprecating specific array values through documentation.

Conditional Deprecation Documentation

{
  "type": "object",
  "properties": {
    "paymentMethod": {
      "type": "string",
      "enum": ["credit_card", "paypal", "bank_transfer", "bitcoin"],
      "description": "Payment method. Note: 'bitcoin' payment method is deprecated for new transactions as of January 2024."
    }
  }
}

Documenting conditional or partial deprecation.

Replacement Field Indicated

{
  "type": "object",
  "title": "Event",
  "properties": {
    "timestamp": {
      "type": "integer",
      "description": "Unix timestamp",
      "deprecated": true,
      "description": "Deprecated: Use eventTime (ISO 8601 format) for better timezone support."
    },
    "eventTime": {
      "type": "string",
      "format": "date-time",
      "description": "Event timestamp in ISO 8601 format"
    }
  }
}

Clear indication of the replacement field improves developer experience.

Best Practices

Provide Clear Migration Instructions

Always explain what developers should use instead:

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated: Use phoneNumber field which supports international format."
    },
    "phoneNumber": {
      "type": "string",
      "description": "Phone number in E.164 format"
    }
  }
}

Include Version Information

Specify when the field was deprecated and when it will be removed:

{
  "type": "object",
  "properties": {
    "oldField": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated in v2.1.0, will be removed in v3.0.0. Use newField instead."
    },
    "newField": {
      "type": "string"
    }
  }
}

Link to Documentation

Provide links to migration guides:

{
  "type": "object",
  "properties": {
    "legacyAuth": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated: See https://docs.example.com/migration/auth for migration guide."
    }
  }
}

Keep Deprecated Fields Functional

Deprecated fields should continue to work during the deprecation period:

{
  "type": "object",
  "properties": {
    "oldFormat": {
      "type": "string",
      "deprecated": true,
      "description": "Still supported but deprecated. Will be removed in v4.0."
    },
    "newFormat": {
      "type": "string"
    }
  }
}

Core Keywords

Applicator Keywords

Validation Keywords

Meta-Data

Syntax

Purpose

Behavior

Property Deprecation

Root Schema Deprecation

Default Behavior

Examples

Deprecated Property

Migration Path Documentation

API Versioning

Multiple Deprecated Fields

Deprecated Enum Value (Pattern)

Deprecated Configuration Option

Deprecated with Timeline

Entire Schema Deprecated

Array Items Deprecated

Conditional Deprecation Documentation

Replacement Field Indicated

Best Practices

Provide Clear Migration Instructions

Include Version Information

Link to Documentation

Keep Deprecated Fields Functional

​Syntax

​Purpose

​Behavior

​Property Deprecation

​Root Schema Deprecation

​Default Behavior

​Examples

​Deprecated Property

​Migration Path Documentation

​API Versioning

​Multiple Deprecated Fields

​Deprecated Enum Value (Pattern)

​Deprecated Configuration Option

​Deprecated with Timeline

​Entire Schema Deprecated

​Array Items Deprecated

​Conditional Deprecation Documentation

​Replacement Field Indicated

​Best Practices

​Provide Clear Migration Instructions

​Include Version Information

​Link to Documentation

​Keep Deprecated Fields Functional

Syntax

Purpose

Behavior

Property Deprecation

Root Schema Deprecation

Default Behavior

Examples

Deprecated Property

Migration Path Documentation

API Versioning

Multiple Deprecated Fields

Deprecated Enum Value (Pattern)

Deprecated Configuration Option

Deprecated with Timeline

Entire Schema Deprecated

Array Items Deprecated

Conditional Deprecation Documentation

Replacement Field Indicated

Best Practices

Provide Clear Migration Instructions

Include Version Information

Link to Documentation

Keep Deprecated Fields Functional