individualization.json

individualization.json controls advanced processing behavior for variable replacement, solution deletion, warnings, file handling, artifact processors, and compatibility variation settings.

This file is optional. If it is missing, Divekit falls back to built-in defaults.

Minimal Example

{
  "variables": {
    "variableDelimiter": "$"
  }
}

Common Example

{
  "variables": {
    "variableDelimiter": "$",
    "values": {
      "semester": "SS2026"
    }
  },
  "solutionDeletion": {
    "enabled": true,
    "files": ["src/main/java/Solution.java"]
  },
  "warnings": {
    "enabled": true,
    "ignore": ["*.tmp"],
    "variationResidues": {
      "typeWhiteList": ["java", "md"],
      "ignoreList": ["UUID"],
      "matchMode": "word",
      "ignoreRules": [
        {
          "paths": ["src/test/java/**"],
          "values": ["Dish"]
        },
        {
          "values": ["Dish|Meal"],
          "matchMode": "regex"
        }
      ]
    }
  },
  "processors": {
    "uml": {
      "mode": "both",
      "imageFormat": "jpg"
    },
    "tableHash": {
      "solutionTableFileName": "${id}.solution.md",
      "hashedSolutionTableFileName": "${id}.hashed.md",
      "tableConfigFileName": "${id}.config.json"
    }
  }
}

Top-Level Keys

variables

This section controls token delimiters and fixed token values.

solutionDeletion

This section removes solution-only content before repositories are distributed.

warnings

This section controls warnings for unresolved tokens and leftover variation values.

fileManipulation

This section controls target-specific file and directory markers.

With the default values

{
  "filePreIdentifier": "_",
  "filePostIdentifier": "repo",
  "noRepoIdentifier": "no"
}

these built-in defaults produce the markers below. You only need to write fileManipulation when you want to override them.

the resulting markers are:

• _workrepo: include only for target work
• _evalrepo: include only for target eval
• _norepo: exclude from all generated repositories

The marker is removed from the final exported path.

Examples:

src/tests_evalrepo/HiddenTests.java -> src/tests/HiddenTests.java (eval only)
docs/teacher_workrepo.md            -> docs/teacher.md (work only)
assets/_norepo/logo.svg             -> excluded everywhere

Legacy compatibility:

• _mainrepo and _coderepo are still accepted and map to work
• _testrepo is still accepted and maps to eval
• older sandbox terminology may still appear in existing repositories, but eval is the canonical target name

processors

This section configures built-in artifact processors that run during individualization.

Currently supported:

{
  "processors": {
    "uml": {
      "mode": "both",
      "imageFormat": "jpg"
    },
    "tableHash": {
      "solutionTableFileName": "${id}.solution.md",
      "hashedSolutionTableFileName": "${id}.hashed.md",
      "tableConfigFileName": "${id}.config.json"
    }
  }
}

processors.uml

UML processing applies to .uxf and .uml files.

Default behavior:

• the individualized source UML file is kept
• an additional rendered image is emitted
• the default image format is jpg

Supported keys:

Supported modes:

• off: disables UML-specific artifact generation; the individualized source file remains
• source: keeps only the individualized UML source file
• image: emits only the rendered image artifact
• both: keeps the individualized UML source file and emits the rendered image artifact

Target markers from fileManipulation also apply to UML files. After marker removal, Divekit uses the cleaned path for every emitted UML artifact.

Examples with default settings:

docs/test1_evalrepo.uxf -> eval only: docs/test1.uxf + docs/test1.jpg
docs/test2_workrepo.uxf -> work only: docs/test2.uxf + docs/test2.jpg
docs/test3.uxf          -> both targets: docs/test3.uxf + docs/test3.jpg

Rendering modes image and both require UMLet to be available on the machine running Divekit.

processors.tableHash

Table hashing generates work-repository hash artifacts from eval-repository solution tables. It is useful when students fill Markdown table cells and tests should compare hashed expected values.

With the default naming convention, author these files:

src/main/resources/E1.md
src/test/resources/E1.solution_evalrepo.md
src/test/resources/E1.config.json

After target markers are resolved, Divekit reads E1.solution.md from the eval target, reads E1.config.json, and writes E1.hashed.md to the work target. This happens during divekit distribute and during file patches that affect the related work/eval repositories.

