Syntax Reference

Fresh

Complete syntax reference for all MD-LD constructs. Every annotation lives inside {...} curly braces and attaches to a carrier (the text that provides the value).

Context Declarations

Declare namespaces at the top of your document:

markdown

[prefix] <IRI>
[p2] <p1:sub/>    ← prefix folding: p2 is built on p1

Examples:

markdown

[my] <tag:alice@example.org,2026:>
[j]  <my:journal/>          ← j: expands to tag:alice@example.org,2026:journal/...
[ex] <http://example.org/>

Built-in prefixes (always available, no declaration needed):

Prefix	IRI
`rdf`	`http://www.w3.org/1999/02/22-rdf-syntax-ns#`
`rdfs`	`http://www.w3.org/2000/01/rdf-schema#`
`xsd`	`http://www.w3.org/2001/XMLSchema#`
`sh`	`http://www.w3.org/ns/shacl#`
`prov`	`http://www.w3.org/ns/prov#`
`label`	shorthand for `rdfs:label`
`comment`	shorthand for `rdfs:comment`

Subject Declarations

Set the current subject (emits no quads by itself):

markdown

{=my:node}          ← set subject to full IRI
{=#fragment}        ← set subject to current-base#fragment
{=}                 ← clear subject entirely

A subject declaration inside a heading or other carrier:

markdown

# Apollo 11 {=ex:apollo11}
## Design Task {=#task-design}

A standalone subject declaration on its own line:

markdown

{=my:ProjectAlpha}
[3] {my:taskCount ^^xsd:integer}

Value Carriers

Carriers hold the literal value that gets attached to a predicate. MD-LD supports multiple carrier types:

Syntax	Example	Notes
`[text]`	`[34]`	Inline bracketed span
`text`	`Alice`	Bold emphasis
`text`	`v1.2.0`	Code span
`# text`	`# Journal`	Heading (any level)
`- text`	`- Design`	Unordered list item
`1. text`	`1. First`	Ordered list item
`> text`	`> Must be unique`	Blockquote
```text```	code block	Fenced code block

Each carrier attaches to the following {...} annotation block.

Predicate Forms

Three forms determine the type of graph edge:

Form	Edge	Example	Meaning
`p` (bare)	S to literal	`[Alice] {my:name}`	Literal property
`?p`	S to O	`[Bob] {+my:bob ?my:knows}`	Object property (forward)
`!p`	O to S	`[Tag] {+my:tag !my:taggedIn}`	Reverse property

markdown

[Alice] {my:name}                    ← S → "Alice" literal
[Bob] {+my:bob ?my:knows}            ← S → my:bob (object link)
[Tag] {+my:tag !my:taggedIn}         ← my:tag → S (reverse link)

Object Declarations

Introduce a new object node with +:

markdown

{+my:node}              ← declare object (full IRI)
{+#fragment}            ← declare object (fragment IRI)
{+my:node ?predicate}   ← declare object and link
{+my:node !predicate}   ← declare object with reverse link
{+my:node .my:Class}    ← declare object and type it

Object declarations can carry multiple tokens:

markdown

[Neil Armstrong] {+ex:armstrong ?ex:commander .prov:Person label}

This introduces ex:armstrong as an object, links it via ex:commander, types it as prov:Person, and assigns the carrier text as its rdfs:label.

Type Declarations

Emit an rdf:type triple with the . prefix:

markdown

{.my:Class}             ← subject rdf:type my:Class
{.prov:Person}          ← subject rdf:type prov:Person

Multiple types in one annotation:

markdown

## Report {=my:report .prov:Entity .my:Document label}

Literal Modifiers

Datatypes

Append ^^xsd:type to specify the literal datatype:

markdown

[2026-05-06]            {my:date ^^xsd:date}
[2026-05-06T09:00:00Z]  {my:ts ^^xsd:dateTime}
[42]                    {my:count ^^xsd:integer}
[3.14]                  {my:ratio ^^xsd:decimal}
[true]                  {my:active ^^xsd:boolean}
[P1Y6M]                 {my:duration ^^xsd:duration}

Common XSD types:

Type	Example value
`xsd:string`	`"Hello"`
`xsd:integer`	`42`
`xsd:decimal`	`3.14`
`xsd:double`	`3.14e2`
`xsd:boolean`	`true` / `false`
`xsd:date`	`2026-05-06`
`xsd:dateTime`	`2026-05-06T09:00:00Z`
`xsd:time`	`14:30:00Z`
`xsd:duration`	`P1Y6M`
`xsd:anyURI`	`https://example.org/`

Language Tags

Append @lang to tag the literal language:

markdown

[Hello] {my:greeting @en}
[Hola] {my:greeting @es}
[Bonjour] {my:greeting @fr}

Polarity — Retractions

Prefix any annotation token with - to retract it:

markdown

-p      retract literal        [Alice] {-my:name}
-?p     retract object link    [Bob] {+my:bob -?my:knows}
-!p     retract reverse link   [Tag] {+my:tag -!my:taggedIn}
-.Class retract type           {-.my:Draft}

When a retraction matches a positive assertion in the same document, both cancel out (neither appears in output). When no match is found, the retraction becomes an external retraction in the remove array.

Example — inline correction:

markdown

[my] <tag:carol@example.org,2026:>

New student [Alice] {=ex:new-student .prov:Person ex:name} is our [class] {+ex:my-class !member}.

**Correction:** [Her] {=ex:new-student} name is not [Alice] {-ex:name}, it's [Ellie] {ex:name}.

Combining Tokens

All tokens can appear in a single annotation block. Order is flexible:

markdown

{=my:node .my:Class label}
{+my:target ?my:rel sh:name}
{=my:doc -.ex:Draft .ex:Published -my:version}
## Alice {=my:alice .prov:Person label comment}
[Neil] {+ex:armstrong ?ex:commander .prov:Person label}

Standalone Subject Declarations

A subject declaration can stand alone on its own line (not attached to a carrier):

markdown

{=my:ProjectAlpha}

[3] {my:taskCount ^^xsd:integer}
Continued: [yes] {my:continues}

Annotation Attachment Points Summary

INLINE
[text] {annotation}          ← bracketed span
**text** {annotation}        ← bold
`text` {annotation}          ← code span

BLOCK
# Heading {annotation}       ← heading (1-6 levels)
- item {annotation}          ← list item
> blockquote {annotation}    ← blockquote
```code``` {annotation}      ← code fence (annotation after closing fence)

STANDALONE
{=iri}                       ← subject declaration with no carrier

Grammar Guarantees (Normative)

From the formal specification

Attribute token order is semantically unordered
Lists are pure Markdown structure with no semantic scope propagation
Nested lists establish a new semantic scope
No implicit inheritance across list levels
Deterministic, streaming-friendly parsing
Round-trip safe: MD-LD to RDF to MD-LD cycles preserve semantics
No semantic inference at syntax level

Forbidden Constructs

Not expressible in MD-LD grammar

Blank nodes — every node must be a named IRI
Key-value pairs inside braces — always use a carrier
Nested attribute blocks — {...{...}...} is not valid
Implicit subjects or predicates — everything must be explicit
Structural inference — the parser never guesses
Semantic list propagation — each list item annotation is independent

Syntax Reference ​

Context Declarations ​

Subject Declarations ​

Value Carriers ​

Predicate Forms ​

Object Declarations ​

Type Declarations ​

Literal Modifiers ​

Datatypes ​

Language Tags ​

Polarity — Retractions ​

Combining Tokens ​

Standalone Subject Declarations ​

Annotation Attachment Points Summary ​

Grammar Guarantees (Normative) ​

Forbidden Constructs ​

Syntax Reference

Context Declarations

Subject Declarations

Value Carriers

Predicate Forms

Object Declarations

Type Declarations

Literal Modifiers

Datatypes

Language Tags

Polarity — Retractions

Combining Tokens

Standalone Subject Declarations

Annotation Attachment Points Summary

Grammar Guarantees (Normative)

Forbidden Constructs