Reusable Schemas with $ref and $defs

Reusable Schemas with $ref and $defs

As schemas grow, you inevitably need the same structure in multiple places — an address used for both billing and shipping, or a line item used in orders and invoices. The $ref keyword lets you reference a schema defined elsewhere, and $defs provides a standard location for those definitions.

Basic Syntax

{
  "$defs": {
    "MyType": {
      "type": "string",
      "minLength": 1
    }
  },
  "properties": {
    "name": { "$ref": "#/$defs/MyType" }
  }
}

The $ref value is a JSON Pointer — #/$defs/MyType means "look in the current document, under $defs, at the key MyType."

How the Example Schema Works

The schema models an e-commerce order with two reusable definitions:

Address — defines a postal address with street, city, state, postalCode, and country. It is referenced twice: once for billing and once for shipping. Both properties share the exact same validation rules — any change to the Address definition automatically applies to both.

LineItem — defines a product line item with productId, name, quantity, and unitPrice. It is used as the items schema for the order's items array.

The test data provides valid billing and shipping addresses (both conforming to the Address schema) and two valid line items (each conforming to LineItem).

$defs vs. definitions

• Draft 2019-09+: Use $defs (with a dollar sign).
• Draft 7 and earlier: Use definitions (without a dollar sign).

Both work the same way — the rename was part of a broader effort to prefix JSON Schema keywords with $. Most modern validators support both.

External References

$ref can also point to external files:

{ "$ref": "./address.json" }
{ "$ref": "https://api.example.com/schemas/address.json" }

External references are resolved relative to the schema's URI. This enables a library of shared schemas across multiple API endpoints.

Overriding $ref Properties

In Draft 2019-09+, you can place keywords alongside $ref:

{
  "$ref": "#/$defs/Address",
  "required": ["street", "city", "state", "postalCode", "country"]
}

This references the Address definition but adds a stricter required list. In older drafts, all siblings of $ref were ignored — be cautious with backward compatibility.

Best Practices

• Name definitions clearly: Use PascalCase names that match your domain model (Address, LineItem, User).
• Keep $defs at the root: Place all definitions at the document root for discoverability.
• Avoid circular references: While technically allowed, circular $ref chains can cause infinite loops in some validators.