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. For more information, refer to Adding instructions. For information on using jsonMetadata with assets (for OCR tasks), refer to Optical character recognition. Note that adding metadata for transcription jobs is not supported.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 job.true 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 full.true or false
isIgnoredForMetricsComputationsUsed to control whether or not the job will be used when computing quality metrics.true or false
isVisible(optional)Used to hide labeling jobs from labelers.true or false

Labeling job type mapping

Labeling job typemlTask
Object detectionOBJECT_DETECTION
Semantic segmentationOBJECT_DETECTION
Object relationOBJECT_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 four 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 Multiple choices dropdown input type.
  • In the asset viewer, only the first transcription sub-job is visible in label tags. To make sure that you always have full visibility of the most important sub-jobs, you can change the order of transcription sub-jobs from the project JSON.