The .maxtopia file format

Portable program description as UTF-8 JSON. Version 1. Round-trips through Maxtopia byte-identical after canonicalization. Released under CC0 1.0 (public domain) — build your own reader or writer without asking.

Design goals

Portable. One file per program. Send it through iMessage, email, anywhere. Import it anywhere you can parse JSON.
Stable. Every field on the wire has a fixed name and meaning. Round-trip is byte-identical after canonicalization.
Small. Only what's needed to describe the program — no client-side preferences, no user identity, no history.
Yours. Public domain. No attribution required. If you build something on it, we'd love to hear about it.

Shape

{
  "format": "maxtopia",
  "version": 1,
  "program": {
    "id": "01JABCDEF00000000000000000",
    "name": "5x5 Linear Progression",
    "description": "Simple linear progression; add weight each session.",
    "weeks": 12,
    "days": [
      {
        "day_of_week": 1,
        "name": "Squat A",
        "exercises": [
          {
            "exercise_id": "ex.back_squat",
            "sets": [
              { "reps": 5, "weight_kg": 100 },
              { "reps": 5, "weight_kg": 102.5, "rpe": 7 },
              { "reps": 5, "weight_kg": 105, "rpe": 8 }
            ],
            "rest_seconds": 180
          }
        ]
      },
      {
        "day_of_week": 3,
        "name": "Bench A",
        "exercises": [
          {
            "name": "Bench Press",
            "sets": [
              { "reps": 5, "percent_1rm": 0.80 },
              { "reps": 5, "percent_1rm": 0.82 },
              { "reps": 5, "percent_1rm": 0.85 }
            ],
            "notes": "Pause 1s at chest"
          }
        ]
      }
    ]
  }
}

Rules

format MUST be the string "maxtopia".
version MUST be the integer 1. Readers reject unknown versions.
program.id, program.name, program.weeks, program.days are required.
program.description is optional.
day_of_week is an integer 0..6, Sunday = 0.
Each exercise MUST have exercise_id OR name.
Each set has reps (required, non-negative integer) and optionally weight_kg, rpe, or percent_1rm.
Weights are canonicalized to kilograms; clients convert on display.
Writers MUST emit a canonical field order so write(read(x)) === write(x).
Fields the reader doesn't understand are dropped, not silently forwarded. The reference reader will not preserve unknown keys.

TypeScript reference types

A minimal, zero-dependency reader and writer. Copy freely.

// maxtopia.ts — read and write .maxtopia files. Zero dependencies.
// Works in modern browsers, Cloudflare Workers, and Node 20+. Public domain.
// Spec: https://maxtopia.app/file-format

export interface MaxtopiaFile {
  format: 'maxtopia';
  version: 1;
  program: MaxtopiaProgram;
}

export interface MaxtopiaProgram {
  id: string;
  name: string;
  description?: string;
  weeks: number;
  days: MaxtopiaDay[];
}

export interface MaxtopiaDay {
  day_of_week: 0 | 1 | 2 | 3 | 4 | 5 | 6; // Sunday = 0
  name: string;
  exercises: MaxtopiaExercise[];
}

export interface MaxtopiaExercise {
  exercise_id?: string;
  name?: string;
  sets: MaxtopiaSet[];
  rest_seconds?: number;
  notes?: string;
}

export interface MaxtopiaSet {
  reps: number;
  weight_kg?: number;
  rpe?: number;
  percent_1rm?: number;
}

License

The .maxtopia format is released into the public domain under CC0 1.0. Do whatever you want with it. No attribution required.