Property Types Reference

This reference documents the expected data types for each frontmatter property that TaskNotes uses.

Quick Reference

Use this table for fast validation when a field is not behaving as expected in views or API calls. Most parsing issues come from shape mismatches (for example scalar vs list) rather than missing values.

Property Details

The sections below describe storage formats, but there is flexibility in authoring style. TaskNotes normalizes many equivalent YAML representations as long as the resulting data type is correct.

Text Properties

title

• Type: text (string)
• Description: The task's title or name
• Example: title: "Complete project documentation"

status

• Type: text (string)
• Description: The task's current status. Must match one of the status values configured in your settings.
• Default values: "open", "in-progress", "done"
• Example: status: "in-progress"
• Note: Also supports boolean values (true/false) for Obsidian checkbox compatibility. See Boolean Status Values.

priority

• Type: text (string)
• Description: The task's priority level. Must match one of the priority values configured in your settings.
• Default values: "low", "normal", "high"
• Example: priority: "high"

Date Properties

All date properties are stored as text strings in your frontmatter. TaskNotes expects specific formats: When in doubt, prefer ISO-style values. They sort correctly as text, travel well through APIs, and are easiest to parse consistently.

due

• Type: text (date string)

• Format: YYYY-MM-DD or ISO 8601 timestamp

• Description: The task's due date

• Examples:

  due: "2025-01-15"
  due: "2025-01-15T17:00:00"
  

scheduled

• Type: text (date string)

• Format: YYYY-MM-DD or ISO 8601 timestamp

• Description: When the task is scheduled to be worked on

• Examples:

  scheduled: "2025-01-10"
  scheduled: "2025-01-10T09:00:00"
  

completedDate

• Type: text (date string)
• Format: YYYY-MM-DD
• Description: The date when the task was completed
• Example: completedDate: "2025-01-20"

dateCreated

• Type: text (datetime string)
• Format: ISO 8601 timestamp
• Description: When the task was created
• Example: dateCreated: "2025-01-01T08:00:00Z"

dateModified

• Type: text (datetime string)
• Format: ISO 8601 timestamp
• Description: When the task was last modified
• Example: dateModified: "2025-01-15T10:30:00Z"

List Properties

List properties must be arrays, even when containing a single value. Single-item arrays may look verbose, but they prevent edge cases when filters and formulas assume list semantics.

tags

• Type: list (array of strings)

• Description: Tags associated with the task

• Examples:

  tags: ["work", "documentation"]
  tags:
    - work
    - documentation
  

contexts

• Type: list (array of strings)

• Description: Context labels for the task

• Examples:

  contexts: ["office", "computer"]
  contexts:
    - "office"
    - "computer"
  

projects

• Type: list (array of strings)

• Description: Project references (typically wiki-links)

• Examples:

  projects: ["[[Website Redesign]]", "[[Q1 Planning]]"]
  projects:
    - "[[Website Redesign]]"
    - "[[Q1 Planning]]"
  

Numeric Properties

timeEstimate

• Type: number
• Unit: minutes
• Description: Estimated time to complete the task
• Example: timeEstimate: 120 (2 hours)

Recurrence Properties

recurrence

• Type: text (string)

• Format: RFC 5545 RRULE format

• Description: Defines how the task repeats

• Examples:

  recurrence: "FREQ=DAILY"
  recurrence: "FREQ=WEEKLY;BYDAY=MO,WE,FR"
  recurrence: "FREQ=MONTHLY;BYMONTHDAY=1"
  

recurrence_anchor

• Type: text (string)
• Valid values: "scheduled" or "completion"
• Description: Determines whether the next occurrence is calculated from the scheduled date or when the task was completed
• Example: recurrence_anchor: "scheduled"

complete_instances

• Type: list (array of date strings)

• Format: YYYY-MM-DD

• Description: Dates when recurring task instances were completed

• Example:

  complete_instances:
    - "2025-01-08"
    - "2025-01-15"
  

skipped_instances

• Type: list (array of date strings)

• Format: YYYY-MM-DD

• Description: Dates when recurring task instances were skipped

• Example:

  skipped_instances:
    - "2025-01-22"
  

Materialized Occurrence Properties

Materialized occurrence notes are ordinary task notes created for one date in a recurring series. The parent recurring task owns the recurrence rule; the occurrence note owns date-specific state such as status, completed date, body content, time entries, reminders, and comments.

When an occurrence note is created, TaskNotes inherits parent planning metadata such as scheduled time, due offset, priority, tags, contexts, projects, reminders, dependencies, details, custom properties, and time estimate. It does not copy parent recurrence/history/runtime fields such as recurrence, complete_instances, skipped_instances, completedDate, provider event IDs, or timeEntries.

recurrence_parent

• Type: text (link or path string)
• Description: Parent recurring task for a materialized occurrence note
• Example: recurrence_parent: "[[Tasks/Weekly review]]"

occurrence_date

• Type: text (date string)
• Format: YYYY-MM-DD
• Description: Target recurrence date represented by a materialized occurrence note
• Example: occurrence_date: "2025-01-15"

