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 recurrence, time_window, and milestone 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