Linked Markdown (LMD)

Specification Version 0.1.0 – Draft

Repository: github.com/wazootech/linked-markdown Reference Implementations: - TypeScript: @wazoo/linked-markdown on JSR (github.com/wazootech/linked-markdown-ts) - Python: linked-markdown on PyPI (github.com/wazootech/linked-markdown-py) License: MIT

Status of this document

This document was published by the JSON for Linked Data Community Group. It is a draft Editor’s Draft and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to cite this document as other than work in progress.

If you wish to make comments regarding this document, please open an issue or contact the group on their public mailing list public-json-ld@w3.org.

This document is governed by the W3C Community Contributor License Agreement (CLA).

1. Introduction

Linked Markdown (LMD) is a specification for structuring typed Markdown documents as first-class semantic graph nodes.

LMD defines a protocol over standard .md files. An LMD document is simultaneously:

• Valid Markdown – renderable by any CommonMark-compliant renderer, including GitHub, Obsidian, VS Code, and Pandoc.
• Valid JSON-LD – frontmatter is a valid JSON-LD node, loadable by any RDF toolchain including rdflib, Apache Jena, and Oxigraph.
• Incrementally adoptable – a single file with an @id field and an @type field is an LMD document. The protocol adds capability without breaking existing workflows.

No custom syntax is introduced. No new file extension is required. The protocol lives entirely in the frontmatter and linking conventions.

1.1. Design goals

1. Zero custom syntax. LMD adds no nonstandard Markdown syntax. All protocol semantics are expressed through standard JSON-LD frontmatter and standard Markdown links.
2. Valid by default. A vanilla .md file with JSON-LD frontmatter is valid LMD. The protocol does not require any special Markdown dialect.
3. Layered capability. A processor may parse or extract – each capability builds on the previous.
4. Standard RDF foundation. LMD does not invent a new data model. It maps directly onto RDF 1.1 and JSON-LD 1.1.
5. Deterministic structure. Two conforming processors that process the same corpus produce the same results.

1.2. Table of contents

• Introduction
  • Design Goals
  • Prior Art and Related Work
  • Protocol Status and Versioning
• Conformance
• The LMD Document Model
• Frontmatter as JSON-LD
• Document Linking
• Serialization
• Security Considerations
• IANA Considerations

1.3. Prior art and related work

• DataBooks (Cagle, Shannon, 2026) – A design pattern for Markdown as semantic infrastructure. LMD adopts the DataBooks vision but diverges by requiring JSON-LD frontmatter (not YAML) and zero custom inline syntax.
• Markdown-LD (ozekik, 2023) – A literate programming approach to embedding Turtle in Markdown body text using inline RDF syntax. Complementary to LMD; LMD addresses document-level typing and validation rather than inline triple annotation.
• MD-LD (davay42, 2026) – A zero-dependency JavaScript library for inline RDF annotations in Markdown using {=iri} syntax. The nonstandard annotation syntax can cause unpredictable rendering. LMD avoids this entirely by restricting protocol semantics to frontmatter.
• json-ld-markdown (iunera, 2025) – A transformer that infers Schema.org JSON-LD from plain Markdown structure (headings, tables, lists). Addresses a different concern (SEO/consumption-oriented inference vs. LMD’s author-intent typing).

1.4. Protocol status and versioning

This specification uses semantic versioning. Versions before 1.0.0 are drafts and may change incompatibly between minor versions. Once 1.0.0 is published, breaking changes require a major version bump.

2. Conformance

2.1. Document conformance

A document conforms to LMD if and only if:

1. It is a syntactically valid Markdown document per the CommonMark specification.
2. It contains exactly one JSON-LD frontmatter block delimited by --- at the start of the file.
3. The frontmatter block is valid JSON-LD per JSON-LD 1.1.

The minimum viable LMD document:

---
---
# My Item
Content here.

A processor MUST NOT reject a conforming LMD document for lacking optional fields such as @id, @type, @context, name, or description.

2.2. Processor conformance

A processor conforms to LMD if it implements the LMD-Extract capability:

• LMD-Extract – Must parse frontmatter from a Linked Markdown document and return the extracted frontMatter string, body string, and attrs object (the parsed JSON-LD node). A processor MUST support all delimiter patterns listed in §4.1. A processor MUST reject malformed frontmatter with a descriptive error.

3. The LMD document model

3.1. Document identity

An LMD document SHOULD declare a canonical IRI in its @id field. When present, this IRI is the document’s identity within the LMD corpus and serves as the RDF subject for all triples generated from the document’s frontmatter.

The @id SHOULD be a dereferenceable HTTP(S) IRI. The @id MAY be a URN or tag URI for documents that are not publicly hosted.

"@id": https://example.org/docs/people/alice-smith

3.2. Document type

An LMD document SHOULD declare its semantic type via @type. The value SHOULD be one or more IRI references, which may use CURIE notation when a @context is present.

@type:
  - schema:Person
  - lmd:Document

3.3. The JSON-LD context

The @context field defines the prefix mappings for CURIE expansion within the frontmatter. A processor MUST resolve all CURIEs in the frontmatter against the active context before producing RDF.

The context MUST include at minimum:

@context:
  schema: https://schema.org/
  lmd: https://linked-markdown.wazoo.dev/ns#

Processors SHOULD provide a default context that includes commonly used prefixes (schema, lmd, rdf, rdfs, xsd, dc, dcterms, foaf). A document may override any default prefix.

3.4. Vocabulary conventions

The lmd: prefix defines terms specific to the LMD protocol layer – document types and versioning. These terms describe a document’s relationship to the LMD protocol rather than its subject matter.

