TypedMark Typed Markdown note systems
Tool authors

Conformance and Roadmap

Audience: tool authors and implementers.

Authoritative for:

  • the specification's non-goals
  • conformance modes and their required artifact sets
  • the portable validation-report format
  • portable automation event and run-report interchange
  • the recommended implementation order

See also:

Non-Goals#

This specification defines the structural contract for typed Markdown note collections. It deliberately does not define:

  • A specific schema for note types. TypedMark describes how to define and document note types; concrete note sets, starter content, and house conventions belong to systems layered on top of the core, as stated in Foundations.
  • Visual rendering and field widgets. Saved views standardize their layout family, visible field order, labels, grouping, and board partition. Styling, dimensions, interaction controls, value widgets, note rendering, and opaque icon tokens remain tool-defined.
  • Editor user experience. Forms, pickers, autocomplete behavior, and authoring workflows are application concerns.
  • Sync, storage backends, and version control. TypedMark governs files at rest; how they move between machines — Git, sync services, backups — is out of scope.
  • Body prose. Markdown content outside the governed surfaces — frontmatter, H2 headings, internal note links — is free; TypedMark does not constrain writing style or block-level structure.
  • Value coercion. TypedMark is strictly typed: a stored value either satisfies its declared property type or it does not. Reading the string "5" as the integer 5 is coercion.
  • Query and index engine internals. Execution strategy, caching internals, and performance characteristics are implementation concerns; the portable query contract governs results, not how they are produced, and index formats remain outside this version.
  • AI behavior. Agents consume the structural contract; prompts, models, and agent workflows are outside the specification.
  • Identity, authentication, and permissions. Multi-user access control is out of scope; visibility metadata is tracked separately as a possible future addition.

Rules:

  • CR-23 Tools MUST NOT coerce stored values while reading them.

Conformance#

Conformance evaluates a collection root, represented on disk as a directory tree, against the authoritative artifact contracts defined in Collection Model, Systems, Composition, and Evolution, Note Type Schemas, Managed Notes and Properties, and Relationships, Headings, and Templates.

Conformance modes:

Mode Audience Minimum artifact set Advanced features required
Core Profile instantiated collection collection authors typedmark.md, at least one concrete schema, referenced or defaulted templates, and managed notes none
Valid instantiated collection collection authors and tools all artifacts used by the collection, including optional reuse and composition metadata when present only the features physically used
Valid system definition system publishers collection model plus system fields, scaffold, schemas, templates, and optional history publishing, composition, and migration support

Validation Reports#

Validators can serialize their findings as one portable JSON report for editors, CI pipelines, and other tools. The report states what was evaluated and whether any configured error remains; individual results identify both a stable diagnostic category and the exact normative rule that produced it.

{
  "specification_version": "0.0.1",
  "mode": "instantiated_collection",
  "valid": false,
  "results": [
    {
      "code": "invalid_field_value",
      "severity": "error",
      "path": "notes/typed-mark.md",
      "rule_id": "FDR-198",
      "message": "priority must be one of low, medium, or high",
      "note_type": "topic",
      "field": "priority"
    }
  ]
}

