9. Configuration

9.1 Purpose#

This section defines the normative configuration model for collections using tasknotes-spec.

9.2 Configuration provider model#

Implementations MUST derive an effective configuration from one or more configuration providers.

A provider is a source adapter that returns a partial configuration normalized to this section's schema.

Implementations MUST:

• support at least one provider,
• document supported providers,
• document provider precedence order,
• disclose active providers and fallback behavior in conformance output (§7).

9.2.1 Common provider types#

Common providers include:

• yaml_file: a tasknotes.yaml document at collection root,
• tasknotes_plugin_data_json: .obsidian/plugins/tasknotes/data.json,
• built_in_defaults: implementation defaults,
• optional runtime/CLI/env overrides.

This list is not exhaustive.

9.2.2 Deterministic precedence and merge#

Provider precedence MUST be deterministic.

Unless explicitly documented otherwise, implementations MUST resolve configuration per top-level key:

• for each key in §9.3/§9.4, the highest-precedence provider that supplies that key wins,
• winning object values replace lower-precedence object values as whole objects (no implicit deep merge),
• after top-level selection, implementations MUST apply documented schema defaults for missing nested keys before exposing effective configuration.

If an implementation supports deep-merge behavior, it MUST be explicitly documented and deterministic.

9.2.3 Strict vs permissive provider behavior#

In strict mode:

• failure to resolve required effective keys (spec_version, mapping) MUST be a configuration error.

If permissive mode is implemented, then in permissive mode:

• implementations MAY continue with defaults when providers are missing/unreadable,
• implementations MUST emit configuration warnings,
• implementations MUST disclose that effective configuration is partial/default-derived.

9.2.4 TaskNotes plugin provider (data.json)#

The TaskNotes plugin stores settings in .obsidian/plugins/tasknotes/data.json within the vault root. When using this file as a configuration provider, normalization MUST apply the field mapping in the table below.

Key mapping table (data.json key → spec effective config):

Key data.json fields with defaults (for cold-start reading of a vault with no tasknotes.yaml):

StatusConfig object shape:

{
  "id": "done",
  "value": "done",
  "label": "Done",
  "color": "#00aa00",
  "isCompleted": true,
  "order": 3,
  "autoArchive": false,
  "autoArchiveDelay": 5
}

spec_version is not present in data.json. Implementations MUST synthesize an effective spec_version as described in §9.5.

Provider keys not listed above MAY be ignored by tasknotes-spec consumers.

9.3 Required top-level keys#

Required keys apply to the effective configuration after provider resolution.

9.4 Recommended top-level keys#

9.5 spec_version behavior#

spec_version MUST be a semantic version string. Pre-release identifiers are valid (for example 0.3.0-rc.3).

Implementations in strict mode MUST reject unsupported major versions.

If permissive mode is implemented, permissive mode MAY proceed with warning when major version differs.

If a provider does not supply spec_version (for example TaskNotes data.json), implementations MUST synthesize an effective spec_version matching their target tasknotes-spec version and SHOULD disclose that it was synthesized.

9.6 mapping schema#

mapping MUST map semantic roles (from §2) to string storage keys.

Minimum required roles in mapping:

• title
• status
• completed_date
• date_created
• date_modified

If semantic role id is supported (§2.6.5), mapping SHOULD include id. If profile materialized-occurrences is claimed, mapping MUST include recurrence_parent and occurrence_date, and SHOULD include parent policy roles (occurrence_materialization, occurrence_next_trigger, occurrence_template, occurrence_past_horizon, occurrence_future_horizon).

Example:

mapping:
  title: title
  status: status
  date_created: dateCreated
  date_modified: dateModified
  completed_date: completedDate
  recurrence: recurrence
  recurrence_anchor: recurrenceAnchor
  complete_instances: completeInstances
  skipped_instances: skippedInstances
  recurrence_parent: recurrence_parent
  occurrence_date: occurrence_date
  occurrence_materialization: occurrence_materialization
  occurrence_next_trigger: occurrence_next_trigger
  occurrence_template: occurrence_template
  occurrence_past_horizon: occurrence_past_horizon
  occurrence_future_horizon: occurrence_future_horizon
  time_entries: timeEntries
  blocked_by: blockedBy
  reminders: reminders
  attachments: attachments

