Quick Reference

Fresh

Everything you need without reading the full docs.

Installation

pnpm install mdld-parse
# or
npm install mdld-parse

import { parse, generate, merge, locate, generateNode } from 'mdld-parse';

Syntax Cheat Sheet

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

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

TYPES
{.my:Class}    ← rdf:type triple

LITERALS
[value] {predicate}             ← plain literal
[value] {predicate @en}         ← language-tagged literal
[value] {predicate ^^xsd:date}  ← typed literal

OBJECT PROPERTIES
[text] {+my:target ?my:rel}     ← S → target (forward)
[text] {+my:target !my:member}  ← target → S (reverse)
[text] {+#frag ?my:rel}         ← fragment object

POLARITY (RETRACTIONS)
[v] {-my:pred}        ← retract literal
[t] {+O -?my:rel}     ← retract object link
{-.my:Class}          ← retract type

COMBINING
{=my:node .my:Class label}
{+my:target ?my:rel .my:Type label}
{=my:doc -.ex:Draft .ex:Published}

Datatype Quick Reference

[2026-05-06]       {my:d ^^xsd:date}
[14:30:00Z]        {my:t ^^xsd:time}
[2026-05-06T14:30:00Z] {my:dt ^^xsd:dateTime}
[42]               {my:n ^^xsd:integer}
[3.14]             {my:r ^^xsd:decimal}
[true]             {my:b ^^xsd:boolean}
[P1Y6M]            {my:dur ^^xsd:duration}
[Hello] {my:l @en}
[Hola]  {my:l @es}

API Quick Reference

parse()

const result = parse({ text, context, dataFactory, graph });

result.quads          // RDF/JS quad array (final state)
result.remove         // External retractions
result.statements     // Elevated rdf:Statement quads (golden graph)
result.origin         // Provenance: { quadIndex, blocks, spans }
result.primary        // { subject, type, label, comment }
result.primarySubject // First non-fragment subject IRI (string)
result.context        // Prefix map
result.md             // Clean markdown without annotations

generate()

const { text, context, compactStats } = generate({
  quads,            // required
  context,          // optional: prefix map
  primarySubject,   // optional: IRI to place first
  compactInline,    // optional: default false
  renderReverse,    // optional: default false
  remove,           // optional: quads to retract
  lang              // optional: preferred label language
});

merge()

const merged = merge([text1, text2, text3], { context });

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

locate()

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

location?.range        // [start, end] character positions
location?.value        // Raw carrier text
location?.carrierType  // 'heading' | 'blockquote' | 'para' | 'span'
location?.polarity     // '+' | '-'

generateNode()

const { text } = generateNode({
  quads,
  focusIRI: 'http://example.org/alice',
  context,
  compactInline: true,  // default: true
  renderReverse: true,  // default: true
  lang: 'en'
});

Common Patterns

Define a person

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

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

Link two nodes

## Alice {=my:alice .prov:Person label}
Works at [ACME] {+my:acme ?my:worksAt}.
Knows [Bob] {+my:bob ?my:knows}.

Provenance activity

## 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 (append-only ledger)

# v1 entry {=j:2026-05-01 .j:Entry j:date ^^xsd:date label}
Project Alpha: [planning] {+my:alpha ?my:status}

# v2 entry {=j:2026-05-10 .j:Entry j:date ^^xsd:date label}
{=my:alpha}
[planning] {-my:status}
[active] {my:status}

const { quads } = merge([v1Text, v2Text]);
// quads: my:alpha my:status "active"

rdf:Statement with confidence

## Claim {=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}

SHACL validation shape

## User Shape {=my:UserShape .sh:NodeShape label}
Validates [User] {+my:User ?sh:targetClass} with:
[email rule] {+my:UserShape-email ?sh:property sh:name}.

### Email rule {=my:UserShape-email .sh:PropertyShape}
Path: [my:email] {+my:email ?sh:path}
Required: [1] {sh:minCount ^^xsd:integer}
> User must have an email address. {sh:message}

Troubleshooting

No quads produced

Check: Is there a subject declaration {=IRI} before the annotations?

## Alice {=my:alice label}   ← subject + label works
[Alice] {my:name}            ← literal property works

[Alice] {my:name}            ← no subject = no triple

Prefix expansion fails

Check: Is the prefix declared before use? Forward references are not allowed.

[j] <my:journal/>    ← ERROR: my: not declared yet
[my] <tag:you@example.com,2026:>

[my] <tag:you@example.com,2026:>
[j]  <my:journal/>   ← OK: my: is declared first

Retraction not cancelling

Check: Are the subject, predicate, and object exactly the same? Retractions use exact string matching.

[Alice] {my:name}    ← emits: S my:name "Alice"
[Alice] {-my:name}   ← cancels: must match exactly

If the retraction is in a different document, it becomes an external retraction in remove. Use merge() to resolve it.

Fragment subject not resolving

Check: Is there a base subject established first?

{=#fragment}         ← ERROR: no base subject
## Doc {=my:doc}
{=#fragment}         ← OK: base is my:doc, fragment resolves to my:doc#fragment

List items not producing triples

Check: Each list item needs its own annotation. There is no semantic scope inheritance from a heading to list items.

## Collection {=my:collection}
- Item 1                         ← no annotation = no triple
- Item 1 {+my:item1 ?my:has}    ← explicit annotation = triple

Invariants to Remember

Rule	Example
Carriers hold values	[42] {my:age ^^xsd:integer} not {my:age "42"^^xsd:integer}
{=...} sets context only	Never emits a triple
No blank nodes	Every node needs a named IRI
Declare all prefixes	No forward references
label = rdfs:label	Always available without prefix
quads ∩ remove = ∅	Parser enforces this automatically
List items are independent	No parent-to-child semantic scope