Rules:

  • CR-24 A tool that serializes validation findings for interchange MUST encode the report as UTF-8 JSON with the top-level keys specification_version, mode, valid, and results.
  • CR-25 specification_version MUST identify the TypedMark specification version under which the validator evaluated the target.
  • CR-26 mode MUST be system_definition, instantiated_collection, or both, corresponding to the conformance targets defined on this page.
  • CR-27 valid MUST be true exactly when results contains no result whose severity is error.
  • CR-28 results MUST be a list containing zero or more validation-result objects.
  • CR-29 Each validation result MUST contain code, severity, path, rule_id, and message.
  • CR-30 code MUST be one of the validation keys defined authoritatively under validation_defaults in Collection Model.
  • CR-31 severity MUST be the result's effective configured severity after applying the defaults and overrides defined in Collection Model and Note Type Schemas.
  • CR-32 A validator MUST NOT emit a result whose effective configured severity is off.
  • CR-33 path MUST be the normalized collection-relative path of the governed artifact or managed note that the result describes, using forward slashes.
  • CR-34 rule_id MUST identify the stable rule whose violation produced the result.
  • CR-35 message MUST be a non-empty human-readable explanation of the specific finding.
  • CR-36 Consumers MUST NOT use message as a machine-stable identifier.
  • CR-37 A result MAY include note_type, field, relationship, heading, expansion, dataset, view, template_region, or drift_kind when that context applies.
  • CR-38 A nested field context MUST use field as a dot-separated path from its top-level frontmatter field.
  • CR-39 Validators MUST order results by path, rule_id, code, note_type, field, relationship, heading, expansion, dataset, view, template_region, and drift_kind, in that sequence, comparing each component as exact Unicode code points and treating absent values as empty strings.
  • CR-40 Validation MUST NOT modify the collection or any governed artifact it evaluates.
  • CR-86 Every template_drift result MUST contain template_region and drift_kind.

Automation Run Reports#

Automation executors serialize one-hop and propagation outcomes as portable JSON. The report records the root events, deterministic execution waves, actual semantic changes, and machine-stable diagnostics without making the report part of the collection's authoritative state.

{
  "specification_version": "0.0.1",
  "run_id": "run-01k0projectdone",
  "mode": "one_hop",
  "status": "committed",
  "root_event_ids": [
    "evt-01k0projectdone"
  ],
  "waves": [
    {
      "index": 0,
      "event_ids": [
        "evt-01k0projectdone"
      ],
      "automations": [
        "project-completed"
      ],
      "changes": [
        {
          "kind": "field",
          "path": "Projects/TypedMark.md",
          "field": "review_needed",
          "before": true,
          "after": false
        },
        {
          "kind": "tag",
          "path": "Projects/TypedMark.md",
          "tag": "state/completed",
          "operation": "add"
        },
        {
          "kind": "note",
          "path": "Projects/TypedMark.md",
          "operation": "archive"
        }
      ]
    }
  ],
  "diagnostics": []
}