9.7 task_detection schema#

task_detection controls how task files are identified within the vault.

Detection methods#

The tasknotes plugin natively supports two identification methods, controlled by taskIdentificationMethod in data.json (mapped to task_detection.method):

tag (default) — A markdown file is a task if it contains the configured tag (default #task) in its frontmatter tags array or inline in the body. Configured by task_detection.tag.

property — A markdown file is a task if a specified frontmatter property has a specified value (or exists, if value is empty). Configured by task_detection.property_name and task_detection.property_value.

Schema and selection rules:

1. task_detection MAY specify either:
   • method (single-method form), or
   • methods (multi-method form; non-empty list).
2. If both are present, methods MUST take precedence and implementations SHOULD emit a configuration warning.
3. If neither is present, effective detection method MUST default to tag.
4. method MUST be tag or property.
5. methods entries MUST be unique and MUST be from:
   • tag
   • property
   • field_presence
   • field_match
6. Method-specific required keys:
   • when tag is enabled, effective task_detection.tag MUST be non-empty (default task when absent);
   • when property is enabled, task_detection.property_name MUST be provided and non-empty; task_detection.property_value MAY be empty (empty means key-exists semantics).
7. If methods has more than one entry, task_detection.combine controls combination semantics (§9.7.3). If omitted, it MUST default to or.

9.7.1 Tag matching semantics#

When task_detection.method=tag, matching MUST follow these rules:

1. Normalize configured task_detection.tag by stripping one leading # when present.
2. Compare tag names case-insensitively after normalization.
3. Frontmatter matching:
   • tags MAY be a list of strings or a single string.
   • each tag value is normalized by trimming surrounding whitespace and stripping one leading #.
   • match requires exact normalized equality (for example task matches #task; task does not match tasking).
4. Body matching:
   • only markdown text outside fenced code blocks and inline code spans is considered,
   • a match requires a hashtag token with exact normalized name (for example #task),
   • partial-word matches MUST NOT count (for example #tasking does not match configured task).

If either frontmatter or body matches, the file is identified as a task.

9.7.2 Property matching semantics#

When property detection is enabled (method=property or methods includes property):

1. task_detection.property_name MUST name the frontmatter key to inspect.
2. If task_detection.property_value is non-empty, match requires semantic equality with the configured value.
3. If task_detection.property_value is empty or absent, match requires key presence only.

9.7.3 Multi-method extension semantics#

tasknotes.yaml-level providers MAY additionally support:

• field_presence (example: required key status)
• field_match (example: type == "task")

Extension-key shape:

• field_presence: string or list of required frontmatter keys.
• field_match: object map of key -> expected scalar value for exact semantic equality checks.

If multiple methods are configured in tasknotes.yaml, task_detection.combine MUST define combinator semantics:

• or (default): file is a task if any enabled method matches.
• and: file is a task only if all enabled methods match.

If task_detection.combine is absent, implementations MUST default to or.

Implementations MUST exclude folders listed in task_detection.excluded_folders from task indexing.

Executable conformance: adapters participating in the fixture suite SHOULD expose config.detect_task_file to evaluate these detection semantics against fixture inputs.

Example (tasknotes.yaml, equivalent to tag-based default):

task_detection:
  method: tag
  tag: task
  default_folder: TaskNotes/Tasks

Example (property-based):

task_detection:
  method: property
  property_name: type
  property_value: task

9.8 defaults schema#

defaults defines values used at create time when caller input omits a role.

Defaults MUST NOT override explicit user input.

Example:

defaults:
  status: open
  priority: normal
  recurrence_anchor: scheduled
  reminders:
    - id: due_minus_1d
      type: relative
      relatedTo: due
      offset: -P1D

defaults.reminders behavior is defined in §10.3.9.

9.9 status schema#

status defines known status values and completion semantics.

Example:

status:
  values: [open, in-progress, done, cancelled]
  default: open
  completed_values: [done]
  skipped_values: [cancelled]
  default_skipped: cancelled

Rules:

• default MUST be one of values.
• completed_values MUST be a non-empty list.
• Each completed_values entry MUST be in values.
• skipped_values, when present, MUST be a list whose entries are in values.
• default_skipped, when present, MUST be in skipped_values.
• For implementations claiming materialized-occurrences, skipped_values MUST NOT overlap completed_values.
• Implementations claiming materialized-occurrences MUST provide at least one skipped value or fail skip of materialized occurrence notes deterministically (§5.20.3).
• Non-recurring completion MUST use this list, not hardcoded literals.
• When a complete operation does not provide an explicit target status, writers MUST use the first entry of completed_values.
• When a materialized occurrence skip operation does not provide an explicit skipped status, writers MUST use default_skipped when present, otherwise the first entry of skipped_values.

9.10 validation schema#

Example:

validation:
  mode: strict
  reject_unknown_fields: false

Rules:

• mode MUST be strict or permissive when present.
• If mode is absent, effective mode MUST default to strict.
• Conforming implementations MUST support strict.
• Implementations MAY support permissive.
• If mode=permissive is configured but not implemented, configuration MUST fail in strict mode and SHOULD emit warning/fallback in permissive mode.
• reject_unknown_fields=true enforces closed-schema behavior for mapped roles.

9.11 dependencies schema#

Example:

dependencies:
  default_reltype: FINISHTOSTART
  treat_missing_target_as_blocked: true
  enforce_unique_uid: true
  unresolved_target_severity: warning
  require_resolved_uid_on_write: false

Rules:

• default_reltype MUST be one of the allowed reltype values in §10.2.
• treat_missing_target_as_blocked controls whether missing/unresolvable dependency targets contribute to blocked-state evaluation (§10.2.5).
• If treat_missing_target_as_blocked is absent, effective value MUST default to true.
• enforce_unique_uid=true enforces uniqueness at validation/write time.
• If enforce_unique_uid is absent, effective value MUST default to true.
• unresolved_target_severity MUST be warning or error.
• require_resolved_uid_on_write=true requires dependency UID resolution success for add/update operations.

9.12 links schema#

Example:

links:
  extensions: [".md"]
  unresolved_default_severity: warning
  update_references_on_rename: true

Rules:

• extensions defines extension trial order for extensionless targets.
• unresolved_default_severity MUST be warning or error.
• update_references_on_rename=true enables rename-time link rewrite behavior when supported.

9.13 title schema#

Example (storage=frontmatter):

title:
  storage: frontmatter
  filename_format: custom
  custom_filename_template: "{{date}} {{title}}"

Example (storage=filename):

title:
  storage: filename

Rules:

• storage MUST be frontmatter or filename.
• when storage=frontmatter, filename_format MUST be title, zettel, timestamp, or custom.
• when storage=frontmatter and filename_format=custom, custom_filename_template MUST be provided and non-empty.
• when storage=filename, filename_format and custom_filename_template MAY be present for compatibility input but MUST be ignored for canonical write behavior.
• Read precedence MUST be storage-mode-aware:
  1. when storage=frontmatter, use mapped title key when present and non-empty, then file basename fallback;
  2. when storage=filename, use file basename first, then mapped title fallback when basename is unavailable.
• If frontmatter and basename titles both exist and differ, the source authoritative for active storage MUST win.
• If storage=filename, canonical writes MUST treat filename as title source, MUST rename on title change, and MUST ignore filename_format and custom_filename_template.
• If storage=frontmatter, canonical writes MUST persist mapped title key; filename_format and custom_filename_template govern create-time filename generation.

Informative mapping to TaskNotes settings:

• title.storage=filename corresponds to storeTitleInFilename=true.
• title.filename_format corresponds to taskFilenameFormat.
• title.custom_filename_template corresponds to customFilenameTemplate.

9.14 templating schema#

templating defines optional create-time template behavior. This schema is required only for implementations claiming profile templating (§7.3.3).

Example:

templating:
  enabled: true
  template_path: Templates/Task.md
  failure_mode: warning_fallback
  unknown_variable_policy: preserve

Rules:

• enabled MUST be boolean.
• If enabled=true, template_path MUST be provided and non-empty.
• failure_mode MUST be error or warning_fallback when present.
• unknown_variable_policy MUST be preserve or empty when present.
• If failure_mode is absent, effective value MUST default to warning_fallback.
• If unknown_variable_policy is absent, effective value MUST default to preserve.
• Implementations claiming templating MUST support portable double-brace variables from §5.3.5.
• Implementations not claiming templating MAY ignore templating settings.

9.15 reminders schema#

Example:

reminders:
  date_only_anchor_time: "00:00"
  apply_defaults_when_explicit: false

Rules:

• date_only_anchor_time MUST be HH:MM 24-hour local time format.
• date_only_anchor_time is used by §10.3.4 for relative reminders against date-only bases.
• apply_defaults_when_explicit MUST be boolean when present.
• if apply_defaults_when_explicit is absent, effective value MUST default to false.
• apply_defaults_when_explicit=false means explicit input reminders replace default-reminder application at create time.
• apply_defaults_when_explicit=true means explicit create-time reminders are merged with defaults using §10.3.9 deterministic merge rules.

9.16 time_tracking schema#

Example:

time_tracking:
  auto_stop_on_complete: true
  auto_stop_notification: false

Rules:

• auto_stop_on_complete MUST be boolean when present.
• auto_stop_notification MUST be boolean when present.
• if auto_stop_on_complete=true, completion-triggered stop behavior MUST follow §5.19.5.
• if auto_stop_notification is absent, effective value MUST default to false.

9.17 occurrences schema#

occurrences defines collection-level defaults for recurrence materialization. This schema is required only for implementations claiming profile materialized-occurrences (§7.3.4).

Example:

occurrences:
  default_materialization: manual
  default_next_trigger: completion
  past_horizon: P0D
  future_horizon: P14D

Rules:

• default_materialization MUST be one of manual, on_completion, or rolling.
• If default_materialization is absent, effective value MUST default to manual.
• default_next_trigger MUST be completion or completion_or_skip.
• If default_next_trigger is absent, effective value MUST default to completion.
• past_horizon and future_horizon, when present, MUST be ISO 8601 duration strings.
• If default_materialization=rolling, implementations MUST use finite rolling bounds. If bounds are absent, documented finite defaults MUST be used.
• Parent task fields override collection defaults: occurrence_materialization overrides occurrences.default_materialization; occurrence_next_trigger overrides occurrences.default_next_trigger; occurrence_past_horizon and occurrence_future_horizon override occurrences.past_horizon and occurrences.future_horizon.
• If occurrences is absent, the effective behavior is manual materialization and completion next trigger.

9.17.1 nlp schema#

nlp advertises optional natural-language capture triggers. These settings allow another TaskNotes client to preserve the same capture vocabulary without making natural-language parsing a requirement of the core profile.

Example:

nlp:
  triggers:
    - property_id: tags
      trigger: "#"
      enabled: true
    - property_id: contexts
      trigger: "@"
      enabled: true
    - property_id: priority
      trigger: "!"
      enabled: false

Rules:

• triggers MUST be a list when present.
• Every trigger entry MUST contain non-empty property_id and trigger strings.
• property_id SHOULD use a stable TaskNotes role (tags, contexts, projects, status, or priority) or the stable identifier of a configured user field.
• enabled MUST be boolean when present and MUST default to true.
• Trigger strings MAY contain more than one character.
• Trigger entries with unknown property_id values MUST be preserved by configuration round-trips and MAY be ignored by clients that cannot resolve the property.
• If nlp is absent, clients MAY use documented local defaults.
• This block controls capture parsing and suggestions only. It MUST NOT change persisted task field names or values.

Informative mapping to TaskNotes settings:

• nlp.triggers corresponds to nlpTriggers.triggers.
• property_id, trigger, and enabled correspond to the plugin fields propertyId, trigger, and enabled.

9.18 compatibility schema#

Example:

compatibility:
  read_aliases: true
  legacy_duration_field: true
  legacy_local_datetime_input: false

Rules:

• Compatibility flags MUST default to conservative behavior in new collections.
• legacy_local_datetime_input=true MAY relax strict parsing for offset-less datetimes only in permissive mode; strict mode parsing rules in §3.4.2 still apply.
• Enabled compatibility flags SHOULD be disclosed in conformance output (§7).

9.19 Complete configuration example (yaml_file provider)#

spec_version: 0.3.0-rc.3

mapping:
  title: title
  status: status
  priority: priority
  due: due
  scheduled: scheduled
  attachments: attachments
  completed_date: completedDate
  date_created: dateCreated
  date_modified: dateModified
  recurrence: recurrence
  recurrence_anchor: recurrenceAnchor
  complete_instances: completeInstances
  skipped_instances: skippedInstances
  recurrence_parent: recurrence_parent
  occurrence_date: occurrence_date
  occurrence_materialization: occurrence_materialization
  occurrence_next_trigger: occurrence_next_trigger
  occurrence_template: occurrence_template
  occurrence_past_horizon: occurrence_past_horizon
  occurrence_future_horizon: occurrence_future_horizon
  time_entries: timeEntries
  blocked_by: blockedBy
  reminders: reminders

task_detection:
  method: tag
  tag: task
  default_folder: TaskNotes/Tasks

defaults:
  status: open
  priority: normal
  recurrence_anchor: scheduled
  reminders:
    - id: due_minus_1d
      type: relative
      relatedTo: due
      offset: -P1D

status:
  values: [open, in-progress, done, cancelled]
  default: open
  completed_values: [done]
  skipped_values: [cancelled]
  default_skipped: cancelled

validation:
  mode: strict
  reject_unknown_fields: false

dependencies:
  default_reltype: FINISHTOSTART
  treat_missing_target_as_blocked: true
  enforce_unique_uid: true
  unresolved_target_severity: warning
  require_resolved_uid_on_write: false

links:
  extensions: [".md"]
  unresolved_default_severity: warning
  update_references_on_rename: true

title:
  storage: filename

templating:
  enabled: false
  failure_mode: warning_fallback
  unknown_variable_policy: preserve

reminders:
  date_only_anchor_time: "00:00"
  apply_defaults_when_explicit: false

time_tracking:
  auto_stop_on_complete: true
  auto_stop_notification: false

occurrences:
  default_materialization: manual
  default_next_trigger: completion
  past_horizon: P0D
  future_horizon: P14D

nlp:
  triggers:
    - property_id: tags
      trigger: "#"
      enabled: true
    - property_id: contexts
      trigger: "@"
      enabled: true
    - property_id: projects
      trigger: "+"
      enabled: true
    - property_id: status
      trigger: "*"
      enabled: true
    - property_id: priority
      trigger: "!"
      enabled: false

compatibility:
  read_aliases: true
  legacy_duration_field: true

9.20 Configuration errors#

Configuration validation MUST report structured errors with key path context.

Examples:

• no readable configuration provider available in strict mode
• required effective key unresolved after provider resolution (spec_version or mapping)
• missing mapping.title
• status.default not present in status.values
• status.completed_values contains a value not present in status.values
• status.skipped_values contains a value not present in status.values
• status.default_skipped not present in status.skipped_values
• status.skipped_values overlaps status.completed_values when materialized-occurrences is claimed
• unsupported validation.mode
• validation.mode=permissive but permissive mode is not implemented
• invalid task_detection.method
• invalid task_detection.methods entry
• empty task_detection.tag when tag method is enabled
• missing task_detection.property_name when property method is enabled
• invalid task_detection.combine
• invalid dependencies.default_reltype
• invalid dependencies.unresolved_target_severity
• invalid links.unresolved_default_severity
• invalid title.storage
• invalid title.filename_format
• missing title.filename_format when title.storage=frontmatter
• missing title.custom_filename_template when title.storage=frontmatter and title.filename_format=custom
• missing templating.template_path when templating.enabled=true
• invalid templating.failure_mode
• invalid templating.unknown_variable_policy
• invalid reminders.date_only_anchor_time
• invalid reminders.apply_defaults_when_explicit
• invalid time_tracking.auto_stop_on_complete
• invalid time_tracking.auto_stop_notification
• invalid occurrences.default_materialization
• invalid occurrences.default_next_trigger
• invalid occurrences.past_horizon
• invalid occurrences.future_horizon
• invalid nlp.triggers
• empty nlp.triggers[].property_id
• empty nlp.triggers[].trigger
• invalid nlp.triggers[].enabled

9.21 Default collection state#

This section describes what a fresh tasknotes vault looks like before any user customization. Implementations that read an existing tasknotes vault without a tasknotes.yaml SHOULD apply these defaults when data.json is absent or fields are missing.

Folder layout#

MyVault/
├── TaskNotes/
│   ├── Tasks/          ← new tasks created here by default
│   └── Archive/        ← archived tasks moved here (if moveArchivedTasks=true)
└── .obsidian/
    └── plugins/
        └── tasknotes/
            └── data.json

Task detection#

Default method: tag. A file is a task if it contains the tag #task in its frontmatter tags array or inline in the body.

Default field mapping#

Note: recurrenceAnchor, completeInstances, and skippedInstances are accepted as aliases on read (§2.5). The mixed camelCase/snake_case defaults are intentional for compatibility with historical TaskNotes frontmatter.

Default statuses#

Default status on create: open. Default completed status (first isCompleted=true): done. No skipped status is configured by default; implementations that support materialized occurrence skips MUST require configuration or expose a documented default before writing skipped occurrence state.

Default priorities#

Default priority on create: normal.

Title and filename defaults#

• title.storage: filename (filename/path is the authoritative title source)
• default basename generation under title.storage=filename derives from semantic title using filename-safe sanitization
• implementations MAY also keep mapped title in frontmatter as a synchronized compatibility mirror
• TaskNotes data.json may still contain legacy taskFilenameFormat values such as zettel, but these are compatibility inputs rather than the forward default when title.storage=filename
• title is read from filename first; frontmatter title is compatibility fallback when filename-derived title is unavailable (§2.2.2)

Time tracking defaults#

• auto_stop_on_complete: true
• auto_stop_notification: false

Link format defaults#

• useFrontmatterMarkdownLinks: false — wikilinks used by default (e.g. [[task-name]])
• To use markdown link format, the obsidian-frontmatter-markdown-links plugin must also be installed

Effective configuration for a minimal fresh vault#

When neither data.json nor tasknotes.yaml is present, implementations MUST use the following effective configuration:

spec_version: 0.3.0-rc.3   # synthesized
mapping:
  title: title
  status: status
  priority: priority
  due: due
  scheduled: scheduled
  contexts: contexts
  projects: projects
  attachments: attachments
  time_estimate: timeEstimate
  completed_date: completedDate
  date_created: dateCreated
  date_modified: dateModified
  recurrence: recurrence
  recurrence_anchor: recurrence_anchor
  complete_instances: complete_instances
  skipped_instances: skipped_instances
  recurrence_parent: recurrence_parent
  occurrence_date: occurrence_date
  occurrence_materialization: occurrence_materialization
  occurrence_next_trigger: occurrence_next_trigger
  occurrence_template: occurrence_template
  occurrence_past_horizon: occurrence_past_horizon
  occurrence_future_horizon: occurrence_future_horizon
  time_entries: timeEntries
  blocked_by: blockedBy
  reminders: reminders
task_detection:
  method: tag
  tag: task
  default_folder: TaskNotes/Tasks
status:
  values: [none, open, in-progress, done]
  default: open
  completed_values: [done]
title:
  storage: filename
time_tracking:
  auto_stop_on_complete: true
  auto_stop_notification: false
links:
  use_markdown_format: false
  extensions: [".md"]
  unresolved_default_severity: warning
  update_references_on_rename: true