Creating and Managing Definitions

Definitions are reusable blocks inside a schema. Define a common structure once, then reference it wherever it is needed instead of repeating it, so a change to the structure applies everywhere it is used.

What are definitions?

Definitions allow you to define common schema structures once and then reference them throughout your schemas, avoiding redundancy and simplifying maintenance.

Example of a definition

Imagine you are designing schemas for various entities in an e-commerce system, and several of these entities (like Customer, Order, and Vendor) need to include an Address. Instead of defining the Address schema repeatedly within each entity's schema, you can define it once in the definitions section.

Here is how the Address schema might look as a separate JSON object within the definitions section of a larger schema:

{
  "type": "object",
  "properties": {
    "street": { "type": "string" },
    "city": { "type": "string" },
    "zipCode": { "type": "string" },
    "country": { "type": "string" }
  },
  "required": ["street", "city", "zipCode", "country"]
}

Within your Customer schema, you then reference this Address definition using the $ref keyword:

{
  "type": "object",
  "properties": {
    "customerId": { "type": "integer" },
    "name": { "type": "string" },
    "shippingAddress": { "$ref": "#/definitions/Address" }
  }
}

Create a definition

1. Open a schema in edit mode and select the Definitions icon.
2. Select the + icon at the top of the Definitions pane and enter a name for the definition.
3. Select the definition to edit its details in the Schema Editor.
4. Build the schema in the code view, or use the editor controls. See editing schema details using the editor.
5. Select Save.

The definition is now available to include in other schemas.

Edit a definition

1. Open a schema in edit mode and select the Definitions icon.
2. Select the definition you want to edit to view its details in the Schema Editor.
3. Change the schema in the code view, or use the editor controls. See editing schema details using the editor.
4. Select Save.

Add a definition to a schema

Syntactically, a definition is just another property of a schema.

1. Open the schema in edit mode and select the Definitions icon.
2. Select Add in the Schema Editor to add the definition as a new property. To update an existing property instead, select it and then select the Properties icon in its toolbar.
3. Select the Reference tab.
4. Enter the Name of the definition in the schema.
5. Drag the definition you want to associate into the Reference field. The field updates to show the reference in the form #/$defs/<definition_name>, for example #/$defs/Address.
6. Add any other details, then select Apply.

How you know it worked

The property shows the reference path, such as #/$defs/Address, and the referenced structure appears wherever the schema is used.

Next steps

To reference schemas outside the current document, see Working with Schema References.