v0.2 alpha

Open Itinerary

An open, token-efficient JSON format for travel plans, designed for AI agents to output and apps to consume.


What it is

A data model for travel plans, validated by a JSON Schema, with no library, no SDK, and no lock-in. Validate it with any JSON Schema validator in any language.

Files use the extension .oitinerary.json and the MIME type application/vnd.open-itinerary+json.

Also available as KDL variant (.oitinerary.kdl) for token-efficient AI generation โ€” 55% fewer total tokens versus JSON.


Design highlights

๐Ÿ˜

Every stop has a goal

A goal captures not just where you're going, but why โ€” and it forces AI agents to be explicit about intent.

๐Ÿ“

Coords are a cache, not truth

The name (and addr) is authoritative; coordinates are added by a geocoder post-generation.

โšก

Token-efficient by design

Abbreviated keys like tz, dur, and cat save 25-35% output tokens versus verbose JSON.

๐Ÿ“„

Flat catalogs, not deep nesting

Stops and routes are top-level, referenced by id โ€” no duplication when a stop appears in multiple days.

๐Ÿ—ก

Alternatives are first-class

Stop-level alts suggest replacements; day-level flex blocks let you choose among options.

โฑ}

Duration ranges, not fixed times

dur: {min: 1.5, max: 2.5} acknowledges travel is uncertain; fixed times for when they truly matter.


Example

{
  "$schema": "https://raw.githubusercontent.com/ThatXliner/open-itin/main/open-itin.schema.json",
  "version": "0.2",
  "name": "SF to LA Road Trip",
  "summary": "A 3-day coastal road trip from San Francisco to Los Angeles via Highway 1.",
  "tags": [
    "road-trip",
    "coastal",
    "california"
  ],
  "tz": "America/Los_Angeles",
  "cur": "USD",
  "stops": [
    {
      "id": "sf",
      "name": "San Francisco",
      "goal": "Start the trip โ€” fuel up and hit the coast",
      "cat": "other",
      "addr": "San Francisco, CA 94102"
    },
    {
      "id": "monterey",
      "name": "Monterey Bay Aquarium",
      "goal": "See the sea otters and kelp forest",
      "cat": "attraction",
      "addr": "886 Cannery Row, Monterey, CA 93940",
      "dur": {
        "min": 1.5,
        "max": 2.5
      },
      "cost": {
        "amt": 65
      },
      "alts": [
        {
          "name": "Monterey State Beach",
          "goal": "Free alternative โ€” walk the beach instead",
          "cat": "nature"
        }
      ]
    },
    {
      "id": "half-moon-bay",
      "name": "Half Moon Bay State Beach",
      "goal": "Walk the beach and decompress โ€” first coastal stop",
      "cat": "nature",
      "addr": "Half Moon Bay, CA 94019",
      "dur": {
        "min": 0.5,
        "max": 1.5
      }
    },
    {
      "id": "santa-cruz",
      "name": "Santa Cruz Boardwalk",
      "goal": "Stretch, grab a snack, catch the sunset over the boardwalk",
      "cat": "attraction",
      "addr": "400 Beach St, Santa Cruz, CA 95060",
      "dur": {
        "min": 1,
        "max": 2
      }
    },
    {
      "id": "big-sur-inn",
      "name": "Big Sur River Inn",
      "goal": "Overnight stay โ€” creekside rooms in the heart of Big Sur",
      "cat": "accommodation",
      "addr": "46800 CA-1, Big Sur, CA 93920",
      "cost": {
        "amt": 280
      }
    },
    {
      "id": "bixby-bridge",
      "name": "Bixby Creek Bridge",
      "goal": "The iconic Big Sur viewpoint โ€” pull over, full stop",
      "cat": "viewpoint",
      "addr": "Bixby Creek Bridge, CA-1, Big Sur, CA 93920",
      "dur": {
        "min": 0.25,
        "max": 0.5
      }
    },
    {
      "id": "hearst-castle",
      "name": "Hearst Castle",
      "goal": "Tour the most absurd private home in American history",
      "cat": "attraction",
      "addr": "750 Hearst Castle Rd, San Simeon, CA 93452",
      "dur": {
        "min": 2,
        "max": 4
      },
      "cost": {
        "amt": 30
      }
    },
    {
      "id": "santa-barbara",
      "name": "Santa Barbara Inn",
      "goal": "Overnight stay with ocean views",
      "cat": "accommodation",
      "addr": "901 E Cabrillo Blvd, Santa Barbara, CA 93103",
      "cost": {
        "amt": 350
      }
    },
    {
      "id": "santa-monica",
      "name": "Santa Monica Pier",
      "goal": "End of the road โ€” touch the Route 66 sign, get the photo",
      "cat": "attraction",
      "addr": "200 Santa Monica Pier, Santa Monica, CA 90401",
      "dur": {
        "min": 0.5,
        "max": 2
      }
    }
  ],
  "routes": [
    {
      "id": "sf-to-halfmoon",
      "from": "sf",
      "to": "half-moon-bay",
      "mode": "drive",
      "dur": {
        "min": 0.5,
        "max": 0.75
      },
      "dist": 45
    },
    {
      "id": "halfmoon-to-santacruz",
      "from": "half-moon-bay",
      "to": "santa-cruz",
      "mode": "drive",
      "dur": {
        "min": 0.75,
        "max": 1.25
      },
      "dist": 75
    },
    {
      "id": "santacruz-to-bigsur",
      "from": "santa-cruz",
      "to": "big-sur-inn",
      "mode": "drive",
      "dur": {
        "min": 1.25,
        "max": 2
      },
      "dist": 110
    },
    {
      "id": "bigsur-to-hearst",
      "from": "big-sur-inn",
      "to": "hearst-castle",
      "mode": "drive",
      "dur": {
        "min": 1.5,
        "max": 2.5
      },
      "dist": 100
    },
    {
      "id": "hearst-to-sb",
      "from": "hearst-castle",
      "to": "santa-barbara",
      "mode": "drive",
      "dur": {
        "min": 2,
        "max": 3
      },
      "dist": 170
    },
    {
      "id": "sb-to-sm",
      "from": "santa-barbara",
      "to": "santa-monica",
      "mode": "drive",
      "dur": {
        "min": 1.5,
        "max": 3
      },
      "dist": 150
    }
  ],
  "days": [
    {
      "date": "2026-06-15",
      "note": "SF to Big Sur",
      "items": [
        {
          "type": "stop",
          "ref": "sf"
        },
        {
          "type": "route",
          "ref": "sf-to-halfmoon"
        },
        {
          "type": "stop",
          "ref": "half-moon-bay"
        },
        {
          "type": "route",
          "ref": "halfmoon-to-santacruz"
        },
        {
          "type": "stop",
          "ref": "santa-cruz"
        },
        {
          "type": "route",
          "ref": "santacruz-to-bigsur"
        },
        {
          "type": "stop",
          "ref": "big-sur-inn"
        }
      ]
    },
    {
      "date": "2026-06-16",
      "note": "Big Sur to Santa Barbara",
      "items": [
        {
          "type": "stop",
          "ref": "bixby-bridge"
        },
        {
          "type": "route",
          "ref": "bigsur-to-hearst"
        },
        {
          "type": "stop",
          "ref": "hearst-castle"
        },
        {
          "type": "route",
          "ref": "hearst-to-sb"
        },
        {
          "type": "stop",
          "ref": "santa-barbara"
        },
        {
          "type": "flex",
          "pick": 1,
          "opts": [
            {
              "type": "note",
              "txt": "Wine tasting in the Funk Zone"
            },
            {
              "type": "note",
              "txt": "Walk State Street for shopping"
            }
          ]
        }
      ]
    },
    {
      "date": "2026-06-17",
      "note": "Santa Barbara to LA",
      "items": [
        {
          "type": "route",
          "ref": "sb-to-sm"
        },
        {
          "type": "stop",
          "ref": "santa-monica"
        }
      ]
    }
  ],
  "generated_by": "claude-sonnet-4",
  "created_at": "2026-05-11T10:00:00Z"
}

