Log In

Customizing the interface through JSON settings

The JSON settings fully describe a project interface. To edit your project JSON settings, go to your project "Settings" page, and then click the JSON interface tab.


To reuse your JSON settings with a different project, simply copy file contents and paste them in the other project.

Generic JSON template

"jobs": {
    "<job name>": {
      "content": {
        "categories": {
          "<category name (internal)>": {
            "children": ["JOB_1, JOB_2"],
            "name": "<category name>",
            "id": "<category id>",
            "shortcut": "<letter>",
            "color": "<hex>", 
            "jsonMetadata": {
              "<metadata type>": "<some text>"           
        "input": "<input type>"
      "instruction": "<short instructions>",
      "mlTask": "<job type>",
      "required": 0|1,
      "isChild": true|false,
      "isNew": true|false,
      "isVisible": true|false

Editable parameters:

Parameter nameDescriptionInput scope
<job name>Unique name of the specific labeling jobText
<category name>Name of the category
(internal; won't be exported or visible in jobs view)
childrenComma-separated list of nested child jobsJSON array
color(optional)Custom color for category (in hex)RGB color in HEX notation. For example:
"color": "#941100"
shortcut(optional)Custom shortcut for label categoryLetters of the English alphabet (a-z) and numbers (0-9). For example:
"shortcut": "Z"
nameName of the label category
(included in export data)
idID of categoryText
jsonMetadata(optional)You can add metadata to your label category. Every annotator will be able to see metadata directly in the job interface, when they hover over the information icon to the right of the category. For information on using jsonMetadata with assets (for OCR tasks), refer to Optical character recognition.Any (or combination) of:
- "imageUrl": "<image URL>",
- "text": "Some text",
- "url": ""
- Text
- Image and URL
inputInput type (for example, "radio" for radio button)For specifics, refer to Customization per job type
instructionShort instructions for the labeling jobText
mlTaskKili labeling job categoryFor specifics, refer to the Labeling job type mapping
requiredInformation if labeling job is required. Required jobs have to be completed for a labeling job to be considered complete.1 or 0
isChildSet if the job is nested under another jobtrue or false
isNewIn projects with many labeling jobs, most jobs are collapsed by default. This parameter is used by Kili UI to show new jobs in fulltrue or false
isVisible(optional)Used to hide labeling jobs from labelerstrue or false

Metadata example: text


Metadata example: image and URL


Labeling job type mapping

Labeling job typemlTask
Object detectionOBJECT_DETECTION
Semantic segmentationOBJECT_DETECTION
Object relationOBJECT_RELATION
Named entities relationNAMED_ENTITIES_RELATION


In PDF projects different pages may represent different document types, so transcription and classification tasks in PDF projects can now be defined once but set to apply to each of the pages separately.
To enable that, use a Classification or a Transcription job, and then set:


Customization per job type

Additional JSON objects are available in specific job types. For details, refer to:

Nesting jobs in JSON

If you want the job to be nested under another job, set its "isChild" attribute to true and add the job ID in the "children" list for the parent.

For example:

      "content": {
        "categories": {
          "A": {
            "children": [],
            "name": "A",
            "id": "A"
          "B": {
            "children": [
            "name": "B",
            "id": "B"
        "input": "radio"
      "instruction": "<instruction>",
      "mlTask": "CLASSIFICATION",
      "required": 1,
      "isChild": false,
      "isNew": true
      "content": {
        "categories": {
          "C": {
            "children": [],
            "name": "C",
            "id": "C"
          "D": {
            "children": [],
            "name": "D",
            "id": "D"
        "input": "checkbox"
      "instruction": "<instruction>",
      "mlTask": "CLASSIFICATION",
      "required": 1,
      "isChild": true,
      "isNew": true

results in this job structure:


  • Only classification jobs and transcription job types are allowed as child jobs
  • In total, you can only nest up to 4 jobs in a row (one main job and three sub-jobs)
  • All job types can have a child job, except for transcription jobs and classification jobs with a Multi choice dropdown input type