Employee Attribute Definition Schemas

The schema property of an employee-attribute-definition specifies the structure and type of the values the matching employee-attributes can hold. These schemas use JSON Schema, with two restrictions:

Only static sub-schemas are allowed Property types are not freely defined. Each one must reference one of the static schemas exposed at the /lucca-api/schemas endpoint, through $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 static sub-schemas.

When you create an employee-attribute-definition (POST /lucca-api/employee-attribute-definitions), you provide a $ref to the relevant static schema. When you fetch an employee-attribute-definition, the API embeds the full definition of the referenced static schema, identified by its $id. This embedded schema cannot be sent back as is.

Examples

// POST
{
    "id": "e_tShirtSize",
    "name": "T-shirt size",
    "schema": {
        "$ref": "/lucca-api/schemas/taxonomy-label-reference"
    },
    "taxonomy": {
        "id": "45"
    }
}

// GET
{
    "id": "e_tShirtSize",
    "type": "employee-attribute-definition",
    "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",
        "type": ["object", "null"],
        "additionalProperties": false,
        "required": ["id"],
        "properties": {
            "id": {
                "type": "string",
                "minLength": 1
            },
            "type": {
                "type": "string",
                "const": "taxonomy-label",
                "readOnly": true
            },
            "url": {
                "type": "string",
                "format": "uri",
                "readOnly": true
            }
        }
    },
    "taxonomy": {
        "id": "45",
        "type": "taxonomy",
        "url": "https://example.ilucca.net/lucca-api/taxonomies/45"
    },
    "targetType": "employee",
    "category": "extension"
}

// POST
{
    "id": "e_children",
    "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": 1,
            "t9n": {
                "name": {
                    "fr-FR": "Date de naissance"
                }
            }
        },
        "bloodType": {
            "name": "Blood type",
            "taxonomy": {
                "id": "9575",
                "type": "taxonomy",
                "url": "https://example.ilucca.net/lucca-api/taxonomies/9575"
            },
            "sortOrder": 2,
            "t9n": {
                "name": {
                    "fr-FR": "Groupe sanguin"
                }
            }
        }
    },
    "taxonomy": null
}

Taxonomies and Taxonomy Labels

Some attribute values are not primitive types but 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).

Taxonomies in Employee Attribute Definitions

When an attribute value is restricted to a taxonomy-label, the definition’s schema references the /lucca-api/schemas/taxonomy-label-reference static schema. The definition then declares which taxonomy provides the allowed labels, through the taxonomy property at its root, alongside schema. For an object schema, each property restricted to taxonomy labels declares its own taxonomy in propertyDescriptions. In the T-Shirt size example above:

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

Overview

Files

Organization

Employee Records

Time Management

Events & Webhooks

Employee Attribute Definition Schemas