Schema Reference

JSON Schema 2020-12 definitions for all data files.

File Structure

Each pilgrimage route is a directory with five files:

routes/{route-id}/
  metadata.json        # Overview, tradition, culture, logistics
  route.geojson        # GeoJSON FeatureCollection (LineString)
  stages.json          # Stage-by-stage breakdown
  waypoints.geojson    # GeoJSON FeatureCollection (Points)
  stats.json           # Historical statistics with sources

Plus index.json at the repo root as the discovery file.

Schemas

Schema	Validates	Source
`index.schema.json`	`index.json`	View
`pilgrimage.schema.json`	`metadata.json`	View
`stages.schema.json`	`stages.json`	View
`route.schema.json`	`route.geojson`	View
`waypoints.schema.json`	`waypoints.geojson`	View
`way.schema.json`	`ways/stage-NN.json`	View
`way-route.schema.json`	`ways/route.json`	View
`way-report.schema.json`	`ways/report.json`	View
None yet	`stats.json`	No schema validates this file yet — a known gap. `schema/` has no `stats.schema.json`.

Conventions

Coordinates

GeoJSON standard: [longitude, latitude] or [longitude, latitude, altitude]. Altitude in meters.

Localized Strings

All human-readable text uses the LocalizedString pattern. English is always required.

{
  "en": "Camino de Santiago",
  "es": "Camino de Santiago",
  "ja": "サンティアゴ巡礼路"
}

Route Topologies

Value	Meaning	Example
`linear`	A-to-B route	Camino Frances
`circular`	Loop returning to start	No route declares it today. The Shikoku 88 is a loop, but it is a pilgrimage of four sections, each of them `linear`; the loop is recorded as `pilgrimage.circular` on all four
`network`	Interconnected sub-routes	Kumano Kodo

Waypoint Types

15 types covering diverse pilgrimage traditions:

Type	Description
`town`	Settlement, village, city
`accommodation`	Place to sleep (albergue, temple lodging, ryokan, etc.)
`sacred_site`	Temple, church, shrine, chapel
`water_source`	Fountain, spring, tap
`credential_stamp`	Stamp/seal location
`viewpoint`	Scenic overlook
`food`	Restaurant, cafe, market
`medical`	Hospital, pharmacy, clinic
`transport`	Bus stop, train station, ferry
`waymarker`	Trail marker, milestone
`cultural_site`	Museum, monument, heritage site
`camping`	Designated camping area
`pass`	Mountain pass or summit
`information`	Tourist office, info board
`supply`	Shop, supermarket, ATM

Schema Versioning

Every data file includes a schemaVersion field following SemVer:

Change	Version Bump	Example
Field removed or renamed	MAJOR	1.0.0 → 2.0.0
New optional field added	MINOR	1.0.0 → 1.1.0
Content correction	PATCH	1.0.0 → 1.0.1

Read the catalog from @main, then pin every file you download to the tag its release field names — see Usage. The @v1 alias is no longer maintained. All schemas use additionalProperties: true for forward compatibility.