> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started With Extension Definition Schemas

> Learn how to define and use (JSON) schemas in our extension system.

## Extension Definition Schemas

The `schema` property of an `extension-definition` specifies the structure and type of the values the extension can hold.

Extension schemas use JSON Schema, but with important restrictions:

1. **Only static sub-schemas are allowed**
   Property types cannot be freely defined. Instead, they must reference one of the static schemas exposed at the /lucca-api/schemas endpoint.
   You must declare these references using `$ref`.
2. **Objects are only supported at the root**
   Nested objects (objects as child properties) are not supported.
   The root schema may be of type object, but its properties must still use `$ref` to point to allowed sub-schemas.

When you create an extension-definition (POST), you provide a `$ref` to the relevant static schema.

When you fetch an extension-definition (GET), the API may either return the raw `$ref` or inline transclude the full definition of the referenced schema.

### Examples

<CodeGroup>
  ```json T-Shirt size (taxonomy) theme={null}
  // POST
  {
      "name": "T-Shirt size",
      "schema": {
          "$ref": "/lucca-api/schemas/taxonomy-label-reference"
      },
      "taxonomy": {
          "id": "39874"
      }
  }

  // GET (inline transclude)
  {
      "name": "T-Shirt size",
      "schema": {
          "$id": "/lucca-api/schemas/taxonomy-label-reference",
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "taxonomy-label-reference",
          "description": "JSON representation of a reference to a taxonomy label"
          "required": [
              "id"
          ],
          "type": [
              "null",
              "object"
          ],
          "properties": {
              "id": {
                  "minLength": 1,
                  "type": "string"
              },
              "type": {
                  "const": "taxonomy-label",
                  "type": "string",
                  "readOnly": true
              },
              "url": {
                  "type": "string",
                  "format": "uri",
                  "readOnly": true
              }
          },
          "additionalProperties": false,
      },
      "taxonomy": {
          "id": "39874"
      }
  }
  ```

  ```json Children (object) theme={null}
  {
      "name": "Children",
      "schema": {
          "type": "object",
          "properties": {
              "givenName": {
                  "$ref": "/lucca-api/schemas/short-text"
              },
              "birthDate": {
                  "$ref": "/lucca-api/schemas/legacy-date"
              },
              "bloodType":  {
                  "$ref": "/lucca-api/schemas/taxonomy-label-reference"
              }
          }
      },
      "propertyDescriptions": {
          "givenName": {
              "name": "Given name",
              "taxonomy": null,
              "sortOrder": 0,
              "t9n": {
                  "name": {
                      "fr-FR": "Prénom"
                  }
              }
          },
          "birthDate": {
              "name": "Birth date",
              "taxonomy": null,
              "sortOrder": 0,
              "t9n": {
                  "name": {
                      "fr-FR": "Date de naissance"
                  }
              }
          },
          "bloodType": {
              "name": "Blood type",
              "taxonomy": {
                  "id": "9575",
                  "type": "taxonomy",
                  "url": "https://example.ilucca.net/lucca-api/9575"
              },
              "sortOrder": 0,
              "t9n": {
                  "name": {
                      "fr-FR": "Groupe sanguin"
                  }
              }
          }
      },
      "taxonomy": null,
  }
  ```
</CodeGroup>

## Taxonomies and Taxonomy Labels

Some extension values are not primitive types but instead must be chosen from a user-defined list. These lists are modeled through the taxonomies and taxonomy-labels API endpoints:

* **Taxonomies** represent the named lists themselves (e.g. T-Shirt sizes).
* **Taxonomy-labels** represent the individual values within a `taxonomy` (e.g. Small, Medium, Large).

Both `taxonomies` and `taxonomy-labels` can be retrieved, created and updated through their own API endpoints.

### Using Taxonomies in Extension Definitions

When an extension value should be restricted to a `taxonomy-label`, the extension’s schema must reference the static schema:

In addition, the extension-definition must declare which `taxonomy` it refers to.
This is done by including a `taxonomy` property at the root of the extension-definition object, alongside schema.

Without this `taxonomy` reference, the system would not know which set of labels to use for validation.

<CodeGroup>
  ```json theme={null}
  POST /lucca-api/{resource}-extension-definitions HTTPS/2

  {
      ...,
      "schema": {
          "$ref": "/lucca-api/schemas/taxonomy-label-reference"
      },
      "taxonomy": {
          "id": "39874"
      }
  }
  ```
</CodeGroup>

In this example:

* The `schema` restricts values to a taxonomy label reference.
* The `taxonomy.id` identifies which taxonomy provides the allowed labels (e.g. the list of T-Shirt sizes).