Wiki menu

JSON schemas

Index of every JSON schema for mod files: which file each one validates, what it is for, where to get it, and how to use it in an editor.

Last updated for v0.5.35
On this page

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

SchemaValidatesWhat it is for
mod_manifest.schema.jsonmod.jsonThe mod’s identity, version, dependencies, load order, permissions and entrypoints.

Scenario

SchemaValidatesWhat it is for
mod_scenario_header.schema.jsonscenario.jsonThe 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.jsoncountries_add.jsonCountries the scenario adds.
mod_scenario_countries_remove.schema.jsoncountries_remove.jsonISO3 codes of countries the scenario removes.
mod_scenario_countries_state.schema.jsoncountries_state.jsonStarting economy, politics and diplomacy values of existing countries.
mod_scenario_diplomacy.schema.jsondiplomacy.jsonStarting alliance organisations, alliances, treaties, wars and relations.
mod_scenario_provinces_ownership.schema.jsonprovinces_ownership.jsonWho owns each province or region at the start.
mod_scenario_provinces_data.schema.jsonThe file named by provinceDataFile in scenario.jsonPer-province population, terrain and resources.
mod_scenario_units_define.schema.jsonunits_define.jsonUnit types the scenario defines.
mod_scenario_units_deploy_armies.schema.jsonunits_deploy_armies.jsonArmies on the map at the start.
mod_scenario_units_deploy_fleets.schema.jsonunits_deploy_fleets.jsonFleets at the start.
mod_scenario_units_deploy_air.schema.jsonunits_deploy_air.jsonAir wings at the start.
mod_scenario_victory.schema.jsonThe file named by victoryFile in scenario.jsonThe scenario’s own endings, extra end-screen rows, and a switch for the base victories.
national_goals.schema.jsonThe file named by nationalGoalsFile in scenario.jsonPer-country national goals.
mod_currencies.schema.jsonContent/currencies.json, or the file named by currenciesFile in scenario.jsonThe currencies money is displayed in. Display only.

Content

SchemaValidatesWhat it is for
mod_content_envelope.schema.jsonThe whole of Content/buildings.json, Content/units.json and Content/resources.jsonThe shape of a content file: a list of entries, or an object that wraps the list.
building_type.schema.jsonOne entry of Content/buildings.jsonA building.
unit_type.schema.jsonOne entry of Content/units.jsonA unit type.
resource_type.schema.jsonOne entry of Content/resources.jsonA resource or good.
event.schema.jsonOne event in Content/events/*.jsonAn event: its trigger, conditions, options and effects.
mod_research_tracks.schema.jsonContent/research_tracks.jsonResearch tracks a mod adds beside the Knowledge Network.
mod_specialists.schema.jsonContent/specialists.jsonNamed scientists and engineers a country can employ.
mod_demography_seeds.schema.jsonContent/demography/seeds.jsonPer-country starting age structure, life expectancy and fertility.
mod_demography_model.schema.jsonContent/demography/model.jsonSections of the demography model to replace, such as a life table.

Interface

SchemaValidatesWhat it is for
mod_ui_theme.schema.jsonContent/ui/theme.jsonThe HUD theme. See HUD theming.
mod_ui_layout.schema.jsonContent/ui/layout.jsonWhich HUD slots the mod replaces or hides. See HUD layout.
mod_ui_hud_trackers.schema.jsonContent/ui/hud_trackers.jsonGauges 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.

SchemaValidatesWhat it is for
game_settings.schema.jsonoverrides/game_settings.json. Its events and envoys sections also validate overrides/events.json and overrides/envoys.json.The game’s balance settings.
doctrines.schema.jsonoverrides/doctrines.jsonThe Knowledge Network: branches, tiers and doctrines.
laws.schema.jsonoverrides/laws.jsonLaw categories and their options.
interest_groups.schema.jsonoverrides/interest_groups.jsonInterest groups, age bands and their political leanings.

Reference only

SchemaDescribesWhy it is here
country.schema.jsonThe base game’s country recordNot a mod file. Read it to see the fields that countries_add.json mirrors.
tech_tree.schema.jsonContent/tech_tree.jsonThe 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:

  1. Copy the schemas folder into your mod’s working folder, from the game’s StreamingAssets/modding/schemas/ or from the online repository. Keep the files together: mod_scenario_header.schema.json refers to the other scenario schemas by file name.

  2. Create .vscode/settings.json in 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" }
      ]
    }
  3. 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.json and the event files describe one entry, not the whole file. Use mod_content_envelope.schema.json for 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.

Play Global Protocol: New World Order

Out now in Early Access on Steam, with online multiplayer for 2–8 players.