mdld-parse 0.9.3 → 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,322 +1,816 @@
1
- # MD-LD One Page Guide
1
+ # MD-LD Authoring Guide
2
2
 
3
- **Semantic Markdown, no guessing, no magic**
3
+ MD-LD is Markdown with semantic annotations. You write normal prose — notes, plans, journals, documentation — and sprinkle in `{...}` curly-brace hints that tell a parser how to build a knowledge graph from your text. Everything outside `{...}` is free-form and ignored by the graph. You don't have to annotate everything — only what you want in the graph.
4
4
 
5
- MD-LD lets you **add meaning without breaking Markdown**.
6
- Add `{...}` → you get an RDF graph.
7
- Delete `{...}` → plain Markdown remains.
5
+ Think of it like highlighters. You pick a color scheme first (prefix declarations), then highlight the parts of your text that carry meaning.
8
6
 
9
- Everything semantic is **explicit**, **local**, and **traceable**.
7
+ ---
8
+
9
+ ## 1. Your First Note
10
+
11
+ Start with plain Markdown. This is always valid MD-LD — it just produces no graph data:
12
+
13
+ ```md
14
+ # Alice's Journal
15
+
16
+ Hi! My name is Alice Smith. This is my personal journal.
17
+ ```
18
+
19
+ Now add your first annotation. Two things happen: you declare a prefix, and you tag the heading as a named node with a type and a label:
20
+
21
+ ```md
22
+ [my] <tag:alice.smith@example.org,2026:>
23
+
24
+ # Alice's Journal
25
+
26
+ ## Alice {=my:alice .prov:Person label}
27
+
28
+ Hi! My name is Alice Smith. This is my personal journal.
29
+ ```
30
+
31
+ That one annotation `{=my:alice .prov:Person label}` did three things:
32
+ - `=my:alice` — declared this heading as a named node (the *subject*)
33
+ - `.prov:Person` — typed it as a Person
34
+ - `label` — used the heading text "Alice" as its display label (`rdfs:label`)
35
+
36
+ The generated triples:
37
+
38
+ ```ttl
39
+ @prefix my: <tag:alice.smith@example.org,2026:>.
40
+ @prefix prov: <http://www.w3.org/ns/prov#>.
41
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
42
+
43
+ my:alice a prov:Person;
44
+ rdfs:label "Alice".
45
+ ```
10
46
 
11
47
  ---
12
48
 
13
- ## 0. Mental model (read once)
49
+ ## 2. Your Personal IRI — the `tag:` Pattern
14
50
 
15
- MD-LD always writes **triples**:
51
+ Every node in a knowledge graph needs a unique identifier — an IRI. If you have a website, use its URL. If you don't, use the RFC 4151 `tag:` scheme. It's yours to own with just an email address or domain:
16
52
 
17
53
  ```
18
- Subject ──predicate──▶ Object / Literal
54
+ tag:alice.smith@example.org,2026:
55
+ │ │ └─ your subspace starts here
56
+ │ └──── year you controlled this email
57
+ └─────────────────────────── your authority (email or domain)
58
+ ```
59
+
60
+ Declare it once at the top of your document as a prefix:
61
+
62
+ ```md
63
+ [my] <tag:alice.smith@example.org,2026:>
19
64
  ```
20
65
 
21
- That’s it.
66
+ Then use it with the short form anywhere:
67
+
68
+ | Short form | Expands to |
69
+ |---|---|
70
+ | `my:alice` | `tag:alice.smith@example.org,2026:alice` |
71
+ | `my:journal/2026-05-06` | `tag:alice.smith@example.org,2026:journal/2026-05-06` |
72
+ | `my:place/central-park` | `tag:alice.smith@example.org,2026:place/central-park` |
22
73
 
23
- At any annotation `{...}`, there may be:
74
+ You can also add a sub-prefix for a specific domain of your notes:
24
75
 
25
- | Symbol | Meaning |
26
- | ------ | ---------------------------------------------------- |
27
- | **S** | current subject (IRI) |
28
- | **O** | object IRI (from link, image, or `{+iri}`) |
29
- | **L** | literal text (from the attached Markdown span/block) |
76
+ ```md
77
+ [my] <tag:alice.smith@example.org,2026:>
78
+ [j] <my:journal/>
79
+ ```
30
80
 
31
- No subject → no triple
32
- No guessing → no triple
33
- No `{...}` → no semantics
81
+ Now `j:2026-05-06` expands to `tag:alice.smith@example.org,2026:journal/2026-05-06`. Prefix folding — short prefixes built on top of other prefixes — keeps long IRIs readable.
82
+
83
+ **Built-in prefixes** (no declaration needed):
84
+
85
+ ```
86
+ rdf http://www.w3.org/1999/02/22-rdf-syntax-ns#
87
+ rdfs http://www.w3.org/2000/01/rdf-schema#
88
+ xsd http://www.w3.org/2001/XMLSchema#
89
+ sh http://www.w3.org/ns/shacl#
90
+ prov http://www.w3.org/ns/prov#
91
+ ```
34
92
 
35
93
  ---
36
94
 
37
- ## 1. Start with a document that *already is* a graph
95
+ ## 3. Saying Things About Things — Literals
96
+
97
+ Once you've set a subject with `{=...}`, every annotated value below it belongs to that subject until you change it. The basic pattern is:
98
+
99
+ ```
100
+ [value] {predicate}
101
+ ```
38
102
 
39
- Always declare a subject first.
103
+ The `[value]` is the *carrier* — it can be a bracketed span, bold text, a code span, a heading, a list item, or a blockquote. The `{predicate}` names the property.
40
104
 
