Note Type Schemas

Audience: collection authors.

Authoritative for:

• local note-type schema shape and effective-schema construction
• note-type metadata, counts, storage, and template references

See also:

• Collection Model: association, boundaries, and mandatory-tag policy
• Managed Notes and Properties: effective values and Core fields
• Field Definition Reference: field declarations
• Schema Reuse and Property Sets: optional reusable layers
• Relationships, Headings, and Templates: body and template contracts

Note Type Registry#

Schemas live directly under <metadata_directory>/schemas/; their basenames identify their types. For example, meeting.md defines meeting without a separate registry file or a duplicate managed-note note_type field definition.

Rules:

• NTS-1 Every Markdown file directly under <metadata_directory>/schemas/ defines one note type.
• NTS-3 A note type MUST NOT be defined in more than one schema file.
• NTS-4 A schema's effective note_type MUST equal its file basename without .md.
• NTS-6 abstract: true defines an abstract type under Schema Reuse.
• NTS-7 An omitted or false abstract defines a concrete type.

Effective Note-Type Schema#

A Core-only schema uses local definitions and deterministic defaults. Reuse adds explicitly governed layers; it does not make a second effective-schema file authoritative.

Normative Evaluation Pipeline#

Rules:

• NTS-10 A validator MUST select exactly one concrete schema using the association rules in Collection Model.
• NTS-174 A Core-only effective schema MUST be constructed from the selected local definitions and their specified defaults.
• NTS-175 A schema using reusable structure MUST apply Schema Reuse and Property Sets before final local definitions.
• NTS-19 Local concrete definitions MUST be applied after reusable contributions.
• NTS-20 The resulting structural blocks and effective top-level metadata form the effective note-type schema.
• NTS-21 Field, relationship, heading, and storage validation MUST use that effective schema.
• NTS-22 Conformance MUST NOT require a separately serialized effective-schema artifact.

Schema File Contract#

The table defines local declarations. Reuse can supply inherited blocks; Core does not guess storage.

specification_version: 0.1.0
note_type: meeting
description: A dated meeting note.
frontmatter:
  meeting_date:
    type: date
  status:
    type: text
    default_value: draft
    allowed_values: [draft, final]
storage:
  folder_pattern: Meetings
  note_name_pattern: "{meeting_date} - {title}"
headings:
  required_h2: [Agenda, Notes]

Store the intended Core title for composite names; its name-part fallback would otherwise include the date, which a name pattern produces rather than an affix.

Rules:

• NTS-23 A note-type schema MUST satisfy the Schema File Contract table.
• NTS-176 A concrete schema without extends MUST physically declare storage.
• NTS-55 Omitted relationships are equivalent to empty belongs_to.allowed_note_types and related_to.allowed_note_types.
• NTS-58 Omitted headings default to empty required/optional H2 lists, allowed other H2s, no ordering requirement, and no H1/title coupling.
• NTS-60 Human-facing guidance MUST NOT override structural rules.
• NTS-66 A note type's effective unknown_field overrides the collection default only for its managed-note frontmatter.
• NTS-67 That override MUST NOT change unknown structural-key severity for governed artifacts.
• NTS-69 A supplied count range MUST have non-negative integer bounds with min <= max when both are present.
• NTS-71 A note-count violation MUST be reported as invalid_note_count.

Mandatory Tags#

A note type can add mandatory tags without declaring a second tags field. Collection-level policy and the effective note-type policy are combined by Collection Model.

mandatory_tags: [type/project, actionable]

Rules:

• NTS-170 A supplied mandatory_tags MUST be a non-empty ordered list of unique valid tags.
• NTS-172 The type-level policy contributes the final stage of Collection Model's mandatory-tag sequence.

Abstract Inheritance Example#

See Schema Reuse.

Conditional Field Constraints#

Conditional constraints belong to Schema Reuse.

Allowed Schema Kinds#

Counts express cardinality directly; fixed storage patterns express fixed paths.

count: {min: 1, max: 1}
storage:
  folder_pattern: ""
  note_name_pattern: Home

Storage Rules#

Storage patterns are a separate, deliberately small grammar, not the optional ${...} expression language. They consist of literal text and references to effective scalar fields. There is no current-clock placeholder and no recursive evaluation of substituted text.

For example, {meeting_date:YYYY}/{meeting_date:MM} names a folder from a declared date; {now:YYYY} needs an actual field named now. A project's decision log can live beside it: with a belongs_to field project, folder_pattern: "{project:folder}/{project:name}" and note_name_pattern: Decisions place it at Projects/Launch/Decisions.md for Projects/Launch.md.

Free names are author-chosen, not stored. Without a stored title, {title} alone is effectively free.

A note's name part is its basename without the affixes it carries. It is the free name, the text a name pattern must produce, and the default title, so Launch (Project).md is titled Launch without storing a duplicate. An optional affix is a decoration: notes may carry it or not, and writers add it only when asked. With this suffix, Growth mindset.md and Growth mindset (Permanent).md both conform, and both have the name part Growth mindset:

storage:
  folder_pattern: notes
  note_name_suffix:
    pattern: " (Permanent)"
    optional: true

A note can also live in a folder of its own, named after its name part, with its related files beside it. note_folder: required makes that folder part of the path; note_folder: optional accepts the note in its own folder or directly in the resolved folder. With this contract, Projects/Launch/Launch (Project).md and Projects/Rollout (Project).md both conform, but Projects/Launch (Project)/Launch (Project).md does not, because the folder takes the name part without the suffix:

storage:
  folder_pattern: Projects
  note_name_suffix:
    pattern: " (Project)"
  note_folder: optional

A writer that claims Edits and Renames moves the rest of the folder with the note.

Rules:

