MD-LD SOP

Appearance

Subject System ​

Fresh

The subject system is the mechanism by which MD-LD tracks "what we are currently talking about." Every triple requires a subject — an IRI that identifies the entity being described. The subject system manages this context across a document.

Subject Declarations ​

A subject declaration sets the current subject for all following annotations:

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

Subject declarations never emit triples themselves. They only change the parser's context. All annotations following a subject declaration apply to that subject until a new declaration is encountered.

In Headings ​

The most common pattern: declaring the subject in a heading annotation:

markdown
## Alice {=my:alice .prov:Person label}

This:

  1. Sets the current subject to my:alice
  2. Types it as prov:Person
  3. Assigns "Alice" as its rdfs:label

All subsequent annotations in the section apply to my:alice until the next heading changes the subject.

Standalone ​

A standalone subject declaration on its own line:

markdown
{=my:ProjectAlpha}

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

This resets the subject mid-document without requiring a new heading.

Clear Subject ​

Use bare {=} to explicitly clear the subject:

markdown
{=}

[This text has no subject] {my:orphanedAnnotation}  ← ignored: no subject

Fragment Subjects ​

Fragments (#name) create IRIs relative to the current base subject:

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

# Project {=my:project .my:Project label}

- Design {+#task-design ?my:hasTask .my:Task label}

## Design Task {=#task-design}

Status: [done] {my:status}

When {=#task-design} is parsed in the context where the base subject is my:project, it sets the current subject to my:project#task-design.

{+#fragment} references that same IRI as an object without changing the current subject:

markdown
[+#task-design ?my:hasTask]  ← creates a link to my:project#task-design

Subject Persistence ​

Subject context persists until explicitly changed:

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

## Alice {=my:alice .prov:Person label}

[alice@example.com] {my:email}        ← subject: my:alice
[Berlin] {my:city}                    ← subject: my:alice

## Bob {=my:bob .prov:Person label}

[bob@example.com] {my:email}          ← subject: my:bob

This is the TTL pattern applied to Markdown: declare a node, write all its properties, then move to the next node.

Prefix Declarations ​

Prefixes establish the namespace for IRIs:

markdown
[my] <tag:alice.smith@example.org,2026:>

The prefix my now resolves: my:alice becomes tag:alice.smith@example.org,2026:alice.

Prefix Folding ​

Prefixes can be built on top of other prefixes:

markdown
[my] <tag:alice.smith@example.org,2026:>
[j]  <my:journal/>
[p]  <my:projects/>

Now:

  • j:2026-05-06 expands to tag:alice.smith@example.org,2026:journal/2026-05-06
  • p:alpha expands to tag:alice.smith@example.org,2026:projects/alpha

Resolution rules:

  • Prefixes must be declared before referenced (no forward references)
  • Circular references are treated as literal strings
  • Later declarations override earlier ones
  • Single-pass parsing is maintained

Built-in Prefixes ​

These are always available without declaration:

PrefixIRI
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfshttp://www.w3.org/2000/01/rdf-schema#
xsdhttp://www.w3.org/2001/XMLSchema#
shhttp://www.w3.org/ns/shacl#
provhttp://www.w3.org/ns/prov#

Additionally, label is shorthand for rdfs:label and comment is shorthand for rdfs:comment.

The tag: URI Pattern ​

The recommended approach for personal namespaces is the RFC 4151 tag: scheme:

tag:alice.smith@example.org,2026:

This gives you a globally unique namespace without requiring:

  • A domain name
  • A server
  • A central registry
  • A platform account

The authority (alice.smith@example.org) and year (2026) together ensure uniqueness. You are the owner of everything under this namespace for all time.

Subject Chaining Pattern ​

The clean pattern for multi-node documents is to declare all outgoing links from a node before moving on to define each linked node in its own section:

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

# Project Alpha {=my:alpha .my:Project label}

Tasks: [design] {+#design ?my:task sh:name}, [build] {+#build ?my:task sh:name}.

## Design {=#design .my:Task label}
[done] {my:status}

## Build {=#build .my:Task label}
[in-progress] {my:status}

The parent node lists all its {+#fragment} links in one place. Each child then gets its own section. No subject resets needed. The document reads top-to-bottom in dependency order.

Subject Resolution in Object Declarations ​

Object declarations ({+IRI}) introduce a new IRI as the object of relationships but do not change the current subject:

markdown
## Alice {=my:alice .prov:Person label}

Knows [Bob] {+my:bob ?my:knows}.    ← subject stays my:alice
                                       my:bob is introduced as an object only

To also define Bob's own properties, Bob needs his own subject declaration:

markdown
## Bob {=my:bob .prov:Person label}
[bob@example.com] {my:email}