OpenTime Specification

1. Introduction

OpenTime is a plain-text file format designed to do for time what Markdown did for notes. An OpenTime file (with extension .ot) describes a collection of items such as goals, tasks, habits, reminders, events, appointments, and projects in a way that is both human-readable and machine-parseable.

This document describes the normative specification for the OpenTime format v0.2. Implementations SHOULD validate against the JSON Schema and MUST NOT remove unknown fields when reading and writing .ot files.

2. Document Structure

An OpenTime file is a single YAML document with the following top-level structure:

opentime_version: "0.2"          # required string, semantic-style version
default_timezone: "Asia/Tokyo"   # optional IANA timezone name
generated_by: "Elysium 0.3"      # optional free-form string
created_at: "2025-12-02T12:00:00Z"  # optional ISO8601 timestamp
items:
  - type: task
    id: task_1
    title: "Example task"
    status: todo

All top-level properties are defined as follows:

3. Items and Types

Every entry in items is an object with at minimum the fields type, id, and title. The type field acts as a discriminator and determines the required and optional fields for that item.

Supported item types:

• goal
• task
• habit
• reminder
• event
• appointment
• project

The id field MUST be a non-empty string and SHOULD be unique within the document. The title field MUST be a non-empty human-readable string.

4. Common Field Types

OpenTime reuses a small set of common scalar types across item definitions:

The links field is an array of link objects with the following structure:

target_id: "goal_novel"
kind: "relates_to"     # optional free-form relation label
label: "Related goal"  # optional display label

5. Item Definitions

This section summarizes the required and notable optional fields for each item type. See the JSON Schema for full details.

5.1 Goal

Represents a single-step intention or outcome (e.g., "Finish novel draft").

5.2 Task

Represents an atomic action that can be completed (e.g., "Write 500 words").

5.3 Habit

Represents a recurring behavior (e.g., "Morning walk").

The pattern object describes frequency:

pattern:
  freq: "daily"        # "daily", "weekly", or custom app-defined values

The window object describes a preferred time window:

window:
  start_time: "06:00"
  end_time: "08:00"

The streak object tracks habit streaks:

streak:
  current: 12
  longest: 21

5.4 Reminder

Represents a lightweight notification at a specific time, optionally repeating.

5.5 Event

Represents a block of time, typically solo (e.g., "Deep work").

5.6 Appointment

Represents an event with one or more attendees, such as a meeting.

5.7 Project

Represents a container for related goals, tasks, events, and other items.

6. Extensions and x_* Fields

OpenTime is designed to be extensible. Item definitions allow additional properties, and applications are encouraged to place app-specific extensions under a namespaced key starting with x_(e.g., x_elysium, x_other_app).

Implementations MUST NOT discard unknown fields when reading and writing .ot files. This allows multiple applications to interoperate on the same file without clobbering each other's data.

- type: event
  id: ev_extended
  title: "Event with extensions"
  start: "2025-12-20T10:00:00+09:00"
  end: "2025-12-20T11:00:00+09:00"
  x_elysium:
    focus_mode: "deep"
    color: "#3B82F6"
  x_other_app:
    custom_field: "preserved on round-trip"

7. Validation and Conformance

The canonical definition of OpenTime v0.2 is provided as a JSON Schema. Implementations SHOULD validate files against this schema in development and may choose to do so in production environments depending on performance constraints.

At minimum, conforming implementations MUST:

• Require opentime_version and items at the document root
• Require type, id, and title for all items, plus any additional type-specific required fields
• Preserve unknown fields, including x_* extension fields, when reading and writing files
• Treat date, datetime, and time fields as opaque strings unless they need to manipulate them semantically; when they do, they SHOULD follow ISO8601 rules

8. Examples and Resources

For a complete example that exercises all item types, see the sample.ot file in the OpenTime repository.

• Quick Reference — At-a-glance lookup for all fields and values
• JSON Schema — Validate your .ot files programmatically
• Examples — Browse example .ot files
• Developer Guide — Implement OpenTime in your app