job-position

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lucca/main/json-schema/lucca-job-position-create-schema.json",
  "title": "job-position",
  "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.",
  "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/job-position.create",
  "x-tags": [
    "Employees"
  ],
  "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"
      ]
    },
    "employment": {
      "title": "employment-reference",
      "description": "Reference to an [employment](../employments/employment) resource.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "id"
      ]
    },
    "startsOn": {
      "description": "Effective date of this job-position for this employee.\n\nCannot be outside the range of the employment.\n\nThe `startsOn` of the first job-position of an employment follows the employment `start.date`: change the employment start instead, as updating it directly returns a `400`.\n\nThis should be considered \"applicable\" based on the related [employment](../employments/employment) business-establishment timezone.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$",
      "format": "date"
    },
    "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"
        }
      ]
    },
    "notes": {
      "type": [
        "null",
        "string"
      ],
      "maxLength": 500,
      "description": "Optional notes about this job-position change."
    },
    "t9n": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "jobTitle": {
          "$ref": "#/$defs/t9n"
        }
      }
    }
  },
  "required": [
    "employment",
    "startsOn",
    "businessEstablishment",
    "department"
  ],
  "$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"
          ]
        }
      }
    }
  }
}