41
105
  ```md
42
- [alice] <tag:alice@example.com,2026:>
106
+ [my] <tag:alice.smith@example.org,2026:>
107
+
108
+ ## Alice {=my:alice .prov:Person label}
43
109
 
44
- # Walnut Bread {=alice:walnut-bread .Recipe name}
110
+ Age: [34] {my:age ^^xsd:integer}
111
+ City: [Berlin] {my:city @de}
112
+ Bio: **Loves hiking and graph databases.** {my:bio @en}
45
113
  ```
46
114
 
47
- This emits:
115
+ Generates:
48
116
 
49
- ```turtle
50
- tag:alice@example.com,2026:walnut-bread
51
- a schema:Recipe ;
52
- schema:name "Walnut Bread" .
117
+ ```ttl
118
+ my:alice a prov:Person;
119
+ rdfs:label "Alice";
120
+ my:age "34"^^xsd:integer;
121
+ my:city "Berlin"@de;
122
+ my:bio "Loves hiking and graph databases."@en.
53
123
  ```
54
124
 
55
- **Why this matters**
125
+ **Carriers at a glance:**
56
126
 
57
- * Your note is already an addressable node
58
- * Everything that follows attaches to it
59
- * This is how “casual notes” become “knowledge”
127
+ | Syntax | Example | When to use |
128
+ |---|---|---|
129
+ | `[text]` | `[34]` | Inline spans, values mid-sentence |
130
+ | `**text**` | `**Alice**` | Bold emphasis on a value |
131
+ | `` `text` `` | `` `v1.2.0` `` | Code/version values |
132
+ | `# text` | `# Journal` | Heading as value |
133
+ | `- text` | `- Design` | List item as value |
134
+ | `> text` | `> Must be unique` | Block quote as message/note |
135
+ | ` ```text``` ` | code block | Multi-line code or raw data |
136
+
137
+ **Datatype shortcuts:**
138
+
139
+ ```md
140
+ [2026-05-06] {my:date ^^xsd:date}
141
+ [14:30:00Z] {my:time ^^xsd:time}
142
+ [42] {my:count ^^xsd:integer}
143
+ [3.14] {my:ratio ^^xsd:decimal}
144
+ [true] {my:active ^^xsd:boolean}
145
+ ```
60
146
 
61
147
  ---
62
148
 
63
- ### 1.1. Prefix Folding: Build Your Namespace
149
+ ## 4. Connecting Things — Object Properties
64
150
 
65
- Create hierarchical namespaces by referencing previous prefixes:
151
+ To link two nodes together, use `{+IRI ?predicate}` on the carrier that names the target:
152
+
153
+ ```
154
+ [label for target] {+target:iri ?predicate}
155
+ ```
156
+
157
+ The `+` introduces the *object node*. The `?` marks a forward object property (subject → object).
66
158
 
67
159
  ```md
68
- # Your domain authority
69
- [my] <tag:mymail@domain.com,2026:>
160
+ [my] <tag:alice.smith@example.org,2026:>
161
+
162
+ ## Alice {=my:alice .prov:Person label}
70
163
 
71
- # Build the hierarchy
72
- [j] <my:journal:>
73
- [p] <my:property:>
74
- [c] <my:class:>
164
+ Alice knows [Bob] {+my:bob ?my:knows}.
165
+ She lives near [Central Park] {+my:central-park ?my:livesNear}.
75
166
 
76
- # Use in content
77
- # 2026-01-27 {=j:2026-01-27 .c:Event p:date ^^xsd:date}
167
+ ## Bob {=my:bob .prov:Person label}
168
+
169
+ ## Central Park {=my:central-park .prov:Location label}
78
170
  ```
79
171
 
80
- **Resolves to:**
81
- - `j:2026-01-27` → `tag:mymail@domain.com,2026:journal:2026-01-27`
82
- - `c:Event` → `tag:mymail@domain.com,2026:class:Event`
83
- - `p:date` → `tag:mymail@domain.com,2026:property:date`
172
+ Generates:
173
+
174
+ ```ttl
175
+ my:alice a prov:Person;
176
+ rdfs:label "Alice";
177
+ my:knows my:bob;
178
+ my:livesNear my:central-park.
179
+ my:bob a prov:Person;
180
+ rdfs:label "Bob".
181
+ my:central-park a prov:Location;
182
+ rdfs:label "Central Park".
183
+ ```
84
184
 
85
- Perfect for personal knowledge graphs without external dependencies.
185
+ Each node is defined exactly once, in its own heading. The `{+my:bob ?my:knows}` annotation only asserts the link — type and label belong on Bob's own section. This keeps the graph clean with no duplicate triples.
86
186
 
87
- ---
187
+ ### Reverse Links — `!predicate`
88
188
 
89
- ## 2. Value carriers (what can hold meaning)
189
+ Sometimes it's more natural to write the relationship from the other direction. Use `!` for a reverse property — the triple goes *from* the object *to* the current subject:
90
190
 
91
- Only these Markdown forms can emit values:
191
+ ```md
192
+ ## Cookbook {=my:cookbook .my:Collection label}
92
193
 
93
- **Inline**
194
+ Recipes in this collection:
94
195
 
95
- * `[text] {...}`
96
- * `*text* {...}`, `**text** {...}`
97
- * `` `code` {...}``
196
+ - Apple Pie {+my:apple-pie !my:partOf}
197
+ - Peach Pie {+my:peach-pie !my:partOf}
98
198
 
99
- **Block**
199
+ ## Apple Pie {=my:apple-pie .my:Recipe label}
100
200
 
101
- * Headings
102
- * List items
103
- * Blockquotes
104
- * Code blocks (fence with `{...}`)
201
+ ## Peach Pie {=my:peach-pie .my:Recipe label}
202
+ ```
105
203
 