Rules:

  • CR-41 Automation events and run reports are portable runtime interchange documents and are not governed collection artifacts.
  • CR-42 A serialized automation event MUST satisfy automation-event.schema.json.
  • CR-43 A serialized automation run report MUST satisfy automation-run-report.schema.json.
  • CR-44 A run report MUST physically contain specification_version, run_id, mode, status, root_event_ids, waves, and diagnostics.
  • CR-45 mode MUST be one_hop or propagation.
  • CR-46 status MUST be committed, no_change, aborted, or incomplete.
  • CR-47 committed means every change recorded by the run was committed successfully.
  • CR-48 no_change means the run completed successfully without producing a semantic collection change.
  • CR-49 aborted means the executor committed none of the run's staged changes.
  • CR-50 incomplete means a commit began but recovery could not establish either the complete pre-run or complete post-run state.
  • CR-51 root_event_ids MUST identify every external or caller-supplied event that initiated the run.
  • CR-52 waves MUST appear in ascending contiguous index order starting at 0.
  • CR-53 A one_hop report MUST contain at most one wave.
  • CR-54 Each wave MUST identify its consumed events, matched automations, and semantic changes.
  • CR-55 Diagnostic code values are machine-stable.
  • CR-56 Run diagnostics MUST use only unsupported_capability, trigger_error, action_failed, conflicting_write, validation_failed, cycle_detected, wave_limit_exceeded, approval_required, concurrent_change, or incomplete_commit.
  • CR-57 A run report's change list MUST record only semantic changes.
  • CR-58 Run reports MAY be stored outside the collection or under ignored tool state.
  • CR-61 An aborted report MUST include at least one diagnostic.
  • CR-62 An incomplete report MUST include an incomplete_commit diagnostic.
  • CR-63 Consumers MUST NOT parse diagnostic message as an identifier.
  • CR-64 A run report's change list MUST NOT record coalesced no-ops.
  • CR-65 Run reports MUST NOT become authoritative collection input.
  • CR-66 A wave's event_ids MUST use the canonical event order defined in Managed Notes and Properties.
  • CR-67 A wave's automations MUST use the execution order defined in Collection Model.
  • CR-68 A wave's changes MUST preserve semantic production order after no-op coalescing.
  • CR-69 A field change records one top-level field's parsed before and after values.
  • CR-70 A tag change records one exact tag addition or removal.
  • CR-71 A path change records one managed note's normalized before and after paths.
  • CR-72 A note change records one note creation, archive, logical deletion, or hard deletion.
  • CR-73 A link change records one internal-link retargeting in note body content or a top-level frontmatter field.
  • CR-83 An expansion change records one identified content expansion's materialized region before and after refresh.
  • CR-74 A committed report MUST record at least one semantic change.
  • CR-75 A no_change report MUST record no semantic changes.
  • CR-76 An aborted report MUST record no semantic changes.
  • CR-77 A change object's path is its post-change normalized path when the note remains, or its pre-change normalized path for hard deletion.
  • CR-78 root_event_ids MUST use the canonical root-event order defined in Managed Notes and Properties.
  • CR-79 Run diagnostics MUST be ordered by wave, path, automation, field, code, and message, with absent values before present values and exact Unicode code-point comparison within each component.
  • CR-80 run_id MUST be unique within the execution history available to the executor.
  • CR-81 A committed report MUST record every semantic collection change produced by the run.
  • CR-82 A committed or no_change report MUST contain no failure diagnostic.

Valid System Definition#

A collection root conforms as a valid system definition when:

  1. CR-1 typedmark.md is present at the root and valid under Collection Model.
  2. CR-2 typedmark.md declares the system fields version and scaffold, valid under Systems, Composition, and Evolution.
  3. CR-3 <metadata_directory>/history.md, if present, is valid under Systems, Composition, and Evolution and reconstructs the current schema state when replayed.
  4. CR-4 Every property set file under <metadata_directory>/property-sets/, if present, is valid under Collection Model, and every property set reference from typedmark.md or a note-type schema resolves.
  5. CR-5 Every schema file under <metadata_directory>/schemas/, if present, is valid under Note Type Schemas.
  6. CR-6 Every template referenced by a schema file exists and satisfies the template-frontmatter contract in Relationships, Headings, and Templates for its note type's effective schema.
  7. CR-59 Every automation file under <metadata_directory>/automations/, if present, is valid under Collection Model.
  8. CR-93 Every dataset file under <metadata_directory>/datasets/, if present, is valid under Collection Model.
  9. CR-89 Every saved-view file under <metadata_directory>/views/, if present, is valid under Collection Model, and every dataset reference from a saved view resolves.
  10. CR-91 Every saved-view reference from a template resolves.
  11. CR-94 Every dataset reference from a template resolves.
  12. CR-84 Every content expansion in a referenced template satisfies the template expansion contract in Relationships, Headings, Templates, and Content Expansion.
  13. CR-87 Every template region in a referenced template satisfies the marker, descriptor, pairing, nesting, and identifier rules in Template Drift Tracking.

Valid Instantiated Collection#