The ${id} placeholder is captured from the solution table file name and reused for the hashed output and config file names. Configure this section only when the default dot-suffix convention does not match your project:

{
  "processors": {
    "tableHash": {
      "solutionTableFileName": "E${id}-solution_testrepo.md",
      "hashedSolutionTableFileName": "E${id}-hashed-solution.md",
      "tableConfigFileName": "E${id}-config.json"
    }
  }
}

Table config files are separate from individualization.json and are resolved next to the solution table by default:

{
  "tableType": "ROWS_AND_COLUMNS",
  "explanationDimensions": ["Question"],
  "validRowValues": [],
  "validColumnValues": ["Question", "Answer"],
  "validCellValues": [],
  "hashedColumns": [false, true],
  "showRowHints": true,
  "showColumnHints": true
}

Columns are zero-based by position in the Markdown table. For ROWS_AND_COLUMNS, index 0 is the row-label column and the first answer column is index 1, matching the legacy Java table config. Unlisted positions are treated as false.

Before hashing, Divekit trims each comma-separated cell value, removes empty values, sorts the remaining values case-insensitively, joins them with commas, and lowercases the joined value unless caseSensitiveColumns marks that column as true.

relations

This section stores explicit object-relation metadata.

variableExtensions

This section customizes generated token names and transformation behavior.

variations

This section is the unified compatibility container for variation definitions. New standalone variation definitions usually belong in variation.json; keep inline variations only when you need compatibility with an existing setup.

Validation Notes

• variables.variableDelimiter must not be empty.
• If solutionDeletion.enabled is true, at least one file or directory must be configured.
• If warnings.enabled is true, warnings.ignore must be present.
• warnings.variationResidues.ignoreRules[].values must not be empty.
• warnings.variationResidues.matchMode must be substring, word, or identifierPart.
• warnings.variationResidues.ignoreRules[].matchMode may additionally be regex.
• processors.uml.mode must be off, source, image, or both.
• processors.uml.imageFormat must not be empty when image output is enabled.

warnings.variationResidues

Use this block to suppress leftover variation values that still appear after sample individualization, and to control the matching rules that also help divekit dev avoid related unresolved-token false positives.

Matching modes:

• substring: matches anywhere, including inside larger identifiers
• word: matches only whole words
• identifierPart: matches identifier parts such as Dish inside ovenDish

typeWhiteList should contain the complete set of file types you want Divekit to inspect. If you set it explicitly, include every extension you still want to scan, for example ["java", "md", "json"].

ignoreList is global. Entries may suppress either the residue value itself (for example Dish) or the surrounding word, identifier, or path fragment that produced the match (for example Feedback or coffee for a Fee residue hit). ignoreRules can be path-specific, or global when paths is omitted. Each rule must list the values it suppresses.

Example:

{
  "warnings": {
    "variationResidues": {
      "ignoreList": ["Dish", "Feedback", "coffee"],
      "ignoreRules": [
        {
          "paths": ["src/generated/**"],
          "values": ["GeneratedDish"]
        }
      ]
    }
  }
}

Legacy compatibility:

• variationResidues is the canonical key
• variationResidueWarnings is still accepted on read
• variableValueWarnings is deprecated and still accepted on read for backwards compatibility

Resolution Order

Divekit resolves unified individualization.json in this order:

1. .divekit/distributions/<distribution>/individualization.json
2. .divekit/individualization.json
3. ~/.divekit/individualization.json
4. built-in defaults

Variation definitions use a more detailed fallback because legacy variation.json files are still supported:

1. distribution individualization.json
2. distribution variation.json
3. project .divekit/individualization.json
4. project .divekit/variation.json
5. user ~/.divekit/individualization.json
6. built-in defaults with no variations

If variations is omitted, Divekit continues to the next source. Set it to an empty object to disable variations and stop fallback resolution:

{
  "version": "2.0",
  "variations": {}
}

Legacy Compatibility

Divekit still contains compatibility loading for these older files:

• originRepositoryConfig.json
• variationsConfig.json
• relationsConfig.json
• variableExtensionsConfig.json

For new setups, prefer a single individualization.json.

Scripting Clarification

Lua, shell, Python, Node, Deno, Java, and Kotlin execution belong to scripting and extensions, not to dedicated individualization.json keys.

Related pages:

• variation.json
• Configuration Keys
• Individualization