106
- If `{...}` cannot clearly attach → **nothing is emitted**.
204
+ This writes `my:apple-pie my:partOf my:cookbook` — the arrow points from the list item back to the collection. Each recipe is then defined in its own section with type and label there.
107
205
 
108
206
  ---
109
207
 
110
- ## 3. The three predicate forms (the whole algebra)
208
+ ## 5. Fragment IRIs — Structuring Within a Document
209
+
210
+ Fragments (`#section`) let you create multiple related nodes inside one document without long IRIs:
211
+
212
+ ```md
213
+ [my] <tag:alice.smith@example.org,2026:>
214
+
215
+ # Project Alpha {=my:ProjectAlpha .my:Project label}
111
216
 
112
- Every triple is written using **one of three predicate shapes**:
217
+ - Design {+#task-design ?my:hasTask .my:Task label}
218
+ - Build {+#task-build ?my:hasTask .my:Task label}
219
+ - Ship {+#task-ship ?my:hasTask .my:Task label}
113
220
 
114
- | Form | Emits |
115
- | ----- | ------- |
116
- | `p` | `S → L` |
117
- | `?p` | `S → O` |
118
- | `!p` | `O → S` |
221
+ ## Design Task {=#task-design}
119
222
 
120
- Nothing else exists.
223
+ Status: [done] {my:status}
121
224
 
122
- ### Example — all three at once
225
+ ## Build Task {=#task-build}
226
+
227
+ Status: [in-progress] {my:status}
228
+ ```
229
+
230
+ `{=#task-design}` sets the subject to `my:ProjectAlpha#task-design` (it appends the fragment to the current base IRI). `{+#task-design}` references that same IRI as an object.
231
+
232
+ When you need to return to the parent node mid-document, just reset the subject:
123
233
 
124
234
  ```md
125
- [alice] <tag:alice@example.com,2026:>
235
+ {=my:ProjectAlpha}
126
236
 
127
- [Bread] {name}
128
- [Walnut] {+alice:walnut ?hasIngredient}
129
- [Recipe](https://en.wikipedia.org/wiki/Recipe) {!hasPart}
237
+ [3] {my:taskCount ^^xsd:integer}
130
238
  ```
131
239
 
132
- Never use shortened CURIE in regular Markdown links. They must be valid URLs for the browser to navigate to.
240
+ Use `{=}` (bare) to clear the subject entirely — subsequent annotations will have no subject until the next `{=...}`.
133
241
 
134
242
  ---
135
243
 
136
- ## 4. Literals are always local
244
+ ## 6. The Three Predicate Forms
245
+
246
+ Every annotation uses one of three forms:
137
247
 
138
- Text comes **only** from the attached carrier.
248
+ | Form | Meaning | Edge | Example |
249
+ |---|---|---|---|
250
+ | `p` | Literal property | S → literal | `[Alice] {my:name}` |
251
+ | `?p` | Object property | S → O | `[Bob] {+my:bob ?my:knows}` |
252
+ | `!p` | Reverse property | O → S | `[Tag] {+my:tag !my:taggedIn}` |
253
+
254
+ You can combine multiple predicates in one annotation:
139
255
 
140
256
  ```md
141
- [2024] {published ^^xsd:gYear}
142
- [Delicious bread] {description @en}
257
+ ## Alice {=my:alice .prov:Person label}
143
258
  ```
144
259
 
145
- No datatype or language is ever inferred.
260
+ This sets subject, types it, and assigns a label — all at once. Order within `{...}` is flexible.
146
261
 
147
262
  ---
148
263
 
149
- ## 5. Object IRIs (links or `{+iri}`)
264
+ ## 7. A Journal Entry — Putting It Together
150
265
 
151
- Objects exist only if explicitly present.
266
+ Here's a complete personal journal note using everything above:
152
267
 
153
268
  ```md
154
- [alice] <tag:alice@example.com,2026:>
269
+ [my] <tag:alice.smith@example.org,2026:>
270
+ [j] <my:journal/>
271
+
272
+ # 2026-05-06 {=j:2026-05-06 .j:Entry j:date ^^xsd:date}
273
+
274
+ ## A good walk {label}
275
+
276
+ Mood: [happy] {j:mood}
277
+ Energy: [8] {j:energy ^^xsd:integer}
155
278
 
156
- [Walnuts](tag:alice@example.com,2026:walnut) {?ingredient}
279
+ Met [Bob] {+my:bob ?j:met} at [Central Park] {+my:central-park ?j:location}.
280
+ The weather was [sunny] {j:weather}.
157
281
  ```
158
282
 
159
- or
283
+ Generated triples:
284
+
285
+ ```ttl
286
+ j:2026-05-06 a j:Entry;
287
+ j:date "2026-05-06"^^xsd:date;
288
+ rdfs:label "A good walk";
289
+ j:mood "happy";
290
+ j:energy "8"^^xsd:integer;
291
+ j:met my:bob;
292
+ j:location my:central-park;
293
+ j:weather "sunny".
294
+ ```
295
+
296
+ `my:bob` and `my:central-park` are referenced by IRI. Their type and label belong in their own definitions — in a people file, a places file, or wherever you keep them. A journal entry only records what happened, not who Bob is.
297
+
298
+ ---
299
+
300
+ ## 8. Core Ontologies — Vocabulary You Can Reuse
301
+
302
+ You don't have to invent every predicate. Five vocabularies are built into MD-LD and cover most needs. Here is what each one actually contributes.
303
+
304
+ ### rdf — The Bedrock
305
+
306
+ `rdf` provides the primitives everything else is built on.
307
+
308
+ **`rdf:type`** — written as `.Class` in MD-LD — declares what kind of thing a node is. It is the most-used annotation in every graph:
160
309
 
