TypedMark

Audience: everyone.

See also:

• Manifesto: the motivation for TypedMark
• Getting Started: a non-normative first collection
• Foundations: the first normative specification page

TypedMark is an open specification for typed Markdown note systems.

Current edition: 0.1.0 draft. This edition is under development and is not yet released. The refocusing work is tracked in #123. See the 0.1.0 migration checklist for intentional compatibility changes.

Changes in this draft#

• Pre-1.0 minor lines are separate compatibility boundaries. Implementing 0.1.x does not imply support for the prior 0.0.1 contract; patch changes remain compatible.
• Templates take their specification version from their referencing concrete schema rather than storing it in starter note frontmatter.
• Required extensions use an exact-version map; validation reports distinguish complete interpretation from unsupported or deliberately limited evaluation.
• Unknown artifact-structure keys are errors under implemented contracts; explicitly scoped x_* metadata provides an inert carrier instead.

The authoritative rules are in Specification Versioning, Extensions and Capabilities, and Validation Reports. Other decisions recorded in the epic remain planned until their corresponding contracts land; this summary does not itself change those contracts.

New here? Read the Manifesto for the why, then follow Getting Started to build your first Core Profile collection in five minutes. The Quick Reference maps terms and everyday tasks to the rules that govern them.

The Pages#

• Manifesto: why note types matter
• Getting Started: your first typed collection, step by step (non-normative)
• Foundations: the core concepts, the file format of governed artifacts, and the parsing baselines everything else builds on
• Extensions and Capabilities: required optional contracts, capability matching, and inert vendor metadata
• Collection Model: collection configuration, mappings, vocabularies, and shared path matching
• Note Type Schemas: local note-type definitions, storage, naming, and effective-schema construction
• Field Definition Reference: every property a field can declare
• Field Compatibility and Conversion: an optional shared contract for queries, datasets, and migrations
• Managed Notes and Properties: managed-note metadata and field materialization
• Note Links: how links between notes are written and resolved
• Relationships, Headings, and Templates: relationships, body headings, and starter templates
• Schema Reuse and Property Sets: optional inheritance, shared blocks, and conditional constraints
• Portable Queries and Datasets and Views: optional querying and presentation contracts
• Expressions and Authoring: optional derivation, extra generators, and immutability
• Template Tracking and Content Expansion: optional tracked and derived body content
• Automation Artifacts, Automation Runtime, and Automation Interchange: optional automation declarations and execution
• Systems, Composition, and Evolution: packaging a collection as a shareable, versioned, composable system
• Migration Effects: what happens to existing notes when a system changes
• Marketplace Catalog: the companion distribution contract
• Conformance and Roadmap: what it means for a tool or collection to conform
• Quick Reference: glossary and "how do I…" index (non-normative)

Reading Paths#

Core Profile — the shortest conforming path:

1. Manifesto
2. Getting Started
3. Foundations
4. Collection Model for typedmark.md identity and defaults
5. Note Type Schemas for one concrete note type and the effective schema
6. Managed Notes and Properties, with the Field Definition Reference at hand
7. Note Links and Relationships, Headings, and Templates for links, headings, and starter templates

Essentials plus reuse — for larger personal or team collections:

8. Collection Model for mappings and vocabularies, then Property Sets when shared blocks are needed
9. Schema Reuse for abstract inheritance and conditions; query and presentation contracts are separate optional reading

Advanced — for publishing, composing, and migrating systems:

10. Systems, Composition, and Evolution
11. Migration Effects

Tool authors — for implementing validators, importers, and editors:

12. Conformance and Roadmap
13. The parsing and matching baselines in Foundations and the machine-readable schemas
14. Extensions and Capabilities for interpreting declarations and reporting unsupported contracts

Machine-Readable Schemas#

The governed artifacts have machine-readable JSON Schemas, fixtures, and a boundary document under schema/. The prose specification remains the single source of truth.

Related Repositories#

• TypedMark: the tooling, website, and documentation around the specification
• TypedMarkExample: a concrete system example built on this specification
• TypedMarkSystemsMarketplace: the systems marketplace, hosting systems, a browsing and composition website under docs/, and the marketplace.json catalog of known systems defined by this specification