For subject-matter and general-purpose metadata, documents SHOULD use established vocabularies such as Schema.org (schema:), Dublin Core (dcterms:), or FOAF (foaf:). A document that uses only standard vocabularies without any lmd:-prefixed properties is a valid LMD document. LMD does not replace existing vocabularies; it provides a Markdown-compatible substrate in which they coexist.

A processor MAY define equivalence mappings between lmd: terms and terms in other vocabularies to improve interoperability with non-LMD RDF consumers. Such mappings are processor-specific and not required for conformance.

3.5. Body content

The Markdown body text (everything after the frontmatter) is part of the LMD document. An LMD-Extract processor returns the body as a body string alongside the parsed frontmatter. A processor MUST NOT require body content. An LMD document may consist only of frontmatter.

3.6. Links as properties

Body links are not processed as RDF properties in this version of the protocol. A processor MUST NOT generate triples from body Markdown links. Link semantics may be addressed in a future version of the specification.

4. Frontmatter as JSON-LD

4.1. Syntax

Frontmatter MUST be a JSON-LD 1.1 document delimited by a supported delimiter pair. A processor MUST recognize the following delimiter patterns and their associated format expectations:

The format hint determines how the processor parses the frontmatter content: - YAML-family: processed with a YAML 1.x parser (which natively handles JSON). - JSON: processed with a JSON parser. - TOML: processed with a TOML parser.

A processor MUST reject frontmatter whose content cannot be parsed according to the indicated format:

---
{
  "@id": "https://example.org/doc",
  "@type": "schema:Article",
  "@context": {
    "schema": "https://schema.org/"
  },
  "schema:name": "Example Document"
}
---

YAML syntax is also conforming:

---
"@id": https://example.org/doc
"@type": schema:Article
"@context":
  schema: https://schema.org/
name: Example Document
---

### 4.2. Fields

| Field | Type | Description |
|-------|------|-------------|
| `@id` | IRI | Canonical identifier for the document |
| `@type` | IRI or IRI[] | RDF type(s) of the document |
| `@context` | Object | CURIE prefix mappings |
| `name` | string | Human-readable title |
| `description` | string | Short summary (aim for 200 chars or less) |

A processor MUST NOT reject a conforming LMD document for lacking recommended fields.

### 4.4. CURIE resolution

When a `@context` is present, all CURIEs (e.g., `schema:Person`) in the frontmatter are expanded to full IRIs using the context's prefix map. A processor MUST reject a document containing unresolvable CURIEs when no matching prefix is defined.

### 4.5. Relation to RDF

Each frontmatter field that is not a JSON-LD keyword (`@id`, `@type`, `@context`) is mapped to an RDF predicate-value pair with the document's `@id` as the subject. Arrays become multiple triples with the same subject-predicate. Nested objects (when supported by the processor) become blank nodes or named nodes per JSON-LD 1.1 framing rules.

## 5. Document linking

Document-level link resolution is not part of this version of the protocol. A future version may define how intra-corpus links between LMD documents are resolved, validated, and exposed as RDF references.

## 6. Serialization

### 6.1. RDF compatibility

The `attrs` object returned by an LMD-Extract processor is a valid JSON-LD node. Consumers may load it into any JSON-LD 1.1-compatible library to produce RDF 1.1 triples:

- [jsonld.js](https://github.com/digitalbazaar/jsonld.js) (JavaScript / TypeScript)
- [rdflib](https://github.com/linkeddata/rdflib.js) (JavaScript / TypeScript)
- [rdflib](https://github.com/RDFLib/rdflib) (Python)
- [Apache Jena](https://jena.apache.org/) (Java)
- [Oxigraph](https://oxigraph.org/) (Rust / Python)

### 6.2. Context preservation

When the frontmatter includes a `@context`, a processor MUST preserve it in the returned `attrs` object so that downstream consumers can perform correct CURIE expansion and JSON-LD framing.

## 7. Security considerations

IRIs in `@id` and link targets MUST be validated to prevent injection of unexpected schemes (e.g., `javascript:`, `data:`). A processor SHOULD reject IRIs with non-http schemes.

## 8. IANA considerations

Linked Markdown does not currently require any IANA registrations. Future versions may request:
- A media type registration (e.g., `text/lmd` or `application/lmd+json`)
- A URI scheme registration (if a dedicated `lmd:` scheme is desired)

These considerations are deferred until the protocol reaches stability at version 1.0.0.

## Appendix A: complete LMD document example

```markdown
---
"@id": https://example.org/docs/people/alice-smith
"@type":
  - schema:Person
  - lmd:Document
@context:
  schema: https://schema.org/
  lmd: https://linked-markdown.wazoo.dev/ns#
  wiki: https://example.org/docs/
name: Alice Smith
description: Profile page for Alice Smith, software engineer.
schema:givenName: Alice
schema:familyName: Smith
schema:email: alice@example.com
schema:knows:
  - wiki:bob-jones
  - wiki:carol-davis
schema:jobTitle: Senior Software Engineer
---

# Alice Smith

Alice is a senior software engineer at Example Corp.

## Biography

Alice has been building semantic web applications since 2020.

## Related

- See [Bob Jones](bob-jones.md) for a colleague
- See [Carol Davis](carol-davis.md) for another colleague

Appendix B: LMD namespace

The lmd: prefix expands to https://linked-markdown.wazoo.dev/ns#. The following terms are defined:

Appendix C: Glossary

Appendix D: References

• CommonMark Spec – Standard Markdown syntax

• JSON-LD 1.1 – JSON-based RDF serialization

• RDF 1.1 – RDF data model

• RFC 4151 – The ‘tag’ URI scheme

• DataBooks: Markdown as Semantic Infrastructure – Cagle, Shannon 2026