161
310
  ```md
162
- [Walnuts] {+alice:walnut ?ingredient}
311
+ ## Alice {=my:alice .prov:Person}
312
+ ## Report {=my:report .prov:Entity}
313
+ ## Run {=my:run .prov:Activity}
163
314
  ```
164
315
 
165
- Same graph. Different ergonomics.
316
+ **`rdf:Property`** — the class of all properties. When you define your own predicate in a vocabulary, type it `.rdf:Property`.
166
317
 
167
- ---
318
+ **`rdf:Statement`** with `rdf:subject`, `rdf:predicate`, `rdf:object` — reification. Lets you make a node *about* a triple, so you can attach metadata (confidence, source, timestamp) to a relationship itself. See §9.
319
+
320
+ **`rdf:Bag` / `rdf:Seq` / `rdf:Alt`** — typed containers. `Bag` is unordered, `Seq` is ordered, `Alt` is a set of alternatives. Use them when the container type carries meaning. For a simple untyped collection, `rdfs:Container` is enough.
168
321
 
169
- ## 6. Lists = pure Markdown structure, explicit annotations only
322
+ **`rdf:List`** with `rdf:first` / `rdf:rest` / `rdf:nil` — a linked-list structure required by SHACL's `sh:in` (enumeration) and `sh:and` (logical combination). You rarely author these by hand outside of SHACL shapes.
170
323
 
171
- Lists have **no semantic scope**. Each item must have explicit annotations.
324
+ **`rdf:value`** — an idiomatic property for the "main value" of a structured node, used in qualified PROV-O patterns and compound literals.
325
+
326
+ ### rdfs — Schema and Display
327
+
328
+ `rdfs` gives you the vocabulary for naming, describing, and organising your data.
329
+
330
+ **`rdfs:label`** (written as bare `label`) — the display name of any node. Every named node should have one:
172
331
 
173
332
  ```md
174
- [alice] <tag:alice@example.com,2026:>
333
+ ## Alice {=my:alice label}
334
+ ## Central Park {=my:place/central-park label}
335
+ ```
175
336
 
176
- Ingredients: {=alice:recipe .Container}
337
+ **`rdfs:comment`** (written as bare `comment`) — a human-readable description of a node, typically used in vocabulary definitions:
177
338
 
178
- - Walnuts {+alice:walnut ?member .alice:Ingredient name}
179
- - Flour {+alice:flour ?member .alice:Ingredient name}
180
- - Water {+alice:water ?member .alice:Ingredient name}
339
+ ```md
340
+ > A person who attended the event. {comment @en}
181
341
  ```
182
342
 
183
- Result: clean, explicit graph. No implicit semantics.
343
+ **`rdfs:Class`** (written as `.Class`) — declares that a node *is itself a class*, i.e. a category other nodes can belong to. Different from `.SomeClass` which says a node *is an instance of* SomeClass:
344
+
345
+ ```md
346
+ ## Person {=my:Person .Class label}
347
+ ## Location {=my:Location .Class label}
348
+ ```
184
349
 
185
- ### List Item Requirements
350
+ **`rdfs:subClassOf`** — builds class hierarchies. `prov:Person rdfs:subClassOf prov:Agent` means every Person is also an Agent:
186
351
 
187
- **✅ DO - Items with explicit subjects emit semantics:**
188
352
  ```md
189
- - **Flour** {=alice:flour} # Clean subject
190
- - **Walnuts** {=alice:walnuts} # Clean subject
353
+ ## Employee {=my:Employee .Class label}
354
+ [Person] {+my:Person ?subClassOf}
191
355
  ```
192
356
 
357
+ **`rdfs:subPropertyOf`** — builds property hierarchies. Used in vocabulary authoring.
193
358
 
194
- **Critical Rule**: **All list items must have explicit subject (`{=iri}` or `{+iri}`) to emit semantics.**
359
+ **`rdfs:domain` / `rdfs:range`** — document what class a property applies to and what type its values should be. Used in vocabulary authoring, not in instance data.
195
360
 
196
- **Valid Alternatives for Additional Information:**
361
+ **`rdfs:Container` / `rdfs:member`** — an open-ended collection. Any node typed `.Container` is a bag; `?member` adds items to it:
197
362
 
198
- **✅ Nested Lists (Pure Structure)**
199
363
  ```md
200
- - **Flour** {=alice:flour}
201
- Properties:
202
- - **Organic** {+alice:organic ?alice:hasProperty .alice:Property label}
364
+ ## Places I've been {=my:places .Container label}
365
+
366
+ - Central Park {+my:place/central-park ?member}
367
+ - Tompkins Square {+my:place/tompkins ?member}
203
368
  ```
204
369
 
205
- **✅ Separate Sections**
370
+ The reverse form — an item declaring which container it belongs to — uses `!member`:
371
+
206
372
  ```md
207
- - **Flour** {=alice:flour}
373
+ ## Central Park {=my:place/central-park .prov:Location label}
208
374
 
209
- ## Flour Description {=alice:flour}
210
- [*Important*] {priority .Important}
375
+ In collection: [places] {+my:places !member}
211
376
  ```
212
377
 
213
- **Why?** Lists are **pure Markdown structure**. This keeps them predictable and streaming-safe.
378
+ **`rdfs:seeAlso` / `rdfs:isDefinedBy`** — link a node to related or defining resources. `isDefinedBy` is a sub-property of `seeAlso` and points to the authoritative specification.
214
379
 
215
- ---
380
+ ### prov — Who Did What When
216
381
 
