{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailpaint.org/schemas/project-v3.schema.json",
  "title": "TrailPaint Project (.trailpaint.json) — covers versions 1-4, current 3.1",
  "description": "A hand-drawn trail map story: a named geographic narrative with numbered spots (景點), routes (路線), optional historical basemaps (overlay), photos with CC attribution (photoMeta), and scripture/historical references. Produced by the TrailPaint editor and consumed by its Player; designed to be generated by LLMs and consumed by AI agents. An exported .trailpaint.json may also include schema.org-compatible JSON-LD fields (`@context`, `@type`, `itinerary`) alongside the native structure for AI discoverability. NOTE: `spots` and `routes` are authoritative; the optional `itinerary` mirror is provided for AI agents — any conflict between `itinerary[i]` and `spots[i]` MUST be resolved in favor of `spots[i]`. The `@context`, `@type`, and `itinerary` fields are stripped on import.",
  "type": "object",
  "required": ["version", "name", "center", "zoom", "spots", "routes"],
  "additionalProperties": true,
  "properties": {
    "version": {
      "description": "Schema version. v3 is current stable; v4 adds Spot.pendingLocation. Importers auto-migrate 1-3 to the runtime version.",
      "type": "integer",
      "enum": [1, 2, 3, 4]
    },
    "name": {
      "description": "Human-readable project / story title.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "center": {
      "$ref": "#/$defs/LatLng",
      "description": "Initial map center [latitude, longitude]. Used when the file is first opened."
    },
    "zoom": {
      "description": "Initial Leaflet zoom level (1 = world, 19 = street).",
      "type": "number",
      "minimum": 0,
      "maximum": 22
    },
    "basemapId": {
      "description": "Identifier of the active base tile layer (e.g. 'osm', 'protomaps-light', 'taiwan-map'). See the `/app/` basemap switcher for the current catalog.",
      "type": "string"
    },
    "music": {
      "$ref": "#/$defs/MusicSetting",
      "description": "Optional background music for Story Player playback."
    },
    "overlay": {
      "$ref": "#/$defs/OverlaySetting",
      "description": "Optional historical tile overlay (e.g. CCTS Tang/Song/Yuan/Ming-era China, DARE Roman-era Mediterranean)."
    },
    "spots": {
      "description": "Numbered story points (景點). Rendered as pins + cards on the map.",
      "type": "array",
      "items": { "$ref": "#/$defs/Spot" }
    },
    "routes": {
      "description": "Hand-drawn or imported polylines connecting spots. Each route is one continuous line.",
      "type": "array",
      "items": { "$ref": "#/$defs/Route" }
    },
    "@context": {
      "description": "Optional JSON-LD context. When present, TrailPaint exports set this to a mixed vocab mapping (schema.org + trailpaint) so AI agents can semantically interpret the document. Ignored on import.",
      "oneOf": [
        { "type": "string" },
        { "type": "object" },
        { "type": "array" }
      ]
    },
    "@type": {
      "description": "Optional JSON-LD type. TrailPaint exports typically set this to 'TouristTrip'. Ignored on import.",
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ]
    },
    "itinerary": {
      "description": "Optional schema.org-style mirror of `spots`. Accepts either a bare Place[] array (simpler JSON-LD) or an ItemList object with `itemListElement[]` (preferred, produced by TrailPaint exporter). Ignored on import; the authoritative spot data lives in `spots`.",
      "oneOf": [
        { "type": "array" },
        { "type": "object" }
      ]
    }
  },
  "$defs": {
    "LatLng": {
      "description": "[latitude, longitude] tuple. Latitude -90..90, longitude -180..180. Enforced length=2 via `prefixItems` + `items:false` (2020-12) plus `minItems:2`; no legacy `maxItems` since `items:false` already caps upper bound.",
      "type": "array",
      "minItems": 2,
      "prefixItems": [
        { "type": "number", "minimum": -90, "maximum": 90 },
        { "type": "number", "minimum": -180, "maximum": 180 }
      ],
      "items": false
    },
    "Spot": {
      "description": "A numbered story point on the map.",
      "type": "object",
      "required": ["id", "latlng", "num", "title", "desc", "iconId", "cardOffset"],
      "additionalProperties": true,
      "properties": {
        "id": {
          "description": "Stable unique ID within this project. Typically 's1', 's2', ... or a slug.",
          "type": "string",
          "minLength": 1
        },
        "latlng": {
          "$ref": "#/$defs/LatLng",
          "description": "Pin location [latitude, longitude]."
        },
        "num": {
          "description": "Display number shown on the pin (1-indexed visit order).",
          "type": "integer",
          "minimum": 1
        },
        "title": {
          "description": "Short spot name (place / event / person).",
          "type": "string",
          "maxLength": 120
        },
        "desc": {
          "description": "Description / story paragraph for this spot. May include inline `📷 作者, 授權 — 來源` attribution lines for embedded photos (pre-013 convention). Supports \\n line breaks.",
          "type": "string"
        },
        "photo": {
          "description": "Embedded photo as a base64 data URL (typically resized/compressed), or null if no photo. External URLs are not auto-fetched at render time for privacy/offline reasons.",
          "type": ["string", "null"]
        },
        "iconId": {
          "description": "Icon key from the TrailPaint ICONS catalog (e.g. 'church', 'peak', 'coffee', 'camera', 'food', 'building', 'home'). See /app/ icon picker for the full list.",
          "type": "string"
        },
        "cardOffset": {
          "description": "Pixel offset of the info-card from the pin (screen coordinates). Default {x: 0, y: -60}.",
          "type": "object",
          "required": ["x", "y"],
          "properties": {
            "x": { "type": "number" },
            "y": { "type": "number" }
          }
        },
        "scripture_refs": {
          "description": "Optional Bible references for scripture-based stories (e.g. ['Acts 13:4-12', 'Matt 16:13-20']). Format: free text but USFM-like book abbreviations are preferred for downstream parsing.",
          "type": "array",
          "items": { "type": "string" }
        },
        "pendingLocation": {
          "description": "v4+. True when a photo was imported without GPS and the spot needs the user to drag the pin to its real location. Exporters may strip this.",
          "type": "boolean"
        },
        "photo_query": {
          "description": "v3.1+. LLM-generated search keywords used by TrailPaint to auto-fetch a representative photo from Wikimedia Commons on import. Format: '中文關鍵字 | English keywords' (pipe-separated bilingual). Consumed and removed during import when the auto-fetch option is enabled.",
          "type": "string"
        },
        "photoMeta": {
          "$ref": "#/$defs/PhotoMeta",
          "description": "v3.1+. CC attribution metadata for the embedded photo, populated by the Commons auto-fetch pipeline."
        }
      }
    },
    "PhotoMeta": {
      "description": "Attribution metadata for a CC-licensed photo (Wikimedia Commons). Rendered as small text under the photo in Player/Editor.",
      "type": "object",
      "required": ["source", "license", "author", "sourceUrl"],
      "additionalProperties": false,
      "properties": {
        "source": {
          "description": "Origin of the photo. Currently only 'wikimedia-commons'; may extend in future.",
          "type": "string",
          "enum": ["wikimedia-commons"]
        },
        "license": {
          "description": "License identifier (e.g. 'CC BY-SA 4.0', 'CC BY 2.0', 'Public Domain').",
          "type": "string"
        },
        "author": {
          "description": "Attribution string (author / uploader name).",
          "type": "string"
        },
        "authorUrl": {
          "description": "URL to the author page. Only kept when the URL is on *.wikimedia.org or *.wikipedia.org; otherwise null (strict allow-list).",
          "oneOf": [
            { "type": "string", "format": "uri" },
            { "type": "null" }
          ]
        },
        "sourceUrl": {
          "description": "URL to the Commons File: page (required for CC compliance).",
          "type": "string",
          "format": "uri"
        }
      }
    },
    "Route": {
      "description": "A drawn polyline connecting one or more points.",
      "type": "object",
      "required": ["id", "name", "pts", "color"],
      "additionalProperties": true,
      "properties": {
        "id": {
          "description": "Stable unique ID within this project.",
          "type": "string",
          "minLength": 1
        },
        "name": {
          "description": "Display name. Auto-filled via reverse geocoding when drawn; can be manually edited.",
          "type": "string"
        },
        "pts": {
          "description": "Polyline points as [latitude, longitude] pairs, in draw order.",
          "type": "array",
          "minItems": 2,
          "items": { "$ref": "#/$defs/LatLng" }
        },
        "color": {
          "description": "Route color key. One of: 'orange', 'blue', 'green', 'red', 'purple'.",
          "type": "string",
          "enum": ["orange", "blue", "green", "red", "purple"]
        },
        "elevations": {
          "description": "Per-point elevation in meters (same length as pts), or null if no elevation data. Fetched from Open-Meteo during draw; may be absent in AI-generated routes.",
          "oneOf": [
            { "type": "array", "items": { "type": "number" } },
            { "type": "null" }
          ]
        }
      }
    },
    "OverlaySetting": {
      "description": "Historical tile overlay settings.",
      "type": "object",
      "required": ["id", "opacity"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Overlay catalog key (e.g. 'han_bc7' 西漢, 'song_1208' 南宋, 'ad0741' 唐代, 'rome_200' 羅馬). See overlays.ts for the full catalog.",
          "type": "string"
        },
        "opacity": {
          "description": "Overlay opacity, 0..1.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "MusicSetting": {
      "description": "Background music configuration for Story Player.",
      "type": "object",
      "required": ["url", "autoplay"],
      "additionalProperties": false,
      "properties": {
        "url": {
          "description": "Audio file URL. Typically CC-BY Incompetech track or user-supplied.",
          "type": "string",
          "format": "uri"
        },
        "autoplay": {
          "description": "Whether to autoplay on Player load. Browser autoplay policies may still block without user gesture.",
          "type": "boolean"
        }
      }
    }
  }
}