TaskNotes Schemas

1
import z from "zod";
2

3
const StatusSchema = z
4
  .union([
5
    z.literal("none").describe("The task has no status"),
6
    z.literal("open").describe("The task is open"),
7
    z.literal("in-progress").describe("The task is in-progress"),
8
    z.literal("done").describe("The task is done"),
9
  ])
10
  .default("none")
11
  .describe(
12
    "Tracks the current state of a task (e.g., todo, in-progress, done). Status determines whether a task appears as completed and can trigger auto-archiving.",
13
  );
14

15
const PrioritySchema = z
16
  .union([
17
    z.literal("none").describe("The task has no priority"),
18
    z.literal("low").describe("The task has low priority"),
19
    z.literal("normal").describe("The task has normal priority"),
20
    z.literal("high").describe("The task has high priority"),
21
  ])
22
  .default("none")
23
  .describe(
24
    "Indicates task importance. Used for sorting and filtering. Values are sorted alphabetically in Bases views, so use prefixes like 1-, 2- to control order.",
25
  );
26

27
const ReminderSchema = z.union([
28
  z.object({
29
    id: z.string(),
30
    type: z.literal("relative"),
31
    relatedTo: z.enum(["due", "scheduled"]),
32
    offset: z.string(),
33
    description: z.string().optional(),
34
  }),
35
  z.object({
36
    id: z.string(),
37
    type: z.literal("absolute"),
38
    description: z.string().optional(),
39
    absoluteTime: z.string(),
40
  }),
41
]);
42

43
const TimeEntrySchema = z.object({
44
  startTime: z.string(),
45
  endTime: z.string().optional(),
46
  description: z.string().optional(),
47
});
48

49
const CorePropertiesSchema = z
50
  .object({
51
    title: z
52
      .string()
53
      .optional()
54
      .describe(
55
        "The task name. Can be stored in frontmatter or in the filename (when 'store title in filename' is enabled).",
56
      ),
57
    status: StatusSchema,
58
    priority: PrioritySchema,
59
  })
60
  .describe(
61
    "Status and priority are the core properties that define a task's state and importance.",
62
  );
63

64
const DatePropertiesSchema = z
65
  .object({
66
    due: z
67
      .string()
68
      .optional()
69
      .describe(
70
        "Indicates task importance. Used for sorting and filtering. Values are sorted alphabetically in Bases views, so use prefixes like 1-, 2- to control order.",
71
      ),
72
    scheduled: z
73
      .string()
74
      .optional()
75
      .describe(
76
        "When you plan to work on a task. Unlike due date, this represents your intended start time. Tasks appear on the calendar at their scheduled date/time.",
77
      ),
78
  })
79
  .describe("Configure when tasks are due and scheduled.");
80

81
const OrganizationPropertiesSchema = z
82
  .object({
83
    contexts: z
84
      .array(z.string())
85
      .optional()
86
      .describe(
87
        "Locations or conditions where a task can be done (e.g., @home, @office, @phone). Useful for filtering tasks by your current situation. Stored as a list.",
88
      ),
89
    projects: z
90
      .array(z.string())
91
      .optional()
92
      .describe(
93
        "Links to project notes this task belongs to. Stored as wikilinks (e.g., [[Project Name]]). Tasks can belong to multiple projects.",
94
      ),
95
    tags: z
96
      .array(z.string())
97
      .optional()
98
      .describe(
99
        "Native Obsidian tags for categorizing tasks. These are stored in the tags frontmatter property and work with Obsidian's tag features.",
100
      ),
101
  })
102
  .describe("Organize tasks with contexts, projects, and tags.");
103

104
const TaskDetailsSchema = z
105
  .object({
106
    timeEstimate: z
107
      .number()
108
      .optional()
109
      .describe(
110
        "Estimated minutes to complete the task. Used for time-blocking and workload planning. Displayed on task cards and calendar events.",
111
      ),
112
    recurrence: z
113
      .string()
114
      .optional()
115
      .describe(
116
        "Pattern for repeating tasks (daily, weekly, monthly, yearly, or custom RRULE). When a recurring task is completed, its scheduled date is automatically updated to the next occurrence.",
117
      ),
118
    recurrence_anchor: z
119
      .string()
120
      .optional()
121
      .describe(
122
        "Controls how the next occurrence is calculated: 'scheduled' uses the scheduled date, 'completion' uses the actual completion date.",
123
      ),
124
    reminders: z
125
      .array(ReminderSchema)
126
      .optional()
127
      .describe(
128
        "Notifications triggered before due or scheduled dates. Stored as a list of reminder objects with timing and optional description.",
129
      ),
130
  })
131
  .describe(
132
    "Additional details like time estimates, recurrence, and reminders.",
133
  );
134

