mdld-parse 0.9.9 → 1.0.0

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.
Files changed (55) hide show
  1. package/README.md +242 -330
  2. package/dist/index.js +1793 -1336
  3. package/package.json +4 -4
  4. package/dist/.nojekyll +0 -0
  5. package/dist/CNAME +0 -1
  6. package/dist/README.md +0 -500
  7. package/dist/docs/API.md +0 -435
  8. package/dist/docs/Architecture.md +0 -190
  9. package/dist/docs/Guide.md +0 -816
  10. package/dist/docs/LLM-MDLD-Inducer.md +0 -550
  11. package/dist/docs/LiterateRDF.md +0 -472
  12. package/dist/docs/Parser.md +0 -720
  13. package/dist/docs/Performance.md +0 -238
  14. package/dist/docs/Spec-render.md +0 -1439
  15. package/dist/docs/Subject.md +0 -180
  16. package/dist/docs/Syntax.md +0 -463
  17. package/dist/docs/TodoList.md +0 -215
  18. package/dist/docs/Use-Cases.md +0 -354
  19. package/dist/docs/guide-m.md +0 -56
  20. package/dist/docs/index.html +0 -108
  21. package/dist/docs/index.md +0 -56
  22. package/dist/docs/one-page.md +0 -322
  23. package/dist/docs/origin.md +0 -460
  24. package/dist/docs/polarity.md +0 -586
  25. package/dist/docs/primary-subject.md +0 -326
  26. package/dist/docs/statements.md +0 -226
  27. package/dist/docs/tokenization-performance-report.md +0 -164
  28. package/dist/examples/Cookbook.md +0 -32
  29. package/dist/examples/Status-SHACL.md +0 -31
  30. package/dist/examples/demo/index.md +0 -35
  31. package/dist/examples/demo/journal.md +0 -58
  32. package/dist/examples/demo/minimal.md +0 -23
  33. package/dist/examples/demo/project.md +0 -84
  34. package/dist/examples/demo/prov.md +0 -107
  35. package/dist/examples/demo/rdf.md +0 -69
  36. package/dist/examples/demo/recipe.md +0 -50
  37. package/dist/examples/demo/research.md +0 -84
  38. package/dist/examples/demo/shacl.md +0 -161
  39. package/dist/examples/demo/space-mission.md +0 -58
  40. package/dist/examples/demo/tasks.md +0 -175
  41. package/dist/examples/demo/xsd.md +0 -91
  42. package/dist/examples/dogfood.md +0 -288
  43. package/dist/examples/few-shot.md +0 -309
  44. package/dist/examples/graph/rdf-graph.html +0 -473
  45. package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
  46. package/dist/examples/index.md +0 -45
  47. package/dist/examples/llm-time-workflow.md +0 -173
  48. package/dist/examples/statements.md +0 -43
  49. package/dist/examples/workflow.md +0 -150
  50. package/dist/index.html +0 -3049
  51. package/dist/logo.svg +0 -7
  52. package/dist/spec/Spec-compact.md +0 -368
  53. package/dist/spec/Spec-ultra.md +0 -232
  54. package/dist/spec/Spec.md +0 -1116
  55. package/dist/spec/index.md +0 -46