217
- ## 7. Fragments = structured documents
382
+ PROV-O models the three building blocks of provenance: **entities** (things), **activities** (events that happen over time), and **agents** (people, software, organisations that bear responsibility).
218
383
 
219
- Fragments turn sections into addressable nodes.
384
+ The three core classes:
220
385
 
221
386
  ```md
222
- [alice] <tag:alice@example.com,2026:>
387
+ ## Report {=my:report .prov:Entity label}
388
+ ## Analysis run {=my:run .prov:Activity label}
389
+ ## Alice {=my:alice .prov:Person label} ← prov:Person is a subclass of prov:Agent
390
+ ```
223
391
 
224
- ## Instructions {=#steps .HowTo}
392
+ The starting-point properties connect them:
225
393
 
226
- ### Mixing {=#step-1 .HowToStep rdfs:label}
394
+ ```md
395
+ ## Analysis run {=my:run .prov:Activity label}
227
396
 
228
- > Mix ingredients {text}
397
+ Started: [2026-05-06T09:00:00Z] {prov:startedAtTime ^^xsd:dateTime}
398
+ Ended: [2026-05-06T09:45:00Z] {prov:endedAtTime ^^xsd:dateTime}
399
+ By: [Alice] {+my:alice ?prov:wasAssociatedWith}
400
+ Used: [dataset] {+my:dataset ?prov:used}
401
+ Made: [report] {+my:report ?prov:generated}
402
+ ```
229
403
 
230
- ### Baking {=#step-2 .HowToStep rdfs:label}
404
+ Entity-to-entity chains use `prov:wasDerivedFrom` (when the activity is unknown or irrelevant) and `prov:wasAttributedTo` (which agent is responsible for an entity):
231
405
 
232
- > Bake for 45 minutes {text}
406
+ ```md
407
+ ## Bar chart {=my:chart .prov:Entity label}
408
+
409
+ Derived from [regional stats] {+my:stats ?prov:wasDerivedFrom}.
410
+ Attributed to [Alice] {+my:alice ?prov:wasAttributedTo}.
233
411
  ```
234
412
 
235
- Emits:
413
+ `prov:actedOnBehalfOf` records delegation — a software agent acting on behalf of a person:
236
414
 
237
- ```turtle
238
- tag:alice@example.com,2026:walnut-bread#steps a schema:HowTo .
239
- tag:alice@example.com,2026:walnut-bread#step-1 a schema:HowToStep ; rdfs:label "Mixing" ; schema:text "Mix ingredients" .
240
- tag:alice@example.com,2026:walnut-bread#step-2 a schema:HowToStep ; rdfs:label "Baking" ; schema:text "Bake for 45 minutes" .
415
+ ```md
416
+ ## Bot {=my:bot .prov:SoftwareAgent label}
417
+ [Alice] {+my:alice ?prov:actedOnBehalfOf}
241
418
  ```
242
419
 
243
- Fragments always attach to the **current subject base**.
420
+ `prov:wasInformedBy` connects two activities without specifying the intermediate entity:
244
421
 
245
- ---
422
+ ```md
423
+ ## Illustration {=my:illustrate .prov:Activity label}
424
+ [aggregation run] {+my:aggregate ?prov:wasInformedBy}
425
+ ```
426
+
427
+ All of these have *qualified* forms (via `prov:qualifiedGeneration`, `prov:qualifiedUsage`, `prov:qualifiedAssociation`, etc.) that let you attach additional metadata to a relationship using an intermediate node. The pattern is: state the simple link, then define the qualification node separately.
246
428
 
247
- ## 8. Blockquotes = descriptions, abstracts, notes
429
+ ### xsd — Typed Literals
430
+
431
+ `xsd` datatypes give literals machine-readable types. Without a datatype, everything is a plain string.
248
432
 
249
433
  ```md
250
- > A dense, rustic bread with toasted walnuts. {description}
434
+ [2026-05-06] {my:date ^^xsd:date}
435
+ [2026-05-06T09:00:00Z] {my:timestamp ^^xsd:dateTime}
436
+ [42] {my:count ^^xsd:integer}
437
+ [3.14] {my:ratio ^^xsd:decimal}
438
+ [true] {my:active ^^xsd:boolean}
439
+ [P1Y6M] {my:duration ^^xsd:duration}
440
+ ```
441
+
442
+ ### sh — Validation Shapes (SHACL)
443
+
444
+ SHACL lets you declare what valid data looks like. The full pattern is: one `sh:NodeShape` declares all its `sh:property` links upfront, then each `sh:PropertyShape` is defined in its own section:
445
+
446
+ ```md
447
+ [my] <tag:you@example.com,2026:>
448
+
449
+ ## Person Shape {=my:PersonShape .sh:NodeShape label}
450
+
451
+ Validates all [Person] {+my:Person ?sh:targetClass} nodes with exactly one [name] {+my:PersonShape-name ?sh:property sh:name} and at least one [email] {+my:PersonShape-email ?sh:property sh:name}.
452
+
453
+ ### Name rule {=my:PersonShape-name .sh:PropertyShape}
454
+
455
+ Path: [label] {+label ?sh:path}
456
+ Required: [1] {sh:minCount sh:maxCount ^^xsd:integer}
457
+
458
+ > Every person must have exactly one name. {sh:message}
459
+
460
+ ### Email rule {=my:PersonShape-email .sh:PropertyShape}
461
+
462
+ Path: [my:email] {+my:email ?sh:path}
463
+ Required: [1] {sh:minCount ^^xsd:integer}
464
+
465
+ > Every person must have an email address. {sh:message}
251
466
  ```
252
467
 
253
- Readable prose → structured data.
468
+ Targeting options: `?sh:targetClass` (all instances of a class), `?sh:targetNode` (one specific node), `?sh:targetSubjectsOf` (nodes that use a given predicate), `?sh:targetObjectsOf` (nodes that are objects of a given predicate).
469
+
470
+ Common constraint predicates: `sh:minCount`, `sh:maxCount`, `sh:datatype`, `sh:nodeKind`, `sh:minInclusive`, `sh:maxInclusive`, `sh:minLength`, `sh:maxLength`, `sh:pattern`, `sh:hasValue`, `sh:in`, `sh:node`, `sh:not`, `sh:message`, `sh:severity`.
254
471
 
255
472
  ---
256
473
 
257
- ## 9. Code blocks are first-class values
474
+ ## 9. Tracking Statements — rdf:Statement
475
+
476
+ When you need to annotate a *relationship* itself (e.g. record confidence, source, or time of a claim), use `rdf:Statement`:
477
+
478
+ ```md
479
+ [my] <tag:alice.smith@example.org,2026:>
258
480
 
