Specification

Fresh

Formal Specifications

MD-LD has three levels of specification, from comprehensive to ultra-compact:

Document	Purpose
Full Specification	Complete canonical specification with grammar, formal definitions, and all constructs
Compact Spec	Concise specification reference for quick lookup
Ultra Compact Spec	Most compact meaningful MD-LD definition

Overview

MD-LD is a markdown-linked data format that combines:

• Markdown syntax — Familiar authoring experience using standard Markdown constructs
• RDF semantics — Standard linked data model (RDF 1.1)
• Polarity system — Built-in diff authoring capabilities via + and - prefixes
• Origin tracking — Complete provenance for every quad
• Context management — Subject declarations and prefix folding

Key Concepts

• Subject declarations — {=IRI} sets current subject
• Predicate forms — p, ?p, !p for different relationship types
• Value carriers — [text], **bold**, code blocks, headings, list items, blockquotes
• Polarity — + (default) and - prefixes for diff authoring
• Origin tracking — Lean mapping from quads to source locations

Normative Guarantees

The specification guarantees:

1. Determinism — Same input always produces same output
2. Round-trip safety — MD-LD to RDF to MD-LD preserves all information
3. No inference — The parser never adds triples beyond what is explicitly annotated
4. Explicit semantics — Every triple traces to an annotation in the source text
5. Hard invariant — quads ∩ remove = empty set (no triple is simultaneously present and retracted)

Grammar Artifacts

The formal grammar is published in two forms:

• TextMate grammar (mdld.tmLanguage.json) — The primary syntax specification, compatible with VS Code, Sublime Text, GitHub, and Shiki
• EBNF grammar (mdld.ebnf) — ISO 14977 EBNF reference specification

See the Grammar section for the full grammar documentation.