@@ -1,816 +0,0 @@
1
- # MD-LD Authoring Guide
2
-
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
-
5
- Think of it like highlighters. You pick a color scheme first (prefix declarations), then highlight the parts of your text that carry meaning.
6
-
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
- ```
46
-
47
- ---
48
-
49
- ## 2. Your Personal IRI — the `tag:` Pattern
50
-
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:
52
-
53
- ```
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:>
64
- ```
65
-
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` |
73
-
74
- You can also add a sub-prefix for a specific domain of your notes:
75
-
76
- ```md
77
- [my] <tag:alice.smith@example.org,2026:>
78
- [j] <my:journal/>
79
- ```
80
-
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
- ```
92
-
93
- ---
94
-
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
- ```
102
-
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.
104
-
105
- ```md
106
- [my] <tag:alice.smith@example.org,2026:>
107
-
108
- ## Alice {=my:alice .prov:Person label}
109
-
110
- Age: [34] {my:age ^^xsd:integer}
111
- City: [Berlin] {my:city @de}
112
- Bio: **Loves hiking and graph databases.** {my:bio @en}
113
- ```
114
-
115
- Generates:
116
-
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.
123
- ```
124
-
125
- **Carriers at a glance:**
126
-
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
- ```
146
-
147
- ---
148
-
149
- ## 4. Connecting Things — Object Properties
150
-
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).
158
-
159
- ```md
160
- [my] <tag:alice.smith@example.org,2026:>
161
-
162
- ## Alice {=my:alice .prov:Person label}
163
-
164
- Alice knows [Bob] {+my:bob ?my:knows}.
165
- She lives near [Central Park] {+my:central-park ?my:livesNear}.
166
-
167
- ## Bob {=my:bob .prov:Person label}
168
-
169
- ## Central Park {=my:central-park .prov:Location label}
170
- ```
171
-
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
- ```
184
-
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.
186
-
187
- ### Reverse Links — `!predicate`
188
-
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:
190
-
191
- ```md
192
- ## Cookbook {=my:cookbook .my:Collection label}
193
-
194
- Recipes in this collection:
195
-
196
- - Apple Pie {+my:apple-pie !my:partOf}
197
- - Peach Pie {+my:peach-pie !my:partOf}
198
-
199
- ## Apple Pie {=my:apple-pie .my:Recipe label}
200
-
201
- ## Peach Pie {=my:peach-pie .my:Recipe label}
202
- ```
203
-
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.
205
-
206
- ---
207
-
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}
216
-
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}
220
-
221
- ## Design Task {=#task-design}
222
-
223
- Status: [done] {my:status}
224
-
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:
233
-
234
- ```md
235
- {=my:ProjectAlpha}
236
-
237
- [3] {my:taskCount ^^xsd:integer}
238
- ```
239
-
240
- Use `{=}` (bare) to clear the subject entirely — subsequent annotations will have no subject until the next `{=...}`.
241
-
242
- ---
243
-
244
- ## 6. The Three Predicate Forms
245
-
246
- Every annotation uses one of three forms:
247
-
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:
255
-
256
- ```md
257
- ## Alice {=my:alice .prov:Person label}
258
- ```
259
-
260
- This sets subject, types it, and assigns a label — all at once. Order within `{...}` is flexible.
261
-
262
- ---
263
-
264
- ## 7. A Journal Entry — Putting It Together
265
-
266
- Here's a complete personal journal note using everything above:
267
-
268
- ```md
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}
278
-
279
- Met [Bob] {+my:bob ?j:met} at [Central Park] {+my:central-park ?j:location}.
280
- The weather was [sunny] {j:weather}.
281
- ```
282
-
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:
309
-
310
- ```md
311
- ## Alice {=my:alice .prov:Person}
312
- ## Report {=my:report .prov:Entity}
313
- ## Run {=my:run .prov:Activity}
314
- ```
315
-
316
- **`rdf:Property`** — the class of all properties. When you define your own predicate in a vocabulary, type it `.rdf:Property`.
317
-
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.
321
-
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.
323
-
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:
331
-
332
- ```md
333
- ## Alice {=my:alice label}
334
- ## Central Park {=my:place/central-park label}
335
- ```
336
-
337
- **`rdfs:comment`** (written as bare `comment`) — a human-readable description of a node, typically used in vocabulary definitions:
338
-
339
- ```md
340
- > A person who attended the event. {comment @en}
341
- ```
342
-
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
- ```
349
-
350
- **`rdfs:subClassOf`** — builds class hierarchies. `prov:Person rdfs:subClassOf prov:Agent` means every Person is also an Agent:
351
-
352
- ```md
353
- ## Employee {=my:Employee .Class label}
354
- [Person] {+my:Person ?subClassOf}
355
- ```
356
-
357
- **`rdfs:subPropertyOf`** — builds property hierarchies. Used in vocabulary authoring.
358
-
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.
360
-
361
- **`rdfs:Container` / `rdfs:member`** — an open-ended collection. Any node typed `.Container` is a bag; `?member` adds items to it:
362
-
363
- ```md
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}
368
- ```
369
-
370
- The reverse form — an item declaring which container it belongs to — uses `!member`:
371
-
372
- ```md
373
- ## Central Park {=my:place/central-park .prov:Location label}
374
-
375
- In collection: [places] {+my:places !member}
376
- ```
377
-
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.
379
-
380
- ### prov — Who Did What When
381
-
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).
383
-
384
- The three core classes:
385
-
386
- ```md
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
- ```
391
-
392
- The starting-point properties connect them:
393
-
394
- ```md
395
- ## Analysis run {=my:run .prov:Activity label}
396
-
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
- ```
403
-
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):
405
-
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}.
411
- ```
412
-
413
- `prov:actedOnBehalfOf` records delegation — a software agent acting on behalf of a person:
414
-
415
- ```md
416
- ## Bot {=my:bot .prov:SoftwareAgent label}
417
- [Alice] {+my:alice ?prov:actedOnBehalfOf}
418
- ```
419
-
420
- `prov:wasInformedBy` connects two activities without specifying the intermediate entity:
421
-
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.
428
-
429
- ### xsd — Typed Literals
430
-
431
- `xsd` datatypes give literals machine-readable types. Without a datatype, everything is a plain string.
432
-
433
- ```md
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}
466
- ```
467
-
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`.
471
-
472
- ---
473
-
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:>
480
-
481
- ## Observation 1 {=my:obs1 .rdf:Statement .prov:Entity label}
482
-
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}
488
- ```
489
-
490
- MD-LD automatically extracts the elevated SPO triple (`my:alice my:knows my:bob`) from this pattern alongside the reified statement node.
491
-
492
- ---
493
-
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:
497
-
498
- ```md
499
- [my] <tag:alice.smith@example.org,2026:>
500
-
501
- # Person Shape {=my:PersonShape .sh:NodeShape label}
502
-
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}.
506
-
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.
546
-
547
- ---
548
-
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}
625
-
626
- {=my:project}
627
- [planning] {-my:status}
628
- [active] {my:status}
629
- ```
630
-
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.
632
-
633
- ---
634
-
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
- ```
681
-
682
- ---
683
-
684
- ## 13. Invariants — What Must Always Hold
685
-
686
- These rules are non-negotiable. Violating them produces invalid or empty graph output:
687
-
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
696
-
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
- ```
706
-
707
- ---
708
-
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:>
752
-
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
- ```