news

TypedMark

Sebastien Dubois

20 Jun 2026 — 4 min read

Canonical version: TypedMark.

TypedMark is an open specification for typed Markdown note systems. It adds explicit structure (schemas, field definitions, property sets, note-type inheritance, and validation) while keeping notes as plain Markdown files with YAML frontmatter. Authored by Sébastien Dubois under the MIT license (2026), it is in very early development. The specification itself is substantive and mature; the reference tooling, the systems marketplace, and the example implementations are still scaffolding. The goal is an open standard that any tool can implement, not a single product.

Why it matters

Without explicit note types, Markdown systems decay as they scale: misplaced notes, missing or inconsistent metadata, duplicated content, fragile link structures, unreliable automated queries, and high cognitive overhead. TypedMark's core thesis is that "note types matter because they make Markdown systems easier to use, easier to trust, easier to improve over time and easier to scale." The manifesto argues further that types are not bureaucracy. As it puts it, "they are how plain-text systems stay clear, reliable, and useful as they grow."

For humans, typed systems provide clarity about a note's purpose, location, required structure, and valid relationships. Templates, auto-completion, and validation reduce friction while keeping the portability and longevity that plain Markdown offers. For tools and AI assistants, explicit schemas enable confident validation, safe scaffolding, reliable navigation, and assistance based on declared rules rather than guesswork. The aim is for AI to understand and use the system precisely, not by approximation. TypedMark embeds structure inside the files themselves, in frontmatter, so systems remain yours: readable, portable, reusable, and durable independent of any application.

The model

Collection: A rooted set of Markdown notes plus the TypedMark artifacts (a typedmark.md config file and a metadata directory) that define structure. Typically a directory tracked in Git.

Note Types: Named structural classes. Each concrete type is defined by a schema file specifying metadata fields, structural blocks, composition rules, and optional inheritance from abstract ancestors. Every managed note conforms to exactly one concrete type.

Managed vs Untyped Notes: Managed notes are bound to a known type, validated against its schema, and discoverable by tools. Untyped notes are permitted but unvalidated. The distinction lets structured and freeform content coexist gracefully.

Fields and Property Sets: Fields define metadata with types, constraints, defaults, and typed-relationship contributions. Property sets are named, reusable bundles of shared frontmatter, block structure, and standard headings. They are the unit of composability.

Strong typing, no coercion: TypedMark enforces type correctness without value coercion. Authority flows top-down: typedmark.md to schemas to property sets to templates to note content. Tools infer structure from the artifacts alone, never by guessing at prose.

Systems, composition, and evolution

A system is a reusable, versioned, publishable collection model: the portable unit people share and instantiate. Systems can represent personal knowledge management, dev-team AI context, marketing workflows, PARA-style organization, or domain-specific archives. A private working collection becomes a system once its typedmark.md declares a semantic version (SemVer 2.0.0) and a scaffold (the folders and seed notes to materialize on instantiation).

Composition is a build-time operation defined by the spec: a conforming tool loads source systems at their declared versions, merges them deterministically, and outputs a self-contained collection. The process is specified to be reproducible and canonical, byte-identical across conforming tools, which enables confident reuse. (This layer is specified but not yet implemented.)

Systems publish to a marketplace (a marketplace.json catalog) with discovery metadata: name, version, source, publisher, license, keywords, and target audiences.

Evolution and migration are treated explicitly. Each system maintains an append-only history.md recording structural changes: note types added, removed, or renamed; fields added, removed, renamed, or retyped; property-set changes. Migration tools classify renames and retypes from that history rather than guessing from a structural diff, which keeps upgrades safe and understood.

Scope

TypedMark defines formats and contracts for structure, schemas, validation, and system composition. Explicitly out of scope: rendering and presentation, editor UX, sync, storage, and version-control mechanisms, value coercion, query and index engine internals, AI behavior, and identity, authentication, and permissions. It is a specification, not a product.

Relationship to the Open Knowledge Format

The Open Knowledge Format (OKF, by Google Cloud, released 2026-06-12) provides a minimal substrate: a directory of Markdown files where every concept has a type frontmatter field (a free string), and consumers tolerate unknown types. Relationships are plain Markdown links. OKF is explicitly positioned as "a starting point, not a finished standard" for representing knowledge that AI systems can consume.

TypedMark and OKF converge on the same foundational substrate: Markdown plus YAML frontmatter plus Git, file-over-app, readable and portable by both humans and agents. OKF validated that foundation. TypedMark goes much further. It actually specifies what a type is (real schemas with fields, constraints, defaults, and typed relationships), enforces type inheritance (extends), codifies validation rules, and separates managed from untyped notes. Beyond individual notes, it adds a whole systems layer: versioned, shareable, deterministically composable systems with a marketplace and history-driven safe migrations. OKF focuses on representing knowledge for AI consumption; TypedMark centers on authoring and co-maintaining typed note systems that grow and evolve over years.

TypedMark is positioned as an additional option for the ecosystem, not a replacement for OKF or mdbase. More interoperable specifications on the same substrate are treated as a net gain for the community.

Inspirations and lineage

The OSK plugin implements a note-type system inside Obsidian: types with properties, tags, icons, folder locations, and templates; auto-recognition by tag, folder, or regex; schema export (md-base); a CLI tool (osk-cli); and an MCP server. TypedMark generalizes that vault-and-plugin-specific feature into an open specification any tool can implement.

The Typed Markdown Collections Specification (mdbase), by callumalpass, is a parallel effort that treats Markdown folders as typed, queryable collections. It defines _types/ schemas and conformance levels with an expression language compatible with Obsidian Bases. They share DNA: files as source of truth, progressive strictness, portability, and Git-friendliness. TypedMark differs by centering systems composition, a marketplace model, and migration safety via history.

TypedMark draws on years of practice building and maintaining the Obsidian Starter Kit and running a large typed vault in production.

Status

Very early. The specification (prose plus JSON Schemas) is substantive. The reference tooling, the marketplace infrastructure, and the example systems are scaffolding: placeholders published to show the intended structure, not yet populated or feature-complete.

The near-term goal is to publish the first real example system: a "home" for a software development team that documents its processes, projects, plans, products and services, repositories, and meetings as strongly-typed notes.

References

Specification site: https://developassion.github.io/TypedMarkSpecification
Specification repository: https://github.com/DeveloPassion/TypedMarkSpecification
Tools repository: https://github.com/DeveloPassion/TypedMark
Systems marketplace repository: https://github.com/DeveloPassion/TypedMarkSystemsMarketplace
Example system repository: https://github.com/DeveloPassion/TypedMarkExample

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

📚 KM for Beginners — 10+ hours of structured video lessons
🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
💼 Knowledge Worker Kit — Complete guides + lifetime community
🦉 1-on-1 Coaching — Personalized guidance
🎯 Join Knowii — Community + ALL courses & tools