259
- ````md
260
- [alice] <tag:alice@example.com,2026:>
481
+ ## Observation 1 {=my:obs1 .rdf:Statement .prov:Entity label}
261
482
 
262
- ```txt {=alice:walnut-bread#formula .Recipe text}
263
- 500g flour
264
- 300ml water
483
+ I observed that [Alice] {+my:alice ?rdf:subject} [knows] {+my:knows ?rdf:predicate} [Bob] {+my:bob ?rdf:object}.
484
+
485
+ Confidence: [0.95] {my:confidence ^^xsd:decimal}
486
+
487
+ Source: [field notes] {+my:field-notes ?prov:wasDerivedFrom label}
265
488
  ```
266
- ````
267
489
 
268
- Code content becomes a literal.
269
- Language fences stay intact.
490
+ MD-LD automatically extracts the elevated SPO triple (`my:alice my:knows my:bob`) from this pattern alongside the reified statement node.
270
491
 
271
492
  ---
272
493
 
273
- ## 10. Reverse relations (write from either side)
494
+ ## 10. Subject Decoupling — The TTL Way
495
+
496
+ Subject context persists until the next `{=...}`. The elegant way to handle multiple related nodes is to declare all of a node's *outgoing links* together — just like Turtle does — then move to each child in its own section:
274
497
 
275
498
  ```md
276
- [alice] <tag:alice@example.com,2026:>
499
+ [my] <tag:alice.smith@example.org,2026:>
277
500
 
278
- Used in: {!hasIngredient}
501
+ # Person Shape {=my:PersonShape .sh:NodeShape label}
279
502
 
280
- - Salad {=alice:salad}
281
- ````
503
+ Validates [Person] {+my:Person ?sh:targetClass} with rules:
504
+ [name] {+my:PersonShape-name ?sh:property sh:name} and
505
+ [email] {+my:PersonShape-email ?sh:property sh:name}.
282
506
 
283
- Same graph. Different narrative flow.
507
+ ## Name rule {=my:PersonShape-name .sh:PropertyShape}
508
+
509
+ Path: [label] {+label ?sh:path}
510
+ Required: [1] {sh:minCount ^^xsd:integer}
511
+
512
+ > Every person must have a name. {sh:message}
513
+
514
+ ## Email rule {=my:PersonShape-email .sh:PropertyShape}
515
+
516
+ Path: [my:email] {+my:email ?sh:path}
517
+ Required: [1] {sh:minCount ^^xsd:integer}
518
+
519
+ > Every person must have an email. {sh:message}
520
+ ```
521
+
522
+ The parent shape lists all its `?sh:property` links in one paragraph. Each child `sh:PropertyShape` then gets its own heading section. No resets needed — the `sh:name` value carrier on the `{+...}` block even gives each rule a human-readable name at the point of reference.
523
+
524
+ The `{=my:Shape}` reset is available when you genuinely need to add properties to a parent *after* defining children inline, but the cleaner default is: **finish a node before moving on**.
525
+
526
+ ### ❌ Antipattern — typing objects inline
527
+
528
+ Avoid adding `.Class` and `label` directly onto `{+IRI}` references unless that is the *only* place the node ever appears:
529
+
530
+ ```md
531
+ ← antipattern: Bob gets typed and labelled here, and again wherever else he appears
532
+ Met [Bob] {+my:bob .prov:Person ?j:met label}.
533
+ ```
534
+
535
+ This scatters type and label triples across every document that mentions Bob. If graphs are merged, you get duplicate assertions. Instead, define Bob once:
536
+
537
+ ```md
538
+ ← correct: the journal just records the link
539
+ Met [Bob] {+my:bob ?j:met}.
540
+
541
+ ← Bob's definition lives in one place (people.md or similar)
542
+ ## Bob {=my:bob .prov:Person label}
543
+ ```
544
+
545
+ The one exception: when you are authoring a *vocabulary* or *ontology*, where introducing a term and its type in the same annotation is exactly right — as seen in the PROV-O example above.
284
546
 
285
547
  ---
286
548
 
