Reference
A practical, at-a-glance reference for the .ot file format: types, fields, and structures.
How to Use This Reference
This page is meant for day-to-day development work. It summarizes the core building blocks of OpenTime:
- Common scalar types (date, datetime, time, progress)
- Shared structures (links, habit patterns, windows, streaks)
- Each item type with its required and optional fields
For the full formal definition, see the Specification and JSON Schema.
Common Scalar Types
date
| Pattern | Example | Description |
|---|---|---|
YYYY-MM-DD | 2025-12-03 | Date only, no time or timezone information. |
datetime
| Pattern | Examples | Description |
|---|---|---|
YYYY-MM-DDTHH:MM:SS(±HH:MM|Z) | 2025-12-03T09:00:00+09:002025-12-03T00:00:00Z | ISO8601 datetime with explicit timezone offset or Z for UTC. |
time
| Pattern | Example | Description |
|---|---|---|
HH:MM | 06:00, 14:30 | Local wall-clock time in 24-hour format. |
progress
| Type | Range | Description |
|---|---|---|
number | 0.0 – 1.0 | Completion percentage (0 = not started, 1 = complete). |
Shared Structures
link
Used inside links arrays on items.
| Field | Type | Required | Description |
|---|---|---|---|
kind | "url" | "ref" | Yes | "url" for external URLs, "ref" for internal item references. |
value | string | Yes | URL or item ID being referenced. |
habitPattern
| Field | Type | Required | Description |
|---|---|---|---|
freq | "daily" | "weekly" | "custom" | No | Frequency of the habit. |
days_of_week | string[] | No | Days of week (e.g. ["mon","wed","fri"]). |
habitWindow
| Field | Type | Required | Description |
|---|---|---|---|
start_time | time | No | Preferred start of the habit window. |
end_time | time | No | Preferred end of the habit window. |
habitStreak
| Field | Type | Required | Description |
|---|---|---|---|
current | integer ≥ 0 | No | Current streak count. |
longest | integer ≥ 0 | No | Longest streak ever achieved. |
Item Types
All items share a few concepts:
type: discriminator for the item kind.id: non-empty string, SHOULD be unique within the document.title: non-empty, human-readable label.- Optional
tags,notes,linkson most item types. - Implementations MAY include additional custom fields (especially under
x_*namespaces).
Goal
Represents a single-step intention or outcome.
| Field | Type | Required | Description |
|---|---|---|---|
type | "goal" | Yes | Discriminator for the goal item. |
id | string | Yes | Unique identifier for this goal. |
title | string | Yes | Human-readable goal title. |
kind | "goal" | Yes | Constant marker for goal kind. |
target_date | date | No | Target completion date. |
progress | progress | No | Goal completion between 0.0 and 1.0. |
project_id | string | No | ID of the project this goal belongs to. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Task
Represents an atomic action that can be completed.
| Field | Type | Required | Description |
|---|---|---|---|
type | "task" | Yes | Discriminator for the task item. |
id | string | Yes | Unique identifier for this task. |
title | string | Yes | Human-readable task title. |
status | "todo" | "in_progress" | "done" | "cancelled" | Yes | Current status of the task. |
due | date | No | Due date for the task. |
scheduled_start | datetime | No | Planned start time. |
estimate_minutes | integer ≥ 0 | No | Estimated time to complete in minutes. |
actual_minutes | integer ≥ 0 | No | Actual time spent in minutes. |
priority | number | No | Priority level (e.g., 1–10). |
goal_id | string | No | ID of the goal this task supports. |
project_id | string | No | ID of the project this task belongs to. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Habit
Represents a recurring behavior (daily, weekly, or custom).
| Field | Type | Required | Description |
|---|---|---|---|
type | "habit" | Yes | Discriminator for the habit item. |
id | string | Yes | Unique identifier for this habit. |
title | string | Yes | Human-readable habit title. |
pattern | habitPattern | No | Frequency and days-of-week configuration. |
window | habitWindow | No | Preferred time-of-day window. |
streak | habitStreak | No | Current and longest streak counts. |
goal_id | string | No | Related goal ID, if any. |
project_id | string | No | Related project ID, if any. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Reminder
Represents a lightweight notification at a specific time.
| Field | Type | Required | Description |
|---|---|---|---|
type | "reminder" | Yes | Discriminator for the reminder item. |
id | string | Yes | Unique identifier for this reminder. |
title | string | Yes | Human-readable reminder title. |
time | datetime | Yes | When this reminder fires first. |
repeat | string (RRULE) | No | RRULE-style recurrence rule (e.g. FREQ=HOURLY;COUNT=4). |
link | string | No | ID of a related item (task/event/habit/goal). |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Event
Represents a block of time, typically solo (e.g. deep work).
| Field | Type | Required | Description |
|---|---|---|---|
type | "event" | Yes | Discriminator for the event item. |
id | string | Yes | Unique identifier for this event. |
title | string | Yes | Human-readable event title. |
start | datetime | Yes | Event start time. |
end | datetime | Yes | Event end time. |
all_day | boolean | No | Whether this is an all-day event. |
timezone | string | No | IANA timezone name; falls back to default_timezone. |
location | string | No | Where the event takes place. |
recurrence | string (RRULE) | No | RRULE-style recurrence rule. |
goal_id | string | No | Related goal ID, if any. |
project_id | string | No | Related project ID, if any. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Appointment
Represents an event with attendees, like a meeting or appointment.
| Field | Type | Required | Description |
|---|---|---|---|
type | "appointment" | Yes | Discriminator for the appointment item. |
id | string | Yes | Unique identifier for this appointment. |
title | string | Yes | Human-readable appointment title. |
start | datetime | Yes | Start time. |
end | datetime | Yes | End time. |
attendees | string[] | Yes | Names or emails of attendees (at least one). |
location | string | No | Physical or virtual location. |
provider | string | No | Service provider (e.g. "dentist", "therapist", "Zoom"). |
goal_id | string | No | Related goal ID, if any. |
project_id | string | No | Related project ID, if any. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |
Project
Represents a container for related goals, tasks, events, etc. It helps group work under a single umbrella.
| Field | Type | Required | Description |
|---|---|---|---|
type | "project" | Yes | Discriminator for the project item. |
id | string | Yes | Unique identifier for this project. |
title | string | Yes | Human-readable project title. |
kind | "project" | Yes | Constant marker for project kind. |
children | string[] | No | List of item IDs that belong to this project. |
progress | progress | No | Overall project completion between 0.0 and 1.0. |
target_date | date | No | Target completion date for the project. |
tags | string[] | No | Labels for filtering and grouping. |
notes | string | No | Free-form notes. |
links | link[] | No | External URLs or internal references. |