MD-LD SOP

Appearance

One Page Quick Reference ​

Fresh

Essential MD-LD patterns on one page. Bookmark this.

Setup ​

bash
pnpm install mdld-parse
javascript
import { parse, generate, merge } from 'mdld-parse';

Prefix Declarations ​

markdown
[my] <tag:you@example.com,2026:>   ← personal namespace
[j]  <my:journal/>                  ← sub-prefix (folded)
[ex] <http://example.org/>          ← external namespace

Built-in (no declaration needed): rdf, rdfs, xsd, sh, prov, label, comment

Subjects ​

markdown
{=my:node}       ← set subject to named IRI
{=#fragment}     ← set subject to base#fragment
{=}              ← clear subject

# Heading {=my:node}          ← subject via heading
## Section {=#fragment}       ← fragment via heading

Types ​

markdown
{.my:Class}                   ← rdf:type triple
## Alice {=my:alice .prov:Person label}   ← subject + type + label

Literals ​

markdown
[value] {predicate}           ← plain literal
[value] {predicate @en}       ← language tag
[value] {predicate ^^xsd:date} ← typed literal

**bold** {predicate}          ← bold carrier
`code` {predicate}            ← code carrier
> blockquote {predicate}      ← blockquote carrier
- list item {predicate}       ← list item carrier

Datatype Quick Reference ​

markdown
[2026-05-06]      {my:date ^^xsd:date}
[09:30:00Z]       {my:time ^^xsd:time}
[2026-05-06T09:00:00Z] {my:ts ^^xsd:dateTime}
[42]              {my:n ^^xsd:integer}
[3.14]            {my:r ^^xsd:decimal}
[true]            {my:flag ^^xsd:boolean}
[P1Y6M]           {my:dur ^^xsd:duration}

Object Properties ​

markdown
[Bob] {+my:bob ?my:knows}         ← S → my:bob (forward)
[Tag] {+my:tag !my:taggedIn}      ← my:tag → S (reverse)
[Item] {+#fragment ?my:has}       ← fragment object
[Neil] {+ex:neil ?ex:commander .prov:Person label}  ← object with type+label

Predicate Forms ​

FormEdgeExample
pS to literal[Alice] {my:name}
?pS to object[Bob] {+my:bob ?my:knows}
!pobject to S[Tag] {+my:tag !my:taggedIn}

Polarity (Retractions) ​

markdown
[Alice] {-my:author}          ← retract literal
[Bob] {+my:bob -?my:knows}    ← retract object link
[Tag] {+my:tag -!my:member}   ← retract reverse link
{-.my:Draft .my:Published}    ← retract type + add type

Combining Tokens ​

markdown
## Alice {=my:alice .prov:Person label}
[Neil] {+ex:neil ?ex:commander .prov:Person label}
{=my:doc -.ex:Draft .ex:Published -my:version}

Parse ​

javascript
const result = parse({ text: mdldString });

result.quads          // RDF/JS quad array
result.remove         // External retractions
result.statements     // Elevated rdf:Statement quads
result.origin         // Provenance tracking
result.primary        // { subject, type, label, comment }
result.primarySubject // First non-fragment subject IRI
result.context        // Prefix map
result.md             // Clean markdown (no annotations)

Generate ​

javascript
const { text } = generate({
  quads,
  context,
  primarySubject: 'http://example.org/doc',
  compactInline: false,
  renderReverse: false,
  lang: 'en'
});

Merge (CRDT) ​

javascript
const merged = merge([v1Text, v2Text, v3Text]);

merged.quads           // Final resolved state
merged.remove          // Unresolved external retractions
merged.primarySubjects // Array of canonical IRIs
merged.primary         // Array of primary metadata objects

Locate (UI Navigation) ​

javascript
const location = locate(quad, result.origin);

location.range        // { start, end } character range
location.value        // Raw carrier text
location.carrierType  // 'heading' | 'blockquote' | 'span'
location.polarity     // '+' | '-'

Invariants (Never Violate) ​

  • Every triple needs a carrier — never {predicate "value"}
  • {=...} never emits a triple — it only sets context
  • No blank nodes — every node must be a named IRI
  • label = rdfs:label, comment = rdfs:comment
  • Declare all prefixes you use
  • Define nodes once — type and label in one place only

Common Patterns ​

Person record ​

markdown
[my] <tag:you@example.com,2026:>

## Alice {=my:alice .prov:Person label}
[alice@example.com] {my:email}
[2026-01-15] {my:joinDate ^^xsd:date}

Journal entry ​

markdown
[my] <tag:you@example.com,2026:>
[j]  <my:journal/>

# 2026-05-06 {=j:2026-05-06 .j:Entry j:date ^^xsd:date label}

[Good day] {j:summary}
Met [Bob] {+my:bob ?j:met}.

Activity with provenance ​

markdown
[my] <tag:you@example.com,2026:>

## Analysis {=my:run-1 .prov:Activity label}

Started: [2026-05-06T09:00:00Z] {prov:startedAtTime ^^xsd:dateTime}
By:      [Alice] {+my:alice ?prov:wasAssociatedWith}
Used:    [dataset] {+my:dataset ?prov:used}
Made:    [report] {+my:report ?prov:generated}

Versioned document ​

markdown
v1: [Alice] {my:author}  [Draft] {my:status}
v2: [Alice] {-my:author}  [Bob] {my:author}  [Draft] {-my:status}  [Published] {my:status}
javascript
const { quads } = merge([v1, v2]);
// quads contains: author=Bob, status=Published

rdf:Statement (reification) ​

markdown
## Claim 1 {=my:claim-1 .rdf:Statement label}

[Alice] {+my:alice ?rdf:subject} [knows] {+my:knows ?rdf:predicate} [Bob] {+my:bob ?rdf:object}.
Confidence: [0.9] {my:confidence ^^xsd:decimal}