OpenTime FAQ

Common questions about the OpenTime .ot format, answered for both users and developers.

General questions

What is OpenTime?

OpenTime is a human-readable, app-agnostic file format for scheduling, planning, and time-related data. It's to time what Markdown is to notes: a simple text format you can read, edit, and version-control yourself. Files use the .ot extension and live as plain text in your filesystem.

An OpenTime document is just a YAML file with metadata and an items array containing goals, tasks, habits, reminders, events, appointments, and projects.

Is OpenTime tied to Elysium?

OpenTime was created inside Elysium and Elysium is the first app to support it natively, but the format itself is intentionally app-agnostic. Any app, plugin, or tool can read and write .ot files without asking permission, paying a license, or depending on Elysium's servers.

Think of Elysium as the reference implementation, not the gatekeeper.

Why not just use Markdown?

Markdown is fantastic — but it was designed for documents, not time.

People often encode tasks and schedules inside .md files, but every app or plugin invents its own conventions:

- [ ] Task
due:: 2025-12-04
YAML frontmatter fields
Dataview / Logseq / NotePlan custom metadata

That works inside a single ecosystem, but it's not a shared standard. Another app can read the text, but may not understand the structure or meaning of your time data.

OpenTime is different: it defines explicit item types — goal, task, habit, reminder, event, appointment, project — with well-defined fields like start, end, due, status, progress, recurrence, and relationships like goal_id and project_id.

A simple way to think about it:

Markdown is for ideas. OpenTime is for time.

In practice, they're meant to live side by side: keep your notes in .md and your schedules in .ot, and let tools link the two.

Why not just use existing calendar formats like ICS?

ICS and CalDAV are great for calendar sync, but they're:

hard to read as a human,
focused on events, not goals/tasks/habits,
awkward to version-control,
not designed to be a single source of truth for your life.

OpenTime is designed from the start to be:

simple YAML,
multi-type (goals, tasks, habits, events, etc.),
round-trip safe across apps,
something you can open in any editor and understand.

Is OpenTime meant to replace my calendar app?

Not necessarily. OpenTime is a format, not a UI. It's a way to store and move your time data. You might:

use Elysium as your primary UI and export to OpenTime,
use other apps that sync with .ot in the future,
keep your master plan as .ot files in git and push certain events into Google Calendar or similar.

Is .ot just YAML?

Yes and no. OpenTime uses YAML syntax for readability, but it also defines a strict schema and specification for what those YAML documents mean. That's what keeps different apps interoperable.

So every .ot file is YAML, but not every YAML file is a valid OpenTime document.

Can I store my OpenTime files in git or cloud storage?

Absolutely. That's one of the core design goals. Because .ot files are just text:

you can keep them in git,
sync them via iCloud, Dropbox, or anything else,
review changes with normal text diffs,
roll back if something breaks.

Does any other app support OpenTime yet?

Right now, Elysium is the first app built natively around OpenTime. The format is intentionally simple so other apps, plugins, and scripts can add support with minimal effort. Over time, the goal is for OpenTime to become a small, stable standard that many tools understand.

Questions for developers

Where is the official specification?

The main technical resources are:

OpenTime Specification – human-readable spec
JSON Schema – machine-readable definition
Reference – tables of fields and types
Examples – concrete .ot snippets and a full sample file

How do I validate that a .ot file is “correct”?

Use the JSON Schema at:

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

Pick any JSON Schema validator that supports draft 2020-12, parse the YAML into an object, and validate it. The schema page includes code samples for JS/TS and Python.

Do I have to support all item types?

No. You can start small. For example, your app might only care about task and event items at first. The spec doesn't require you to implement every type; it just defines how they should look when they exist.

It does ask you to:

preserve unknown fields,
not break the file structure,
respect opentime_version.

What are x_* fields and how should I handle them?

x_* fields are extension namespaces for apps. For example:

x_elysium:
  focus_mode: "deep"
  color: "#3B82F6"

Best practices:

If it's your namespace (e.g. x_myapp), you can read and write it however you like.
If it's someone else's namespace, you can ignore it but should not delete it.
When you write the file back to disk, re-emit those extension blocks so other apps don't lose their data.

Do I need to use YAML, or can I use JSON internally?

On disk, OpenTime is defined as YAML. Internally, you can parse into whatever representation is easiest for you (objects, structs, JSON, etc.). Many apps will:

Read YAML → in-memory object / JSON
Validate against JSON Schema
Map to internal models
Map back to OpenTime items
Serialize to YAML

If you prefer, you can keep an internal JSON representation and only convert to/from YAML at the boundaries.

How stable is the spec? Will it change often?

OpenTime uses semantic-style versioning via the opentime_version field (for example, "0.2"). The goal is:

keep the core small and stable,
evolve cautiously and in a backwards-compatible way where possible,
use new versions (e.g. 0.3) for structural changes.

Older versions will remain documented and their schemas will stay available, so you can support the versions you care about.

Is there a recommended way to generate types from the schema?

Yes. Because OpenTime uses JSON Schema, you can use existing tools to generate types:

TypeScript: tools like json-schema-to-typescript
Other languages: any JSON Schema → types generator

Or, if you prefer hand-written models, the Reference page and schema should give you everything you need.

User & workflow questions

Can I use OpenTime with note apps like Obsidian?

Direct support would require plugins, but OpenTime is designed to sit comfortably alongside things like Markdown. You might keep:

notes in .md,
schedules in .ot,
links between them (for example, a note that references a project_id or vice versa).

In the future, a simple plugin could parse .ot files and surface tasks/events in your note system.

How big can an OpenTime file get?

There's no hard limit in the spec, but for sanity:

many people will use one file per area (e.g. life.ot, work.ot),
or one file per year/season/project,
plus archives if things get huge.

Because it's plain text, extremely large files can get slower to diff, search, and open in some editors. Splitting by context or time range works well.

What happens if two apps edit the same .ot file?

OpenTime doesn't magically solve sync conflicts — it's still a file in a filesystem. But:

because it's text, you can see exactly what changed,
many conflicts can be resolved with normal git-style merges,
apps that follow the spec won't silently delete each other's data (especially in x_* fields).

What's the best way to start using OpenTime today?

Easiest path:

Download the sample.ot and open it in your editor.
Start a small file of your own (for example, life.ot) with tasks and a few events.
Use Elysium (or a future OpenTime-aware app) to visualize and manipulate that file.
If you're a dev, wire up a tiny script or CLI to read/modify your .ot file.

Did we miss something?

If there's a question you think belongs here—especially if you're building an integration or plugin—feel free to suggest it. The FAQ will grow as more people start using and shaping the format.