Visual view

Day 1 โ€” 2026-06-15
SF to Big Sur
San Francisco
Start the trip โ€” fuel up and hit the coast
Drive
San Francisco Half Moon Bay State Beach
0.5hโ€“0.75hยท 45km
Half Moon Bay State Beach
Walk the beach and decompress โ€” first coastal stop
0.5hโ€“1.5h
Drive
Half Moon Bay State Beach Santa Cruz Boardwalk
0.75hโ€“1.25hยท 75km
Santa Cruz Boardwalk
Stretch, grab a snack, catch the sunset over the boardwalk
1hโ€“2h
Drive
Santa Cruz Boardwalk Big Sur River Inn
1.25hโ€“2hยท 110km
Big Sur River Inn
Overnight stay โ€” creekside rooms in the heart of Big Sur
Day 2 โ€” 2026-06-16
Big Sur to Santa Barbara
Bixby Creek Bridge
The iconic Big Sur viewpoint โ€” pull over, full stop
0.25hโ€“0.5h
Drive
Big Sur River Inn Hearst Castle
1.5hโ€“2.5hยท 100km
Hearst Castle
Tour the most absurd private home in American history
2hโ€“4h
Drive
Hearst Castle Santa Barbara Inn
2hโ€“3hยท 170km
Santa Barbara Inn
Overnight stay with ocean views
Choose 1 pick 1
Wine tasting in the Funk Zone
Walk State Street for shopping
Day 3 โ€” 2026-06-17
Santa Barbara to LA
Drive
Santa Barbara Inn Santa Monica Pier
1.5hโ€“3hยท 150km
Santa Monica Pier
End of the road โ€” touch the Route 66 sign, get the photo
0.5hโ€“2h

Quick start

Validate any itinerary against the schema:

pip install jsonschema
python -c "import json, jsonschema; schema = json.load(open('open-itin.schema.json')); data = json.load(open('your-trip.json')); jsonschema.validate(data, schema); print('Valid')"

Then geocode it (adds real coordinates from OpenStreetMap):

python geocode.py your-trip.json

Validator

Paste a JSON or KDL itinerary below and validate it: