Get Started With Extension Definition Schemas

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:

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

{
    "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,
}

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).

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Get Started With Extension Definition Schemas

Extension Definition Schemas

Examples

Taxonomies and Taxonomy Labels

Using Taxonomies in Extension Definitions

​Extension Definition Schemas

​Examples

​Taxonomies and Taxonomy Labels

​Using Taxonomies in Extension Definitions

Extension Definition Schemas

Examples

Taxonomies and Taxonomy Labels

Using Taxonomies in Extension Definitions