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

# Employee Attribute Definition Schemas

> Learn how to define and read the (JSON) schema of an employee-attribute-definition.

## Employee Attribute Definition Schemas

The `schema` property of an [`employee-attribute-definition`](./employee-attribute-definition) specifies the structure and type of the values the matching [`employee-attributes`](./employee-attribute) can hold.

These schemas use JSON Schema, with two restrictions:

1. **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`.
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 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

<CodeGroup>
  ```json T-Shirt size (taxonomy) theme={null}
  // 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"
  }
  ```

  ```json Children (object) theme={null}
  // 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
  }
  ```
</CodeGroup>

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


## Related topics

- [Replace an employee-attribute-definition](/api-reference/latest/employee-attributes/put-employee-attribute-definition.md)
- [Create an employee-attribute-definition](/api-reference/latest/employee-attributes/post-employee-attribute-definition.md)
- [Update an employee-attribute-definition](/api-reference/latest/employee-attributes/patch-employee-attribute-definition.md)
- [Retrieve an employee-attribute](/api-reference/latest/employee-attributes/get-employee-attribute.md)
- [Create an employee-attribute](/api-reference/latest/employee-attributes/post-employee-attribute.md)