A collection root conforms as a valid instantiated collection when:

  1. CR-7 typedmark.md is present at the collection root and valid under Collection Model.
  2. CR-8 If typedmark.md declares composition, it is valid under Collection Model, and the collection is self-contained so that conformance does not require re-resolving its sources.
  3. CR-9 Every property set file under <metadata_directory>/property-sets/, if present, is valid under Collection Model, and every property set reference from typedmark.md or a note type used by managed notes resolves.
  4. CR-10 Every schema file under <metadata_directory>/schemas/, if present, is valid under Note Type Schemas, and every concrete note type used by managed notes resolves to exactly one such schema file.
  5. CR-21 Every template referenced or defaulted by a concrete schema exists and satisfies the template-frontmatter contract in Relationships, Headings, and Templates.
  6. CR-11 Managed notes resolve to valid concrete note types under the configured note-type mapping rules and satisfy the managed note contract under Managed Notes and Properties.
  7. CR-12 Managed notes satisfy their schema storage rules under Note Type Schemas.
  8. CR-13 Managed notes satisfy their schema relationship and heading rules under Relationships, Headings, and Templates.
  9. CR-60 Every automation file under <metadata_directory>/automations/, if present, is valid under Collection Model.
  10. CR-95 Every dataset file under <metadata_directory>/datasets/, if present, is valid under Collection Model.
  11. CR-90 Every saved-view file under <metadata_directory>/views/, if present, is valid under Collection Model, and every dataset reference from a saved view resolves.
  12. CR-92 Every saved-view reference from a collection note resolves.
  13. CR-96 Every dataset reference from a collection note resolves.
  14. CR-85 Every content expansion in a collection note satisfies the applicable marker, descriptor, source, rendering, synchronization, and persisted-state rules in Relationships, Headings, Templates, and Content Expansion.
  15. CR-88 Every template-region marker or template_regions receipt in a collection note belongs to an enrolled managed note and satisfies the receipt, marker-correspondence, and drift-classification rules in Template Drift Tracking.

Additional rules:

  • CR-14 Validators MUST evaluate conformance against an explicit target mode: system definition, instantiated collection, or both.
  • CR-15 A collection root is a system definition when typedmark.md declares the system fields, and an instantiated collection when typedmark.md governs managed notes; neither requires a separate system or instance manifest.
  • CR-16 A single collection root MAY conform simultaneously as both a valid system definition and a valid instantiated collection.
  • CR-17 Untyped notes MAY exist in an instantiated collection and do not by themselves make the collection non-conforming.
  • CR-18 Structural precedence across artifacts remains defined in Foundations.
  • CR-19 A Core Profile instantiated collection is a valid instantiated collection that omits system fields, composition provenance, history.md, automation rules, datasets, saved views, property sets, folder_scopes, vocabularies, and non-default note-type mappings.
  • CR-20 Validators MUST apply the defaulted shorthand values defined in Collection Model and Note Type Schemas before evaluating any conformance mode.
  • CR-22 Validators MUST evaluate every winning note-type mapping candidate under CM-114, including candidates that do not resolve to a concrete schema.

Recommended implementation order:

  1. create a Core Profile typedmark.md using the defaults in Collection Model
  2. create the initial concrete note type schemas and let Note Type Schemas compute each effective schema
  3. create canonical templates using the defaulted or explicit template.file paths in Relationships, Headings, and Templates
  4. implement managed note parsing, field materialization, field compatibility and conversion, shared-expression evaluation, and note-link resolution using Managed Notes and Properties, Field Definition Reference, Foundations, and Note Links
  5. add reusable property sets, abstract schemas, vocabularies, advanced mappings, heading rules, and relationship rules only when the collection needs them
  6. add a validator and importer that evaluate the conformance modes defined on this page
  7. populate the system fields in typedmark.md, and add a <metadata_directory>/history.md change log, if you are packaging a reusable, versioned system, using Systems, Composition, and Evolution
  8. implement deterministic system composition that materializes a self-contained collection and records its lineage in typedmark.md composition, using Systems, Composition, and Evolution
  9. implement the migration and update flow that recomposes a collection at newer source versions and applies the resulting change operations to managed notes
  10. implement one-hop automation events, declarative actions, and portable run reports
  11. add dependency-graph propagation, fixed-point termination, recovery, and destructive previews
  12. implement portable query evaluation and query-backed content expansion against the same effective collection model
  13. generate the human-facing reference pages from the authoritative artifacts