287
- ## 11. What MD-LD never does
549
+ ## 11. Polarity — Append-Only Editing and Retractions
550
+
551
+ Every predicate, type, and reverse link in MD-LD can be prefixed with `-` to retract it. This turns MD-LD into an append-only semantic ledger: you never delete text from a file, you write a new entry that cancels a previous assertion.
552
+
553
+ ### Intra-document cancellation
554
+
555
+ When a retraction matches a positive triple *in the same document*, both cancel out — neither appears in the final graph:
556
+
557
+ ```md
558
+ [my] <tag:you@example.com,2026:>
559
+
560
+ ## Article {=my:article}
561
+
562
+ [Alice] {my:author} ← add
563
+ [Alice] {-my:author} ← cancel — both disappear
564
+ [Bob] {my:author} ← this survives
565
+ ```
566
+
567
+ Result: only `my:article my:author "Bob"` in `quads`. Nothing in `remove`.
568
+
569
+ ### External retraction
570
+
571
+ When a retraction finds no matching positive in the current document, it becomes an *external retraction* — stored in `remove` rather than `quads`. It waits to cancel a triple from a previously merged document:
572
+
573
+ ```md
574
+ [my] <tag:you@example.com,2026:>
575
+
576
+ ## Article {=my:article}
577
+
578
+ [Alice] {-my:author} ← external retract: targets a prior document
579
+ [Bob] {my:author}
580
+ ```
581
+
582
+ Result: `my:article my:author "Bob"` in `quads`. `my:article my:author "Alice"` in `remove`.
583
+
584
+ ### Merge resolution
585
+
586
+ The `merge()` function resolves external retractions against earlier documents. This is how you implement versioning:
587
+
588
+ ```md
589
+ v1.md → [Alice] {my:author} [Draft] {my:status}
590
+ v2.md → [Alice] {-my:author} [Bob] {my:author} [Draft] {-my:status} [Published] {my:status}
591
+ ```
592
+
593
+ ```javascript
594
+ const final = merge([v1, v2]);
595
+ // quads: author=Bob, status=Published
596
+ // remove: [] — all retractions resolved
597
+ ```
598
+
599
+ The invariant always holds: **`quads ∩ remove = ∅`** — a triple is never simultaneously present and retracted.
600
+
601
+ ### Type and link retractions
602
+
603
+ The `-` prefix works on all annotation forms:
604
+
605
+ ```md
606
+ ## Alice {=my:alice .ex:Employee -.ex:Contractor} ← add Employee, retract Contractor in same block
607
+
608
+ [project-x] {+my:project-x -?my:assignedTo} ← retract an object link
609
+ [my:team] {+my:team -!my:hasMember} ← retract a reverse link
610
+ ```
611
+
612
+ ### The ledger pattern
613
+
614
+ The real power is in append-only files — a journal, a log, a knowledge base — where every change is a new entry:
615
+
616
+ ```md
617
+ [my] <tag:you@example.com,2026:>
618
+ [j] <my:journal/>
619
+
620
+ # 2026-05-01 — started project {=j:2026-05-01 .j:Entry j:date ^^xsd:date}
621
+
622
+ Project status: [planning] {+my:project ?my:documents ?j:status}
623
+
624
+ # 2026-05-10 — project kicked off {=j:2026-05-10 .j:Entry j:date ^^xsd:date}
288
625
 
289
- * ❌ No implicit meaning
290
- * ❌ No blank nodes
291
- * ❌ No inferred subjects
292
- * ❌ No structural guessing
293
- * ❌ No multi-pass parsing
294
- * ❌ **No semantic list propagation**
626
+ {=my:project}
627
+ [planning] {-my:status}
628
+ [active] {my:status}
629
+ ```
295
630
 
296
- Every triple is **authored**, not derived.
631
+ Merging these two entries produces `my:project my:status "active"` only. The history of the change lives in the text; the graph holds only the current truth.
297
632
 
298
633
  ---
299
634
 
300
- ## 12. Why this scales (humans + agents)
635
+ ## 12. Quick Reference
636
+
637
+ ```
638
+ PREFIXES
639
+ [prefix] <IRI> declare a namespace
640
+ [p2] <p1:sub/> fold prefix p2 under p1 (slash for path segments)
641
+
642
+ SUBJECTS
643
+ {=my:node} set subject to full IRI
644
+ {=#fragment} set subject to current-base#fragment
645
+ {=} clear subject
646
+
647
+ OBJECTS
648
+ {+my:node ?predicate} forward link: subject → object
649
+ {+my:node !predicate} reverse link: object → subject
650
+ {+#fragment ?predicate} same with fragment IRI
651
+
652
+ TYPES
653
+ {.my:Class} subject rdf:type my:Class
654
+
655
+ LITERALS (value comes from the carrier)
656
+ [text] {predicate} literal property
657
+ [text] {predicate @en} with language tag
658
+ [text] {predicate ^^xsd:integer} with datatype
659
+
660
+ CARRIERS
661
+ [text] **text** `text` inline spans
662
+ # text - text > text block-level (heading / list / blockquote)
663
+ ```fenced``` code block
664
+
665
+ PREDICATE FORMS
666
+ p S → literal [Alice] {my:name}
667
+ ?p S → object [Bob] {+my:bob ?my:knows}
668
+ !p object → S [Tag] {+my:tag !my:taggedIn}
669
+
670
+ POLARITY (prefix any predicate or type with -)
671
+ -p retract literal [Alice] {-my:name}
672
+ -?p retract object link [Bob] {+my:bob -?my:knows}
673
+ -!p retract reverse link [Tag] {+my:tag -!my:taggedIn}
674
+ -.Class retract type {-.my:Draft}
675
+
676
+ COMBINING (all valid in one block)
677
+ {=my:node .my:Class label}
678
+ {+my:target ?my:rel sh:name}
679
+ {=my:doc -.ex:Draft .ex:Published -my:version}
680
+ ```
301
681
 
302
- Because MD-LD is:
682
+ ---
303
683
 
304
- * **Streaming-parseable**
305
- * **Round-trip safe**
306
- * **Text-preserving**
307
- * **SPARQL-addressable**
684
+ ## 13. Invariants — What Must Always Hold
308
685
 
309
- Agents can:
686
+ These rules are non-negotiable. Violating them produces invalid or empty graph output:
310
687
 
