Skip to main content

​
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

// 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"
    }
}

​
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. 
POST /lucca-api/{resource}-extension-definitions HTTPS/2

{
    ...,
    "schema": {
        "$ref": "/lucca-api/schemas/taxonomy-label-reference"
    },
    "taxonomy": {
        "id": "39874"
    }
}
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).