Open Itinerary

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.

It's to travel plans what iCalendar is to events: boring, useful, and open.

Design highlights

🎯

Every stop has a `goal`

A goal captures not just where you're going, but why you're going there, and a goal like “Scenic viewpoint — stretch and take photos” forces AI agents to be explicit about intent.

📍

Coords are a cache, not truth

AI agents hallucinate lat/lng, so 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 from each day, so there is no duplication when a stop appears in multiple days.

🔁

Alternatives are first-class

Stop-level alts suggest replacements (“instead of this restaurant, try that one”), and day-level flex blocks let you choose among options (“choose N of these”).

⏱

Duration ranges, not fixed times

dur: {min: 1.5, max: 2.5} acknowledges that travel is uncertain, and fixed times are reserved for when they truly matter (flights, reservations).

Example

Visual view

Quick start

Validate any itinerary against the schema:

pip install jsonschemacopy

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')"copy

Then geocode it (adds real coordinates from OpenStreetMap):

python geocode.py your-trip.jsoncopy

Validator

Paste an Open Itinerary JSON below and validate it:

Geocode stops