Every JSON file a mod ships has a JSON Schema (draft-07) that describes its fields, their types and their allowed values. The Mod Builder builds its editors from these schemas and its VALIDATE check uses them, so a file that passes the schema is a file the editor can open. Point your own editor at them and you get validation and autocomplete while you type.
Where the schemas are
- In the game. The game ships all of them in the
StreamingAssets/modding/schemas/folder of its data folder. These copies always match the game you are running. - Online. The example mod’s public repository carries a copy of each one. The links in the tables below go there. If an online copy and the copy in your game folder differ, use the one in your game folder.
In the tables, <name> in a link stands for the schema’s file name. Paths are relative to the mod folder. Scenario files sit in the scenario folder, which is scenario/ unless mod.json names another one.
Manifest
| Schema | Validates | What it is for |
|---|---|---|
mod_manifest.schema.json | mod.json | The mod’s identity, version, dependencies, load order, permissions and entrypoints. |
Scenario
| Schema | Validates | What it is for |
|---|---|---|
mod_scenario_header.schema.json | scenario.json | The scenario’s required header: its id, start date, switches, and the names of its other files. It can also hold the other scenario sections inline. |
mod_scenario_countries_add.schema.json | countries_add.json | Countries the scenario adds. |
mod_scenario_countries_remove.schema.json | countries_remove.json | ISO3 codes of countries the scenario removes. |
mod_scenario_countries_state.schema.json | countries_state.json | Starting economy, politics and diplomacy values of existing countries. |
mod_scenario_diplomacy.schema.json | diplomacy.json | Starting alliance organisations, alliances, treaties, wars and relations. |
mod_scenario_provinces_ownership.schema.json | provinces_ownership.json | Who owns each province or region at the start. |
mod_scenario_provinces_data.schema.json | The file named by provinceDataFile in scenario.json | Per-province population, terrain and resources. |
mod_scenario_units_define.schema.json | units_define.json | Unit types the scenario defines. |
mod_scenario_units_deploy_armies.schema.json | units_deploy_armies.json | Armies on the map at the start. |
mod_scenario_units_deploy_fleets.schema.json | units_deploy_fleets.json | Fleets at the start. |
mod_scenario_units_deploy_air.schema.json | units_deploy_air.json | Air wings at the start. |
mod_scenario_victory.schema.json | The file named by victoryFile in scenario.json | The scenario’s own endings, extra end-screen rows, and a switch for the base victories. |
national_goals.schema.json | The file named by nationalGoalsFile in scenario.json | Per-country national goals. |
mod_currencies.schema.json | Content/currencies.json, or the file named by currenciesFile in scenario.json | The currencies money is displayed in. Display only. |
Content
| Schema | Validates | What it is for |
|---|---|---|
mod_content_envelope.schema.json | The whole of Content/buildings.json, Content/units.json and Content/resources.json | The shape of a content file: a list of entries, or an object that wraps the list. |
building_type.schema.json | One entry of Content/buildings.json | A building. |
unit_type.schema.json | One entry of Content/units.json | A unit type. |
resource_type.schema.json | One entry of Content/resources.json | A resource or good. |
event.schema.json | One event in Content/events/*.json | An event: its trigger, conditions, options and effects. |
mod_research_tracks.schema.json | Content/research_tracks.json | Research tracks a mod adds beside the Knowledge Network. |
mod_specialists.schema.json | Content/specialists.json | Named scientists and engineers a country can employ. |
mod_demography_seeds.schema.json | Content/demography/seeds.json | Per-country starting age structure, life expectancy and fertility. |
mod_demography_model.schema.json | Content/demography/model.json | Sections of the demography model to replace, such as a life table. |
Interface
| Schema | Validates | What it is for |
|---|---|---|
mod_ui_theme.schema.json | Content/ui/theme.json | The HUD theme. See HUD theming. |
mod_ui_layout.schema.json | Content/ui/layout.json | Which HUD slots the mod replaces or hides. See HUD layout. |
mod_ui_hud_trackers.schema.json | Content/ui/hud_trackers.json | Gauges the mod adds to the top bar. See HUD layout. |
The injection file (inject.json) has no schema. Its fields are listed on Adding buttons, rows and popups.
Rule overrides
Override files are sparse: you write only the keys you change. VALIDATE checks them without the schema’s required fields and reports a mismatch as a warning.
| Schema | Validates | What it is for |
|---|---|---|
game_settings.schema.json | overrides/game_settings.json. Its events and envoys sections also validate overrides/events.json and overrides/envoys.json. | The game’s balance settings. |
doctrines.schema.json | overrides/doctrines.json | The Knowledge Network: branches, tiers and doctrines. |
laws.schema.json | overrides/laws.json | Law categories and their options. |
interest_groups.schema.json | overrides/interest_groups.json | Interest groups, age bands and their political leanings. |
Reference only
| Schema | Describes | Why it is here |
|---|---|---|
country.schema.json | The base game’s country record | Not a mod file. Read it to see the fields that countries_add.json mirrors. |
tech_tree.schema.json | Content/tech_tree.json | The game does not read this file. Research is changed through overrides/doctrines.json and Content/research_tracks.json. |
Using a schema in your editor
Most editors that understand JSON Schema can attach a schema to a file by its path. In Visual Studio Code:
-
Copy the
schemasfolder into your mod’s working folder, from the game’sStreamingAssets/modding/schemas/or from the online repository. Keep the files together:mod_scenario_header.schema.jsonrefers to the other scenario schemas by file name. -
Create
.vscode/settings.jsonin the working folder and map each file to its schema:{ "json.schemas": [ { "fileMatch": ["/mod.json"], "url": "./schemas/mod_manifest.schema.json" }, { "fileMatch": ["/scenario/scenario.json"], "url": "./schemas/mod_scenario_header.schema.json" }, { "fileMatch": ["/scenario/countries_add.json"], "url": "./schemas/mod_scenario_countries_add.schema.json" }, { "fileMatch": ["/Content/ui/theme.json"], "url": "./schemas/mod_ui_theme.schema.json" }, { "fileMatch": ["/Content/ui/layout.json"], "url": "./schemas/mod_ui_layout.schema.json" }, { "fileMatch": ["/Content/ui/hud_trackers.json"], "url": "./schemas/mod_ui_hud_trackers.schema.json" }, { "fileMatch": ["/overrides/game_settings.json"], "url": "./schemas/game_settings.schema.json" } ] } -
Open one of the mapped files. The editor underlines fields the schema does not allow and offers field names and allowed values as you type.
Add one line for each file your mod has, using the tables above.
Do not add a $schema field to mod files. Several schemas, mod_manifest.schema.json among them, allow only the fields they list, so an extra $schema field is itself reported. Attach schemas through the editor’s settings instead.
Two things to keep in mind:
- The schemas for
Content/buildings.json,Content/units.json,Content/resources.jsonand the event files describe one entry, not the whole file. Usemod_content_envelope.schema.jsonfor the whole of a content file. - For the sparse override files, an editor that applies the full schema reports required fields you left out on purpose. The game does not require them.