135
const MetadataPropertiesSchema = z
136
  .object({
137
    dateCreated: z
138
      .string()
139
      .optional()
140
      .describe(
141
        "Timestamp when the task was first created. Automatically set and used for sorting by creation order.",
142
      ),
143
    dateModified: z
144
      .string()
145
      .optional()
146
      .describe(
147
        "Timestamp of the last change to the task. Automatically updated when any task property changes.",
148
      ),
149
    completedDate: z
150
      .string()
151
      .optional()
152
      .describe(
153
        "Timestamp when the task was marked complete. Set automatically when status changes to a completed state.",
154
      ),
155
    timeEntries: z
156
      .array(TimeEntrySchema)
157
      .optional()
158
      .describe(
159
        "Records of time tracking sessions for this task. Each entry stores start and end timestamps. Used to calculate total time spent.",
160
      ),
161
    complete_instances: z
162
      .array(z.string())
163
      .optional()
164
      .describe(
165
        "Completion history for recurring tasks. Stores dates when each instance was completed to prevent duplicate completions.",
166
      ),
167
    skipped_instances: z
168
      .array(z.string())
169
      .optional()
170
      .describe(
171
        "Skipped occurrences for recurring tasks. Stores dates of instances that were skipped rather than completed.",
172
      ),
173
    blockedBy: z
174
      .array(z.object({
175
        uid: z.string(),
176
        reltype: z.literal("FINISHTOSTART"),
177
      }))
178
      .optional()
179
      .describe(
180
        "Links to tasks that must be completed before this one. Stored as wikilinks. Blocked tasks display a visual indicator.",
181
      ),
182
    tasknotes_manual_order: z
183
      .string()
184
      .optional()
185
      .describe(
186
        "Frontmatter property used for drag-to-reorder manual ordering. A view must be sorted by this property for drag-and-drop reordering to work.",
187
      ),
188
  })
189
  .describe("System-managed properties for tracking task history.");
190

191
const FeaturePropertiesSchema = z
192
  .object({
193
    icsEventId: z
194
      .string()
195
      .optional()
196
      .describe(
197
        "Unique identifier linking a note to an ICS calendar event. Added automatically when creating notes from calendar events.",
198
      ),
199
  })
200
  .describe(
201
    "Properties used by specific TaskNotes features like Pomodoro timer and calendar sync.",
202
  );
203

204
const AdditionalPropertiesSchema = z.object({
205
  id: z.string()
206
    .optional()
207
    .describe("The task unique identifier."),
208
  description: z
209
    .string()
210
    .optional()
211
    .describe("The task description. Markdown content of the note."),
212
}).describe(
213
  "Properties that are not part of the TaskNotes spec but still useful."
214
)
215

216
const TaskSchema = z.object({
217
  ...CorePropertiesSchema.shape,
218
  ...DatePropertiesSchema.shape,
219
  ...OrganizationPropertiesSchema.shape,
220
  ...TaskDetailsSchema.shape,
221
  ...MetadataPropertiesSchema.shape,
222
  ...FeaturePropertiesSchema.shape,
223
  ...AdditionalPropertiesSchema.shape,
224
});
225

226
const TaskNotesSchemas = {
227
  Priority: PrioritySchema,
228
  Reminder: ReminderSchema,
229
  Status: StatusSchema,
230
  Task: TaskSchema,
231
  TimeEntry: TimeEntrySchema,
232
};
233

234
type CoreProperties = z.infer<typeof CorePropertiesSchema>;
235
type DateProperties = z.infer<typeof DatePropertiesSchema>;
236
type OrganizationProperties = z.infer<typeof OrganizationPropertiesSchema>;
237
type TaskDetails = z.infer<typeof TaskDetailsSchema>;
238
type MetadataProperties = z.infer<typeof MetadataPropertiesSchema>;
239
type FeatureProperties = z.infer<typeof FeaturePropertiesSchema>;
240
type AdditionalProperties = z.infer<typeof AdditionalPropertiesSchema>;
241
type Priority = z.infer<typeof PrioritySchema>;
242
type Reminder = z.infer<typeof ReminderSchema>;
243
type Status = z.infer<typeof StatusSchema>;
244
type Task = z.infer<typeof TaskSchema>;
245
type TimeEntry = z.infer<typeof TimeEntrySchema>;
246

247
declare namespace TaskNotes {
248
  export type { Priority, Reminder, Status, Task, TimeEntry };
249
}
250

251
export type {
252
  AdditionalProperties,
253
  CoreProperties,
254
  DateProperties,
255
  FeatureProperties,
256
  MetadataProperties,
257
  OrganizationProperties,
258
  Priority,
259
  Reminder,
260
  Status,
261
  Task,
262
  TaskDetails,
263
  TaskNotes,
264
  TimeEntry,
265
};
266
export {
267
  AdditionalPropertiesSchema,
268
  CorePropertiesSchema,
269
  DatePropertiesSchema,
270
  FeaturePropertiesSchema,
271
  MetadataPropertiesSchema,
272
  OrganizationPropertiesSchema,
273
  PrioritySchema,
274
  ReminderSchema,
275
  StatusSchema,
276
  TaskDetailsSchema,
277
  TaskNotesSchemas,
278
  TaskSchema,
279
  TimeEntrySchema,
280
};
281
export default TaskNotesSchemas;