Configuration Files

The build process is controlled by three main JSON configuration files. Understanding these files is key to understanding how the timezone boundaries are created and to contributing changes.

timezones.json

This is the master file that defines the recipe for building each timezone boundary. It's an object where each key is a timezone identifier (e.g., "America/Chicago") and the value is an array of operations.

Each operation in the array is an object with the following keys:

  • op: The geometric operation to perform (init, union, difference, intersect, difference-reverse-order).
  • source: The type of data source (overpass, manual-polygon, manual-multipolygon, final).
  • id or data: The identifier for the source (from osmBoundarySources.json or another timezone) or the raw coordinate data for manual geometries.
  • description: A required string explaining the purpose of any manual geometry.

Example: America/Chicago

{
  "America/Chicago": [
    {
      "op": "init",
      "source": "overpass",
      "id": "America-Chicago-tz"
    }, {
      "op": "difference",
      "source": "manual-polygon",
      "data": [[[-85.2,32.97],[-85.237,32.954],[-85.282,32.847],[-85.235,32.765],[-85.198,32.656],[-85.182,32.571],[-85.214,32.514],[-85.119,32.444],[-85.094,32.397],[-85.073,32.355],[-85.031,32.339],[-85.02,32.3429],[-85.011,32.358],[-84.86,32.35],[-85.2,32.97]]],
      "description": "Omit a few towns in Alabama close to Georgia that observe eastern time"
    }
  ]
}

This configuration initializes the America/Chicago timezone using a boundary from OpenStreetMap and then subtracts a manually defined polygon to account for a local time variation in Alabama.

osmBoundarySources.json

This file defines the data to be downloaded from OpenStreetMap via the Overpass API. Each key in this object is a unique ID that can be referenced from timezones.json. The value is an object specifying the OSM tags to query.

Example:

{
  "Africa-Abidjan-tz": {
    "timezone": "Africa/Abidjan"
  },
  "Australia": {
    "ISO3166-1": "AU"
  }
}

This tells the script to download:

  1. The OSM relation with the tag timezone equal to Africa/Abidjan.
  2. The OSM relation with the tag ISO3166-1 equal to AU (the boundary for Australia).

expectedZoneOverlaps.json

The validation process flags any overlaps between timezone boundaries. However, some overlaps are expected, particularly in disputed territories. This file lists the allowed overlaps.

Each key is a combination of two timezone IDs, and the value is an array of objects, each defining an acceptable bounding box for an overlap.

Example:

{
  "Africa/Juba-Africa/Khartoum": [
    {
      "bounds": [27.8, 9.3, 29.1, 10.2],
      "description": "Allow disputed Abyei Area (https://en.wikipedia.org/wiki/Abyei) to overlap."
    }, {
      "bounds": [23.4, 8.6, 24.9, 9.9],
      "description": "Allow disputed Kafia Kingi region (https://en.wikipedia.org/wiki/Kafia_Kingi) to overlap."
    }
  ]
}

This configuration tells the validator to ignore any overlaps between Africa/Juba and Africa/Khartoum that fall within the specified bounding boxes for the Abyei Area and Kafia Kingi region.