• NTS-97 A supplied storage block MUST contain folder_pattern.
• NTS-177 Storage declarations MUST satisfy the Storage Rules shape table.
• NTS-101 Storage patterns govern both path validation and note creation.
• NTS-113 A resolved name consists of the resolved prefix, name pattern or free name, and suffix in that order, where an absent optional affix contributes nothing.
• NTS-188 An affix declaring optional: true MAY be absent from a conforming basename; an omitted optional has the effective value false.
• NTS-192 A note's name part is its basename without .md, without the resolved prefix it starts with, and without the resolved suffix it ends with, under the storage contract NTS-138 selects; a prefix and suffix that would overlap are not removed.
• NTS-193 An affix whose pattern cannot be resolved, or references title while the note stores no title, is not removed from the name part.
• NTS-189 An optional affix is removed only when the name part remains non-empty, and it is present exactly when it is removed.
• NTS-181 Without note_name_pattern, the free name is the note's name part, which MUST be non-empty.
• NTS-198 With note_folder, the note's basename MUST sit in a folder named exactly the note's name part, directly inside the resolved folder.
• NTS-199 With note_folder: optional, a note MAY instead sit directly in the resolved folder, and it is in its own folder exactly when its parent folder is the resolved folder followed by its name part.
• NTS-190 A writer creating a note MUST omit an optional affix and an optional note folder unless its caller explicitly requests them.
• NTS-191 A writer moving or renaming a note MUST keep each optional affix and an optional note folder present or absent unless its caller explicitly requests otherwise.
• NTS-182 A free name MUST fully match any note_name_regex.
• NTS-117 A placeholder MUST have the form {field_name} or {field_name:format}.
• NTS-124 A placeholder MUST reference a top-level effective field or Core field.
• NTS-125 Storage placeholders MUST NOT traverse nested fields.
• NTS-127 A formatted placeholder MUST reference a date or datetime and use YYYY, MM, DD, YYYY-MM, YYYY-MM-DD, Q, WW, or GGGG, or reference a single note-link field and use name or folder.
• NTS-184 {field:name} resolves to the basename without .md, and {field:folder} to the collection-relative folder, of the managed note the field's effective value currently resolves to.
• NTS-185 :folder MUST appear only in folder_pattern; its value may contain /, and an empty segment it leaves is dropped.
• NTS-186 A link placeholder whose value does not resolve to a managed note makes the path unresolvable.
• NTS-120 Q is the quarter number 1 through 4, WW is the zero-padded ISO 8601 week number 01 through 53, and GGGG is the four-digit ISO 8601 week-numbering year; week-based patterns SHOULD pair WW with GGGG rather than YYYY.
• NTS-128 Datetime components MUST be taken from the effective instant in the collection timezone; date components use the calendar date as written.
• NTS-129 Substitution MUST use effective scalar field values.
• NTS-130 Every referenced value MUST be concrete and non-null when the path is evaluated.
• NTS-132 List, tags, object, and any fields MUST NOT be used in storage placeholders.
• NTS-133 A substituted value other than a :folder value MUST NOT contain slash, backslash, or control characters, or equal . or ...
• NTS-134 A resolved note basename, and a note folder name, MUST be a non-empty string not beginning with ..
• NTS-180 A resolved path MUST be free of control characters and . or .. path segments, regardless of whether they came from literal text or substituted values.
• NTS-178 Substituted text MUST NOT be reparsed as storage-pattern syntax.
• NTS-137 The resolved note path is the resolved folder, then the note folder when the note has one, then the basename and .md, with no leading separator for an empty folder.
• NTS-138 Effective archived selects the active or archived storage contract.
• NTS-144 An archived note with an archive block MUST use its alternate patterns.
• NTS-145 Without an archive block, an archived note MUST continue to satisfy the active storage patterns.
• NTS-146 A path mismatch or unsafe path MUST be reported under path; an unsafe path MUST NOT be created.
• NTS-148 A writer creating a note MUST derive its initial path from the effective storage patterns and values it will write.
• NTS-150 A writer MUST obtain every necessary concrete value and free name before creating a note at a conforming path.
• NTS-183 A writer moving a note to a free-name contract MUST keep its name part unless given another.
• NTS-187 A writer moving or renaming a note SHOULD move the notes whose storage paths depend on it.
• NTS-152 A writer MUST NOT create or move a note onto an occupied note or artifact path.
• NTS-154 Tools SHOULD report resolved paths differing only by letter case and names reserved on common filesystems, including Windows device names and path components ending in a dot or space.
• NTS-156 Archiving MUST preserve the note's type and its effective non-null identifier.

Template References#

Explicit templates name files; otherwise <note_type>.md supplies overrides when present, or starter state is derived.

template:
  file: meetings/standard.md

Rules:

• NTS-44 A supplied template.file MUST be relative to <metadata_directory>/templates/.
• NTS-45 That path MUST NOT be absolute, contain .. segments, or restate the metadata/templates prefix.
• NTS-47 A supplied template file path MUST end in .md.
• NTS-159 When no effective explicit template reference exists, the conventional template filename is <note_type>.md.

Creation Inputs#

inputs lists the fields a writer asks for when a person or agent creates a note, in order, using each field's label and description. A task can ask for its priority and effort even though both have defaults.

inputs: [priority, effort, due]

Rules:

• NTS-194 A supplied inputs MUST be a non-empty ordered list of unique names of top-level effective fields or Core fields other than note_type.
• NTS-195 An input field MUST NOT declare computed, a generation strategy, or const_value.
• NTS-196 A writer asking a person or agent for values while creating a note SHOULD ask for the effective inputs in declared order before other values.
• NTS-197 An input MAY be left unanswered when its field has a conforming effective value without it.