OpenTime/JSON Schema

JSON Schema

Validate your OpenTime files programmatically.

Schema URL

https://elysium.is/opentime/schemas/v0.2/opentime.json

What is the Schema?

The OpenTime JSON Schema is a machine-readable definition of the OpenTime format. It allows you to:

Validate .ot files against the spec
Get auto-completion in editors that support JSON Schema
Generate types for statically typed languages
Catch errors before runtime

Top-Level Structure

An OpenTime file is an array of items. Each item must have a type field that determines which schema definition applies.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "items": {
    "oneOf": [
      { "$ref": "#/$defs/goal" },
      { "$ref": "#/$defs/task" },
      { "$ref": "#/$defs/habit" },
      { "$ref": "#/$defs/reminder" },
      { "$ref": "#/$defs/event" },
      { "$ref": "#/$defs/appointment" },
      { "$ref": "#/$defs/project" }
    ]
  }
}

Using the Schema

In Your Editor

Add this to the top of your .ot file (if using JSON format):

{
  "$schema": "https://elysium.is/opentime/schemas/v0.2/opentime.json",
  ...
}

Programmatic Validation

JavaScript / TypeScript (using Ajv)

import Ajv from "ajv";
import schema from "./opentime.json";

const ajv = new Ajv();
const validate = ajv.compile(schema);

const data = [
  {
    type: "task",
    id: "task-001",
    title: "Review PR",
    status: "todo"
  }
];

if (validate(data)) {
  console.log("Valid OpenTime file!");
} else {
  console.error(validate.errors);
}

Python (using jsonschema)

import json
from jsonschema import validate, ValidationError

with open("opentime.json") as f:
    schema = json.load(f)

data = [
    {
        "type": "task",
        "id": "task-001",
        "title": "Review PR",
        "status": "todo"
    }
]

try:
    validate(instance=data, schema=schema)
    print("Valid OpenTime file!")
except ValidationError as e:
    print(f"Validation error: {e.message}")

Key Definitions

The schema defines these item types under $defs:

Definition	Description
`goal`	Long-term outcomes with optional milestones
`task`	Actionable items with status tracking
`habit`	Recurring behaviors with optional streaks
`reminder`	Time-triggered notifications
`event`	Time-bound occurrences (meetings, deadlines)
`appointment`	Scheduled commitments with location/attendees
`project`	Containers for related items with phases

Shared structures like link, habitPattern, habitWindow, and habitStreak are also defined and referenced where applicable.

Versioning

The schema version matches the OpenTime specification version. The current version is v0.2.

Schema URLs follow this pattern:

https://elysium.is/opentime/schemas/v{version}/opentime.json

Download

You can download the schema directly for offline use or bundling:

Download opentime.json

Next Steps

Specification

Full OpenTime specification

Reference

Quick lookup for all fields

Developer Guide

Implement OpenTime in your app

Examples

Study example .ot files