occurrence_materialization

• Type: text (string)
• Valid values: "manual", "on_completion", "rolling"
• Description: Parent task policy for creating occurrence notes. The plugin currently supports manual creation and creating the next note after completion; rolling windows are defined by the spec but are not automated yet.
• Example: occurrence_materialization: "on_completion"

occurrence_next_trigger

• Type: text (string)
• Valid values: "completion" or "completion_or_skip"
• Description: Parent task policy for whether skip actions should also create the next occurrence note when occurrence materialization is set to on_completion
• Example: occurrence_next_trigger: "completion_or_skip"

occurrence_template

• Type: text (link or path string)
• Description: Optional template reference used when creating materialized occurrence notes. This parent-level template takes priority over the global occurrence note template fallback in Features settings.
• Example: occurrence_template: "[[Templates/Weekly occurrence]]"

occurrence_past_horizon and occurrence_future_horizon

• Type: text (ISO 8601 duration string)

• Description: Optional rolling-window bounds for occurrence materialization. These fields are part of the TaskNotes spec; automated rolling materialization is not currently enabled in the plugin.

• Examples:

  occurrence_past_horizon: "P7D"
  occurrence_future_horizon: "P14D"
  

Complex Properties

These properties contain structured data with multiple fields. For these fields, copy known-good examples before editing manually. Minor schema deviations can break downstream features such as reminders, recurrence, or dependency checks.

Time Entries

• Type: list (array of objects)

• Description: Time tracking entries for the task

• Structure:

  timeEntries:
    - startTime: "2025-01-15T10:30:00Z"    # Required: ISO 8601 timestamp
      endTime: "2025-01-15T11:15:00Z"      # Optional: ISO 8601 timestamp
      description: "Initial work"          # Optional: text
  

Dependencies (blockedBy)

• Type: list (array of objects)

• Description: Tasks that must be completed before this task can start

• Structure:

  blockedBy:
    - uid: "path/to/blocking-task.md"    # Required: path to blocking task
      reltype: "FINISHTOSTART"           # Required: relationship type
      gap: "P1D"                         # Optional: ISO 8601 duration offset
  

• Relationship types accepted in stored data: FINISHTOSTART, STARTTOSTART, FINISHTOFINISH, STARTTOFINISH

• Current behavior: Dependencies created from the UI use FINISHTOSTART. Blocking evaluation is based on dependency presence/completion state and does not currently apply distinct scheduling semantics for different reltype values or gap.

Reminders

• Type: list (array of objects)

• Description: Reminder notifications for the task

• Structure for relative reminders:

  reminders:
    - id: "rem_1"                        # Required: unique identifier
      type: "relative"                   # Required: "relative" or "absolute"
      relatedTo: "due"                   # Required for relative: "due" or "scheduled"
      offset: "-PT1H"                    # Required for relative: ISO 8601 duration
      description: "1 hour before due"   # Optional: description
  

• Structure for absolute reminders:

  reminders:
    - id: "rem_2"
      type: "absolute"
      absoluteTime: "2025-01-15T09:00:00Z"  # Required for absolute: ISO 8601 timestamp
      description: "Morning reminder"
  

icsEventId

• Type: list (array of strings)

• Description: ICS calendar event IDs linked to this task

• Example:

  icsEventId:
    - "event-abc123"
    - "event-def456"
  

Complete Example

Here's a complete task with all property types:

---
title: "Complete quarterly report"
status: "in-progress"
priority: "high"
due: "2025-01-31"
scheduled: "2025-01-25"
tags:
  - work
  - reports
contexts:
  - "@office"
projects:
  - "[[Q1 Planning]]"
timeEstimate: 240
dateCreated: "2025-01-01T08:00:00Z"
dateModified: "2025-01-20T14:30:00Z"
timeEntries:
  - startTime: "2025-01-20T10:00:00Z"
    endTime: "2025-01-20T11:30:00Z"
blockedBy:
  - uid: "tasks/gather-data.md"
    reltype: "FINISHTOSTART"
reminders:
  - id: "rem_1"
    type: "relative"
    relatedTo: "due"
    offset: "-P1D"
    description: "Due tomorrow"
---

Field Mapping

All property names can be customized via Settings → Task Properties → Field Mapping. If you change a field mapping, TaskNotes will read and write using your custom property name.

Custom property names are frontmatter keys, so names with spaces or punctuation are valid in task files. When you write your own Bases filters or formulas for those keys, use bracket notation such as note["TN-status"] or note["Task Type"] instead of dot notation. Dot notation only works reliably for simple identifier-style names.

For example, if you map due to dueDate, TaskNotes will expect:

dueDate: "2025-01-15"

See Task Properties settings for configuration details.

Custom User Fields

You can define additional properties with these types:

• text - Single text value
• number - Numeric value
• date - Date string (YYYY-MM-DD)
• boolean - true/false
• list - Array of values

See Custom User Fields for configuration details.