311
- * align facts via SPARQL
312
- * add/remove triples
313
- * serialize changes back into Markdown
314
- without breaking prose, layout, or intent.
688
+ - Every triple must come from an annotation `{...}`
689
+ - Every literal must come from a value *carrier* — never write `{predicate "value"}`
690
+ - `{=...}` always declares the subject; it never emits a triple by itself
691
+ - No blank nodes — every node must be a named IRI
692
+ - Do not invent prefixes; declare everything you use
693
+ - `label` without a prefix means `rdfs:label` — use it freely
694
+ - List item annotations apply only to *that* item, not the header or siblings
695
+ - Define nodes once — type and label belong in a node's own section, not scattered across every reference to it
315
696
 
316
- Your document becomes a **shared semantic surface**, not a data export.
697
+ **Invalid:**
698
+ ```md
699
+ {my:age "34"^^xsd:integer} ← literal inside braces, no carrier
700
+ ```
701
+
702
+ **Valid:**
703
+ ```md
704
+ [34] {my:age ^^xsd:integer} ← carrier [34] holds the value
705
+ ```
317
706
 
318
707
  ---
319
708
 
320
- ## One sentence summary
709
+ ## 14. Worked Patterns
710
+
711
+ ### Personal journal entry
712
+ ```md
713
+ [my] <tag:you@example.com,2026:>
714
+ [j] <my:journal/>
715
+
716
+ # 2026-05-06 {=j:2026-05-06 .j:Entry j:date ^^xsd:date label}
717
+
718
+ [Productive] {j:mood}. Met [Sam] {+my:sam ?j:met} at [the library] {+my:place/library ?j:location}.
719
+ ```
720
+
721
+ ### Project with tasks
722
+ ```md
723
+ [my] <tag:you@example.com,2026:>
724
+
725
+ # Project Alpha {=my:alpha .my:Project label}
726
+
727
+ Tasks: [design] {+#design ?my:task sh:name}, [build] {+#build ?my:task sh:name}.
728
+
729
+ ## Design {=#design .my:Task label}
730
+ [done] {my:status}
731
+
732
+ ## Build {=#build .my:Task label}
733
+ [in-progress] {my:status}
734
+ ```
735
+
736
+ ### Provenance activity
737
+ ```md
738
+ [my] <tag:you@example.com,2026:>
739
+
740
+ ## Analysis run {=my:run-1 .prov:Activity label}
741
+
742
+ Started: [2026-05-06T09:00:00Z] {prov:startedAtTime ^^xsd:dateTime}
743
+ Ended: [2026-05-06T09:45:00Z] {prov:endedAtTime ^^xsd:dateTime}
744
+ By: [Alice] {+my:alice ?prov:wasAssociatedWith}
745
+ Used: [dataset v2] {+my:dataset-v2 ?prov:used}
746
+ Made: [report] {+my:report ?prov:generated}
747
+ ```
748
+
749
+ ### SHACL validation shape
750
+ ```md
751
+ [my] <tag:you@example.com,2026:>
321
752
 
322
- > **MD-LD is RDF you can read, write, diff, query, and share—without ever leaving Markdown.**
753
+ ## User Shape {=my:UserShape .sh:NodeShape label}
754
+
755
+ Validates all [User] {+my:User ?sh:targetClass} with:
756
+ [email rule] {+my:UserShape-email ?sh:property sh:name} and
757
+ [name rule] {+my:UserShape-name ?sh:property sh:name}.
758
+
759
+ ### Email rule {=my:UserShape-email .sh:PropertyShape}
760
+
761
+ Path: [my:email] {+my:email ?sh:path}
762
+ Required: [1] {sh:minCount ^^xsd:integer}
763
+
764
+ > User must have an email address. {sh:message}
765
+
766
+ ### Name rule {=my:UserShape-name .sh:PropertyShape}
767
+
768
+ Path: [label] {+label ?sh:path}
769
+ Required: [1] {sh:minCount ^^xsd:integer}
770
+
771
+ > User must have a name. {sh:message}
772
+ ```
773
+
774
+ ### Reified statement with confidence
775
+ ```md
776
+ [my] <tag:you@example.com,2026:>
777
+
778
+ ## Claim {=my:claim-1 .rdf:Statement label}
779
+
780
+ [Alice] {+my:alice ?rdf:subject} [knows] {+my:knows ?rdf:predicate} [Bob] {+my:bob ?rdf:object}.
781
+ Confidence: [0.9] {my:confidence ^^xsd:decimal}
782
+ Recorded: [2026-05-06] {prov:generatedAtTime ^^xsd:date}
783
+ ```
784
+
785
+ ### People and places — define once, reference everywhere
786
+ ```md
787
+ [my] <tag:you@example.com,2026:>
788
+
789
+ # People
790
+
791
+ ## Alice {=my:alice .prov:Person label}
792
+ [alice@example.com] {my:email}
793
+
794
+ ## Bob {=my:bob .prov:Person label}
795
+
796
+ # Places
797
+
798
+ ## Central Park {=my:place/central-park .prov:Location label}
799
+ [New York] {my:city}
800
+ ```
801
+
802
+ ### Versioned knowledge — append-only ledger
803
+ ```md
804
+ [my] <tag:you@example.com,2026:>
805
+ [j] <my:journal/>
806
+
807
+ # 2026-05-01 {=j:2026-05-01 .j:Entry j:date ^^xsd:date label}
808
+
809
+ Project Alpha kicked off: [planning] {+my:alpha ?my:status}
810
+
811
+ # 2026-05-10 {=j:2026-05-10 .j:Entry j:date ^^xsd:date label}
812
+
813
+ {=my:alpha}
814
+ [planning] {-my:status}
815
+ [active] {my:status}
816
+ ```