employment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lucca/main/json-schema/lucca-employment-create-schema.json",
  "title": "employment",
  "description": "The employment resource represents a relationship between an [employee](../employees/employee) and a [legal-entity](../organization/legal-entity) over a continuous period. It may actually represent a work contract, an internship agreement, a contractor's contract, etc...\n\nThe actual job of the employee is defined through the [job-position](/api-reference/latest/employments/job-position) resource, which references an employment. Over the course of his/her employment, the employee may occupy several job-positions.",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lucca-api-2024-11-01.json#/components/schemas/employment.create",
  "x-tags": [
    "employees"
  ],
  "type": "object",
  "properties": {
    "remoteId": {
      "type": [
        "null",
        "string"
      ],
      "minLength": 1,
      "maxLength": 200,
      "description": "Resource identifier in a third-party system."
    },
    "employee": {
      "title": "employee-reference",
      "description": "Reference to an employee resource.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "legalEntity": {
      "description": "Reference to a legal-entity. It must be the legal-entity of the business-establishment of the first job-position, otherwise the API returns a `400`.",
      "allOf": [
        {
          "title": "Reference to a legal-entity",
          "description": "Reference to a [legal-entity](../organization/legal-entity) resource.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "id"
          ]
        }
      ]
    },
    "start": {
      "type": "object",
      "required": [
        "date"
      ],
      "additionalProperties": false,
      "properties": {
        "date": {
          "description": "Date of the first day (included) of this employment.",
          "type": "string",
          "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$",
          "format": "date"
        }
      }
    },
    "end": {
      "type": [
        "null",
        "object"
      ],
      "additionalProperties": false,
      "required": [
        "date"
      ],
      "properties": {
        "date": {
          "description": "Date of the last day (included) of this employment. After this date, this employment is considered terminated.\n\nLeave `null` for permanent employments (as long as the employee is kept), and set the date of the last day in case of a fixed-term employment.\n\nEndsOn date must be greater or equal than StartsOn date.",
          "type": "string",
          "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$",
          "format": "date"
        }
      }
    },
    "document": {
      "oneOf": [
        {
          "title": "file-reference",
          "description": "Reference to a [file](../files/file) resource.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "id"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "template": {
      "title": "employment-template-reference",
      "description": "Reference to an [employment-template](../employments/employment-template) resource.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "id"
      ]
    },
    "firstJobPosition": {
      "title": "job-position",
      "x-tags": [
        "Employees"
      ],
      "description": "The job position represents a stage in an [employee](../employees/employee)'s career during one of their [employment](/api-reference/latest/employments/employment) in a given [business-establishment](../organization/business-establishment).\n\nIt therefore outlines the attributes of the person as a professional (qualifications) and their role in the company as well as who's their manager.",
      "type": "object",
      "properties": {
        "remoteId": {
          "minLength": 1,
          "maxLength": 1024,
          "description": "Resource identifier in a third-party system. No unicity constraint: two job-positions may have the same value.",
          "type": [
            "null",
            "string"
          ]
        },
        "businessEstablishment": {
          "title": "business-establishment-reference",
          "description": "Reference to a [business-establishment](../organization/business-establishment) resource.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "jobTitle": {
          "description": "Short description of the job occupied by this employee.",
          "type": [
            "null",
            "string"
          ],
          "maxLength": 1024,
          "minLength": 1
        },
        "jobQualification": {
          "oneOf": [
            {
              "title": "job-qualification-reference",
              "description": "Reference to a [job-qualification](../employee-occupations/job-qualification) resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "manager": {
          "oneOf": [
            {
              "title": "employee-reference",
              "description": "Reference to an employee resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "occupationCategory": {
          "oneOf": [
            {
              "title": "occupation-category-reference",
              "description": "Reference to an [occupation-category](../employee-occupations/occupation-category) resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "workingTimeArrangement": {
          "oneOf": [
            {
              "title": "working-time-arrangement-reference",
              "description": "Reference to a working-time-arrangement resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "department": {
          "title": "department-reference",
          "description": "Reference to a [department](../organization/department) resource.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "document": {
          "oneOf": [
            {
              "title": "file-reference",
              "description": "Reference to a [file](../files/file) resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "t9n": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "jobTitle": {
              "$ref": "#/$defs/t9n"
            }
          }
        }
      },
      "required": [
        "businessEstablishment",
        "department"
      ]
    }
  },
  "required": [
    "employee",
    "start",
    "legalEntity",
    "template",
    "firstJobPosition"
  ],
  "$defs": {
    "t9n": {
      "type": [
        "object",
        "null"
      ],
      "title": "Translations",
      "description": "Used for translation purposes. Object is structured as a dictionary whose keys refer to translated properties of the parent object, and whose values are a dictionary of supported languages.\n\nOn the parent object, the translated property value is considered the \"invariant\" translation. It is expected to show this value whenever the user's language has no translation in `t9n`.\n\nLanguages are identified through their RFC 4646 language tag.",
      "properties": {
        "de-DE": {
          "description": "German (Germany)",
          "type": [
            "string",
            "null"
          ]
        },
        "en-US": {
          "description": "English (United States of America)",
          "type": [
            "string",
            "null"
          ]
        },
        "en-GB": {
          "description": "English (Great Britain)",
          "type": [
            "string",
            "null"
          ]
        },
        "es-ES": {
          "description": "Spanish (Spain)",
          "type": [
            "string",
            "null"
          ]
        },
        "fr-FR": {
          "description": "French (France)",
          "type": [
            "string",
            "null"
          ]
        },
        "fr-CH": {
          "description": "French (Switzerland)",
          "type": [
            "string",
            "null"
          ]
        },
        "it-IT": {
          "description": "Italian (Italy)",
          "type": [
            "string",
            "null"
          ]
        },
        "nl-BE": {
          "description": "Dutch (Belgium)",
          "type": [
            "string",
            "null"
          ]
        },
        "nl-NL": {
          "description": "Dutch (Netherlands)",
          "type": [
            "string",
            "null"
          ]
        },
        "pt-PT": {
          "description": "Portuguese (Portugal)",
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}