mdld-parse 0.9.2 → 0.9.3

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 (60) hide show
  1. package/dist/.nojekyll +0 -0
  2. package/dist/CNAME +1 -0
  3. package/dist/README.md +425 -0
  4. package/dist/docs/API.md +397 -0
  5. package/dist/docs/Architecture.md +190 -0
  6. package/dist/docs/Guide.md +322 -0
  7. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  8. package/dist/docs/Parser.md +654 -0
  9. package/dist/docs/Performance.md +238 -0
  10. package/dist/docs/Spec-render.md +1439 -0
  11. package/dist/docs/Subject.md +180 -0
  12. package/dist/docs/Syntax.md +463 -0
  13. package/dist/docs/TodoList.md +215 -0
  14. package/dist/docs/Use-Cases.md +354 -0
  15. package/dist/docs/index.html +108 -0
  16. package/dist/docs/index.md +56 -0
  17. package/dist/docs/origin.md +459 -0
  18. package/dist/docs/polarity.md +586 -0
  19. package/dist/docs/primary-subject.md +199 -0
  20. package/dist/docs/statements.md +226 -0
  21. package/dist/docs/tokenization-performance-report.md +164 -0
  22. package/dist/examples/Cookbook.md +32 -0
  23. package/dist/examples/Status-SHACL.md +33 -0
  24. package/dist/examples/demo/index.md +35 -0
  25. package/dist/examples/demo/journal.md +18 -0
  26. package/dist/examples/demo/minimal.md +11 -0
  27. package/dist/examples/demo/project.md +15 -0
  28. package/dist/examples/demo/recipe.md +31 -0
  29. package/dist/examples/demo/research.md +46 -0
  30. package/dist/examples/demo/space-mission.md +48 -0
  31. package/dist/examples/dogfood.md +288 -0
  32. package/dist/examples/few-shot.md +309 -0
  33. package/dist/examples/graph/rdf-graph.html +473 -0
  34. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  35. package/dist/examples/index.md +45 -0
  36. package/dist/examples/llm-time-workflow.md +173 -0
  37. package/dist/examples/prov-o.md +2367 -0
  38. package/dist/examples/rdf.md +827 -0
  39. package/dist/examples/shacl.md +3399 -0
  40. package/dist/examples/statements.md +43 -0
  41. package/dist/examples/workflow.md +150 -0
  42. package/dist/index.html +2827 -0
  43. package/dist/index.js +1548 -0
  44. package/dist/logo.svg +7 -0
  45. package/dist/spec/Spec-compact.md +363 -0
  46. package/dist/spec/Spec-ultra.md +221 -0
  47. package/dist/spec/Spec.md +1068 -0
  48. package/dist/spec/index.md +46 -0
  49. package/package.json +7 -8
  50. package/src/constants.js +0 -31
  51. package/src/generate.js +0 -245
  52. package/src/highlight.js +0 -362
  53. package/src/index.js +0 -13
  54. package/src/locate.js +0 -23
  55. package/src/merge.js +0 -157
  56. package/src/parse.js +0 -711
  57. package/src/render.js +0 -576
  58. package/src/shared.js +0 -577
  59. package/src/tokenizers.js +0 -594
  60. package/src/utils.js +0 -430
@@ -0,0 +1,1068 @@
1
+ # MD-LD — Core Specification
2
+
3
+ **Markdown-Linked Data**
4
+
5
+ A deterministic, streaming-friendly semantic annotation layer for CommonMark Markdown that emits RDF quads **only** from explicit `{...}` annotations.
6
+
7
+ ---
8
+
9
+ ## 1. What MD-LD Guarantees
10
+
11
+ MD-LD follows these strict rules to make it predictable and reliable:
12
+
13
+ 1. **Markdown stays valid** - If you remove all `{...}` blocks, you get perfectly normal Markdown
14
+ 2. **No hidden meanings** - MD-LD never guesses what you meant. Everything must be explicit. RDFS vocabulary is used by default.
15
+ 3. **Every fact comes from `{...}`** - All RDF data comes directly from your annotations
16
+ 4. **One-pass processing** - MD-LD can read your document from start to finish just once
17
+ 5. **No blank nodes** - Every entity has a proper identifier
18
+ 6. **No guessing games** - MD-LD doesn't infer or assume anything from structure
19
+ 7. **Traceable origins** - Every fact can be traced back to exactly where you wrote it
20
+
21
+ These rules make MD-LD **deterministic** - the same input always produces the same output.
22
+
23
+ ---
24
+
25
+ ## 2. How MD-LD Creates Data
26
+
27
+ MD-LD turns your annotations into **facts** about things. Think of it like creating sentences:
28
+
29
+ **Subject → Predicate → Object**
30
+
31
+ For example:
32
+ - "Apollo 11 → has name → "Apollo 11""
33
+ - "Apollo 11 → is a → Space Mission"
34
+ - "Apollo 11 → launched in → 1969"
35
+
36
+ ### The Building Blocks
37
+
38
+ MD-LD uses two types of things:
39
+
40
+ 1. **IRIs** - Unique identifiers for entities (like web addresses)
41
+ - `http://schema.org/Person` - the concept of "Person"
42
+ - `https://www.wikidata.org/entity/Q43653` - Apollo 11 mission
43
+ - `urn:isbn:0060831014` - A book global identifier
44
+ - `tag:alice@example.com,2026:doc` - A local tag
45
+
46
+ 2. **Literals** - Actual data values (text, numbers, dates)
47
+ - "Apollo 11" (text)
48
+ - 1969 (number)
49
+ - "1969"^^xsd:gYear (typed date)
50
+
51
+ ### The Rules
52
+
53
+ - **IRIs** can be subjects or objects - they can point to things or be pointed at
54
+ - **Literals** are always objects - they can only be pointed at (never subjects)
55
+ - Every fact connects exactly two things through a predicate
56
+
57
+ This creates a **graph** - a network of connected facts that computers can process.
58
+
59
+ ---
60
+
61
+ ## 3. What's Available When You Write `{...}`
62
+
63
+ When you add a `{...}` annotation, MD-LD knows about three things:
64
+
65
+ ### **S - The Current Subject** (What we're talking about)
66
+ - This is the main entity we're describing
67
+ - Set by `{=IRI}` or `{=#fragment}`
68
+ - Stays current until you change it or reset with `{=}`
69
+
70
+ **Example:**
71
+ ```md
72
+ [nasa] <https://nasa.gov/>
73
+ # Apollo 11 {=wd:Q43653 .nasa:Mission label} ← Sets S to Apollo 11
74
+ [1969] {nasa:launchYear} ← S is still Apollo 11
75
+ ```
76
+
77
+ ### **O - The Object Resource** (What we're linking to)
78
+ - Comes from links, images, or `{=IRI}`/`{+IRI}` inside the annotation
79
+ - Only available when you explicitly provide it
80
+
81
+ **Examples:**
82
+ ```md
83
+ [nasa] <https://nasa.gov>
84
+
85
+ # NASA {=nasa:orgranization .nasa:class:Organization label}
86
+
87
+ Is operating in **USA** {+nasa:usa ?nasa:countryOfOrigin}
88
+ <https://nasa.gov> {?seeAlso}
89
+ [NASA website](https://nasa.gov) {?website .Website label}
90
+ ![NASA Logo](https://nasa.gov/logo.png) {?logo .Image label}
91
+
92
+ ```
93
+
94
+ ### **L - The Literal Value** (The actual text)
95
+ - The text content of what you're annotating
96
+ - Can have datatypes (`^^xsd:gYear`) or languages (`@en`)
97
+
98
+ **Example:**
99
+ ```md
100
+ [Successful] {status} ← L = "Successful"
101
+ [1969] {launchYear ^^xsd:gYear} ← L = "1969"^^xsd:gYear
102
+ [July 20] {launchDate @en} ← L = "July 20"@en
103
+ ```
104
+
105
+ These three pieces let MD-LD create the right facts from your annotations.
106
+
107
+ ---
108
+
109
+ ## 4. What Can Carry Annotations
110
+
111
+ A `{...}` block can attach to exactly one **value carrier** - the piece of Markdown that provides the literal value.
112
+
113
+ ### Inline Elements (text-level)
114
+
115
+ | Markdown | What it captures | Example |
116
+ |----------|------------------|---------|
117
+ | `[text] {...}` | Link text | `[Apollo 11] {label}` |
118
+ | `*text* {...}` | Italic text | `*important* {emphasis}` |
119
+ | `_text_ {...}` | Italic text | `_important_ {emphasis}` |
120
+ | `**text** {...}` | Bold text | `**warning** {alert}` |
121
+ | `__text__ {...}` | Bold text | `__warning__ {alert}` |
122
+ | `` `text` {...}` | Code text | `` `console.log()` {code}`` |
123
+
124
+ ### Block Elements (structure-level)
125
+
126
+ | Markdown | What it captures | Example |
127
+ |----------|------------------|---------|
128
+ | `# Heading {...}` | Heading text | `# Apollo 11 {=ex:mission .Mission name}` |
129
+ | `- item {...}` | List item text | `- Neil Armstrong {=ex:person .Person name}` |
130
+ | `> quote {...}` | Quote text | `> "One small step" {comment}` |
131
+ | ````lang {...}`` | Code block content | ````js {=ex:code .ex:SoftwareSourceCode}` |
132
+ | `~~~lang {...}` | Tilde code block content | `~~~js {=ex:code ex:codecontent}` |
133
+
134
+ ### Links and Media (with URLs)
135
+
136
+ | Markdown | What it captures | Literal behavior | Type behavior |
137
+ |----------|------------------|------------------|---------------|
138
+ | `<URL> {...}` | The URL itself | No literals (ignored) | URL becomes subject |
139
+ | `[label](URL) {...}` | Label text + URL | Uses label as literal | URL becomes subject |
140
+ | `![alt](URL) {...}` | Alt text + URL | Uses alt as literal | URL becomes subject |
141
+
142
+ **Examples:**
143
+ - `<https://nasa.gov> {?website}` → current subject → website → URL
144
+ - `[NASA](https://nasa.gov) {label}` → URL → rdfs:label → "NASA"
145
+ - `[NASA](https://nasa.gov) {.schema:Organization}` → URL → rdf:type → schema:Organization
146
+ - `![Photo](photo.jpg) {caption}` → URL → caption → "Photo"
147
+
148
+ URLs when used as IRIs have `{+IRI}` **soft subject** behavior - properties in the annotation are applied to the URL, but current subject is not changed.
149
+
150
+ ### URL vs IRI Priority
151
+
152
+ When both a markdown link URL and an explicit IRI (`{=IRI}` or `{+IRI}`) are present in the same annotation, explicit IRIs take priority according to these rules:
153
+
154
+ **Priority Rules:**
155
+ 1. **Type declarations**: Explicit subject (`{=IRI}`) > Soft object (`{+IRI}`) > URL > Current subject
156
+ 2. **Literal predicates** (`p`): Explicit subject (`{=IRI}`) > Current subject, URL only when no explicit subject
157
+ 3. **Object predicates** (`?p`): Current subject → Explicit object (`{+IRI}`) or URL
158
+ 4. **Reverse predicates** (`!p`): Explicit object (`{+IRI}`) or URL → Current subject
159
+
160
+ **Examples:**
161
+ ```md
162
+ # Case 1: Explicit subject overrides URL
163
+ [Link](https://example.com) {=ex:subject .Type label}
164
+ # Results: ex:subject → rdf:type → Type, ex:subject → rdfs:label → "Link"
165
+
166
+ # Case 2: Soft object with URL present
167
+ [Link](https://example.com) {+ex:object ?predicate}
168
+ # Results: currentSubject → predicate → ex:object (URL ignored)
169
+
170
+ # Case 3: Mixed predicates
171
+ [Link](https://example.com) {=ex:subject label ?object}
172
+ # Results: ex:subject → label → "Link", currentSubject → object → ex:subject
173
+
174
+ # Case 4: No explicit subject (backward compatibility)
175
+ [Link](https://example.com) {.Type label}
176
+ # Results: URL → rdf:type → Type, URL → rdfs:label → "Link"
177
+ ```
178
+
179
+ **Key Principles:**
180
+ - Explicit IRIs (`{=IRI}`, `{+IRI}`) override URL-based subjects when present
181
+ - URLs become purely navigational when explicit IRIs are present
182
+ - Link text remains available as literal value for predicates
183
+ - Backward compatibility maintained for existing documents
184
+ - Round-trip safety through predictable priority rules
185
+
186
+ **Key Rules:**
187
+ - Type declarations use URL as subject (soft subject behavior) when no explicit IRI is present
188
+ - Object predicates use current subject as subject
189
+ - Reverse predicates use URL as subject
190
+ - Link text is treated as a value carrier for the literal value
191
+ - Images work the same way but use alt text for literals
192
+
193
+ **Example:**
194
+ ```md
195
+ [Berlin](https://en.wikipedia.org/wiki/Berlin) {.Place label ?mentions}
196
+ ```
197
+ Generates:
198
+ - `https://en.wikipedia.org/wiki/Berlin` → `rdf:type` → `Place`
199
+ - `https://en.wikipedia.org/wiki/Berlin` → `rdfs:label` → `"Berlin"`
200
+ - `currentSubject` → `mentions` → `https://en.wikipedia.org/wiki/Berlin`
201
+
202
+ ### What CAN'T Carry Annotations
203
+
204
+ - Plain paragraphs without inline formatting
205
+ - Bare URLs without angle brackets and `{...}` (use `<URL> {...}` instead)
206
+ - Text that's not in one of the formats above
207
+ - Multiple elements at once (one `{...}` per carrier)
208
+
209
+ **Key Rule:** The `{...}` block must come **immediately after** the value carrier.
210
+
211
+ ---
212
+
213
+ ## 5. How `{...}` Blocks Attach
214
+
215
+ A `{...}` block needs to know what it's describing. MD-LD follows simple rules to figure this out.
216
+
217
+ ### The Attachment Rules
218
+
219
+ 1. **Attach to the nearest value carrier** - The `{...}` grabs the closest thing that can carry it
220
+ 2. **Or stand alone** - If on its own line, it applies to the current subject or the next list.
221
+
222
+ ### Rule 1: Attach to Nearest Inline Carrier
223
+
224
+ ```md
225
+ [Apollo 11] {label} was launched in [1969] {nasa:launchYear}.
226
+ ```
227
+
228
+ - `{label}` attaches to `[Apollo 11]` → L = "Apollo 11"
229
+ - `{nasa:launchYear}` attaches to `[1969]` → L = "1969"
230
+
231
+ ### Rule 2: Attach to block-level Value Carrier
232
+
233
+ ```md
234
+ # Apollo 11 Mission {=ex:apollo11 .Mission label}
235
+ ```
236
+
237
+ - `{=ex:apollo11 .Mission label}` is attached to the heading block
238
+ - Sets the current subject to `ex:apollo11`
239
+ - Declares it's a `.Mission`
240
+ - Gets its `rdfs:label` as `Apollo 11 Mission`
241
+
242
+ ### Rule 3: Stand Alone for Lists
243
+
244
+ ```md
245
+ Crew members: {?crew .Person name}
246
+ - Neil Armstrong {=ex:neil}
247
+ - Buzz Aldrin {=ex:buzz}
248
+ ```
249
+
250
+ - `{?crew .Person name}` stands alone before the list, must have non-empty text before it on the same line.
251
+ - Applies to ALL list items that follow
252
+
253
+ ### What Happens When It's Ambiguous?
254
+
255
+ If MD-LD can't figure out what the `{...}` should attach to, **no data is emitted**. This prevents mistakes.
256
+
257
+ **Ambiguous example:**
258
+ ```md
259
+ Some text here {name}
260
+ ```
261
+ - "Some text here" isn't a valid value carrier
262
+ - Result: No RDF data is created
263
+
264
+ **Clear example:**
265
+ ```md
266
+ [Some text here] {name}
267
+ ```
268
+ - `[Some text here]` is a valid value carrier
269
+ - Result: Creates the expected RDF data
270
+
271
+ ---
272
+
273
+ ## 6. Setting the Subject
274
+
275
+ The **subject** is what you're talking about. Once set, it stays current until you change it.
276
+
277
+ ### Full IRI Subject
278
+
279
+ ```
280
+ {=IRI}
281
+ ```
282
+
283
+ Sets the current subject to a complete identifier.
284
+
285
+ **Example:**
286
+ ```md
287
+ # Apollo 11 {=wd:Q43653}
288
+ [1969] {nasa:launchYear}
289
+ ```
290
+
291
+ **Result:**
292
+ ```turtle
293
+ wd:Q43653 nasa:launchYear "1969" .
294
+ ```
295
+
296
+ ### Fragment Subject
297
+
298
+ ```
299
+ {=#fragment}
300
+ ```
301
+
302
+ Creates a local identifier relative to the current subject base.
303
+
304
+ **Rules:**
305
+ - Requires a current subject to exist
306
+ - Replaces any existing fragment
307
+ - Creates `currentSubjectBase#fragment`
308
+
309
+ **Example:**
310
+ ```md
311
+ [schema] {http://schema.org/}
312
+
313
+ # Document {=tag:alice@example.com,2026:doc}
314
+ ## Section 1 {=#section1}
315
+ [Section content] {schema:text}
316
+
317
+ ## Section 2 {=#section2}
318
+ [More content] {schema:text}
319
+ ```
320
+
321
+ **Result:**
322
+ ```turtle
323
+ tag:alice@example.com,2026:doc#section1 schema:text "Section content" .
324
+ tag:alice@example.com,2026:doc#section2 schema:text "More content" .
325
+ ```
326
+
327
+ ### Soft Object IRI (Temporary)
328
+
329
+ ```
330
+ {+iri}
331
+ ```
332
+
333
+ Declares a temporary object for use with `?` and `!` predicates, without changing the current subject.
334
+
335
+ ### Soft Fragment (Temporary)
336
+
337
+ ```
338
+ {+#fragment}
339
+ ```
340
+
341
+ Creates a temporary fragment relative to the current subject base.
342
+
343
+ **Use cases:**
344
+ - `[Related Item] {+ex:related ?schema:isRelatedTo}` - Links to a local fragment
345
+ - `[Parent] {+ex:parent !schema:hasPart}` - Reverse relationship
346
+ - `[Section] {+#section1 name ?hasPart}` - Object property with fragment
347
+
348
+ The soft IRI only exists within the current annotation block.
349
+
350
+ ---
351
+
352
+ ## 7. Declaring Types
353
+
354
+ Types tell us **what something is**. Use the dot notation.
355
+
356
+ ```
357
+ .Class
358
+ ```
359
+
360
+ **What it creates:**
361
+ ```
362
+ S rdf:type rdfs:Class
363
+ ```
364
+
365
+ **Example:**
366
+ ```md
367
+ # Apollo 11 {=wd:Q43653 .nasa:SpaceMission}
368
+ ```
369
+
370
+ **Result:**
371
+ ```turtle
372
+ wd:Q43653 a nasa:SpaceMission .
373
+ ```
374
+
375
+ **Multiple types are allowed:**
376
+ ```md
377
+ # Neil Armstrong {=nasa:neil .prov:Person .nasa:Astronaut}
378
+ ```
379
+
380
+ **Result:**
381
+ ```turtle
382
+ nasa:neil a prov:Person, nasa:Astronaut .
383
+ ```
384
+
385
+ **Key points:**
386
+ - Types are declared with a leading dot `.ClassName`
387
+ - Multiple types can be listed in the same `{...}`
388
+ - The current subject gets the type(s)
389
+
390
+ ---
391
+
392
+ ## 8. How Predicates Work
393
+
394
+ Predicates create the actual **facts** by connecting subjects to objects. The syntax determines the direction.
395
+
396
+ ### The Three Predicate Forms
397
+
398
+ | Syntax | Direction | What it means | Example use case |
399
+ |--------|-------------------|--------------------|------------------------|
400
+ | `p` | Subject → Literal | "Has property" | `[Apollo 11] {name}` |
401
+ | `?p` | Subject → Object | "Points to" | `[NASA] {?operator}` |
402
+ | `!p` | Object → Subject | "Is pointed at by" | `[Mission] {!hasPart}` |
403
+
404
+ ### How They Work
405
+
406
+ **`p` - Subject to Literal**
407
+ ```md
408
+ [Apollo 11] {label}
409
+ ```
410
+ Creates: `S → rdfs:label → "Apollo 11"`
411
+
412
+ **`?p` - Subject to Object**
413
+ ```md
414
+ [NASA](https://nasa.gov) {?nasa:operator}
415
+ ```
416
+ Creates: `S → nasa:operator → https://nasa.gov`
417
+
418
+ **`!p` - Object to Subject**
419
+ ```md
420
+ [Mission] {=ex:mission !member}
421
+ ```
422
+ Creates: `ex:mission → rdfs:member → S`
423
+
424
+ ### When Facts Are Created
425
+
426
+ A predicate creates a fact only when:
427
+ - All required pieces exist (subject, predicate, object)
428
+ - The roles make sense (literals can't be subjects)
429
+
430
+ If anything is missing, **no fact is created** - this prevents errors.
431
+
432
+ ### All Forms Are Required
433
+
434
+ MD-LD implementations must support all three forms. They're not optional - they're core to how MD-LD works.
435
+
436
+ ### 8.5 Diff Polarity: Remove Tokens
437
+
438
+ MD-LD supports per-predicate remove polarity using the `-` prefix. This enables diff authoring by allowing tokens to retract quads against the live graph state during parsing.
439
+
440
+ #### Remove Token Syntax
441
+
442
+ | Token | Normal Form | Remove Form | Effect |
443
+ |-------|-------------|-------------|--------|
444
+ | Literal predicate | `p` | `-p` | Remove S→L fact |
445
+ | Object predicate | `?p` | `-?p` | Remove S→O fact |
446
+ | Reverse predicate | `!p` | `-!p` | Remove O→S fact |
447
+ | Type declaration | `.C` | `-.C` | Remove rdf:type fact |
448
+
449
+ #### Live State Routing
450
+
451
+ The parser maintains a live quad buffer representing the current graph state. Remove tokens route against this state:
452
+
453
+ 1. **If quad exists in buffer** → Cancel immediately (appears nowhere)
454
+ 2. **If quad absent from buffer** → Add to remove array (external retract)
455
+
456
+ #### Examples
457
+
458
+ **Intra-document cancellation:**
459
+ ```md
460
+ [my] <tag:hr@example.com,2026:>
461
+ # Employee {=my:emp456 .my:Employee}
462
+ [Software Engineer] {my:jobTitle}
463
+ [Software Engineer] {-my:jobTitle} # Cancel previous
464
+ [Senior Software Engineer] {my:jobTitle}
465
+ ```
466
+ Result: `quads` contains only Senior Engineer title, `remove` is empty.
467
+
468
+ **External retraction:**
469
+ ```md
470
+ # Employee {=my:emp456}
471
+ [Software Engineer] {-my:jobTitle} # External retract
472
+ [Senior Software Engineer] {my:jobTitle}
473
+ ```
474
+ Result: `quads` contains Senior Engineer, `remove` contains Software Engineer.
475
+
476
+ **Mixed polarity:**
477
+ ```md
478
+ # Doc {=my:doc -.my:Draft .my:Published -my:version}
479
+ [2.0] {my:version}
480
+ ```
481
+ Same annotation can contain both add and remove tokens.
482
+
483
+ #### Invalid Remove Syntax
484
+
485
+ These tokens warn but don't support remove polarity:
486
+ - `-=IRI` - Subject declarations have no polarity
487
+ - `-+IRI` - Object declarations have no polarity
488
+ - `-^^datatype` - Datatype modifiers have no polarity
489
+ - `-@lang` - Language tags have no polarity
490
+
491
+ #### Return Structure
492
+
493
+ Parse results include a `remove` array:
494
+ ```javascript
495
+ {
496
+ quads: [...], // Final resolved graph state
497
+ remove: [...], // External retractions targeting prior state
498
+ origin: {...}, // Origin tracking with polarity
499
+ context: {...} // Final context
500
+ }
501
+ ```
502
+
503
+ **Hard invariant:** `quads ∩ remove = ∅` - no quad appears in both arrays.
504
+
505
+ ---
506
+
507
+ ## 9. Working with Literals
508
+
509
+ Literals are the actual text values - the data itself.
510
+
511
+ ### Where Literals Come From
512
+
513
+ The literal value `L` comes **only** from the value carrier you're annotating.
514
+
515
+ **Good:**
516
+ ```md
517
+ [Apollo 11] {label} ← L = "Apollo 11"
518
+ ```
519
+
520
+ **Bad:**
521
+ ```md
522
+ Apollo 11 {label} ← "Apollo 11" is not in a value carrier
523
+ ```
524
+ Result: No data is created
525
+
526
+ ### Adding Datatypes and Languages
527
+
528
+ ```
529
+ ^^datatypeIRI # For typed data
530
+ @lang # For language-specific text
531
+ ```
532
+
533
+ **Rules:**
534
+ - Use only one per literal (datatype OR language, not both)
535
+ - Never inferred - you must specify them explicitly
536
+
537
+ **Examples:**
538
+ ```md
539
+ [1969] {nasa:launchYear ^^xsd:gYear}
540
+ [July] {ex:month @en}
541
+ [Juillet] {ex:month @fr}
542
+ ```
543
+
544
+ **Results:**
545
+ ```turtle
546
+ S nasa:launchYear "1969"^^xsd:gYear .
547
+ S ex:month "July"@en .
548
+ S ex:month "Juillet"@fr .
549
+ ```
550
+
551
+ ### Common Datatypes
552
+
553
+ - `^^xsd:string` - Plain text (default)
554
+ - `^^xsd:integer` - Whole numbers
555
+ - `^^xsd:gYear` - Years (like 1969)
556
+ - `^^xsd:date` - Full dates
557
+ - `^^xsd:boolean` - true/false values
558
+
559
+ ---
560
+
561
+ ## 10. Working with Object Resources
562
+
563
+ Object resources are the **things** you link to, not the text about them.
564
+
565
+ ### Where Objects Come From
566
+
567
+ The object `O` is available only from:
568
+ - Link URLs: `[text](URL)`
569
+ - Image URLs: `![alt](URL)`
570
+ - Explicit IRIs: `{=IRI}`/`{+IRI}` inside the annotation
571
+
572
+ ### Examples
573
+
574
+ ```md
575
+ ## References {=tag:alice@example.com,2026:refs}
576
+
577
+ [Alice] {=tag:alice@example.com,2026:alice ?ex:author ex:name}
578
+ [W3C RDF](https://www.w3.org/RDF) {?dct:references label}
579
+ ![Example image](https://www.example.com/image.jpg) {?ex:image label}
580
+ ```
581
+
582
+ ### What This Creates
583
+
584
+ ```turtle
585
+ tag:alice@example.com,2026:refs ex:author <tag:alice@example.com,2026:alice> .
586
+ <tag:alice@example.com,2026:alice> ex:name "Alice" .
587
+
588
+ tag:alice@example.com,2026:refs dct:references <https://www.w3.org/RDF> .
589
+ <https://www.w3.org/RDF> rdfs:label "W3C RDF" .
590
+
591
+ tag:alice@example.com,2026:refs ex:image <https://www.example.com/image.jpg> .
592
+ <https://www.example.com/image.jpg> rdfs:label "Example image" .
593
+ ```
594
+
595
+ ### How It Works
596
+
597
+ 1. **Link URLs**: The URL becomes the object
598
+ 2. **Predicate `?`**: Connects subject to the URL object
599
+ 3. **Predicate without `?`**: Creates a fact about the URL object itself
600
+
601
+ ### Key Points
602
+
603
+ - Objects are always IRIs (web identifiers)
604
+ - Objects can be subjects of other facts in the same annotation
605
+ - Use `?` to point to objects, no prefix for facts about them
606
+
607
+ ---
608
+
609
+ ## 11. Working with Lists
610
+
611
+ Lists are pure Markdown structure with **no semantic scope**. Each list item requires explicit annotations.
612
+
613
+ ### Explicit List Annotations
614
+
615
+ Lists do not propagate semantics. Each list item must have its own explicit annotation.
616
+
617
+ **Example:** Crew members of a mission
618
+ ```md
619
+ Crew {=ex:crew .Container}
620
+
621
+ - Neil Armstrong {+ex:neil ?crew .Person name}
622
+ - Buzz Aldrin {+ex:buzz ?crew .Person name}
623
+ - Michael Collins {+ex:michael ?crew .Person name}
624
+ ```
625
+
626
+ **Key Rules:**
627
+ - No semantic propagation from list scope
628
+ - Each item must have explicit annotations
629
+ - Use `+IRI` to maintain subject chaining for repeated object properties
630
+ - Nested lists have no inheritance
631
+ - Lists are pure Markdown formatting
632
+
633
+ ### List Item Requirements
634
+
635
+ Each list item is a **single-value block carrier** - the entire text after the marker becomes the literal value.
636
+
637
+ **✅ CORRECT Patterns**
638
+
639
+ ```md
640
+ # Clean subject declaration
641
+ - **Flour** {=ex:flour}
642
+
643
+ # Subject with additional local predicates
644
+ - **Flour** {=ex:flour .c:Food label}
645
+
646
+ # Explicit subject chaining for repeated properties
647
+ - **Flour** {+ex:flour ?ingredient .c:Food label}
648
+ - **Water** {+ex:water ?ingredient .c:Food label}
649
+ ```
650
+
651
+ **Critical Rule**: **All list items must have explicit subject (`{=iri}` or `{+iri}`) to participate in semantic relationships.**
652
+
653
+ ### Valid Alternatives for Additional Information
654
+
655
+ **✅ Use Nested Lists (Pure Structure)**
656
+ ```md
657
+ - **Flour** {=ex:flour}
658
+ Properties:
659
+ - **Organic** {+ex:organic ?hasProperty .rdf:Property label}
660
+ - **Fine ground** {+ex:grind ?hasProperty .rdf:Property label}
661
+ ```
662
+
663
+ **✅ Use Separate Sections**
664
+ ```md
665
+ - **Flour** {=ex:flour}
666
+
667
+ ## Flour Properties {=ex:flour .Important}
668
+ [*Important*] {ex:priority}
669
+ ```
670
+
671
+ ### Nested Lists
672
+
673
+ Each indentation level is pure Markdown structure with no semantic inheritance:
674
+
675
+ ```md
676
+ [#vocab] <http://schema.org/>
677
+
678
+ ## Recipe {=tag:alice@example.com,2026:recipe .Recipe name}
679
+
680
+ Ingredients:
681
+
682
+ - **Flour** {+tag:alice@example.com,2026:flour ?hasPart .Ingredient name}
683
+ - **Water** {+tag:alice@example.com,2026:water ?hasPart .Ingredient name}
684
+ ```
685
+
686
+ **What This Creates:**
687
+ ```turtle
688
+ tag:alice@example.com,2026:recipe a schema:Recipe ;
689
+ schema:name "Recipe" ;
690
+ schema:hasPart tag:alice@example.com,2026:flour, tag:alice@example.com,2026:water .
691
+
692
+ tag:alice@example.com,2026:flour a schema:Ingredient ;
693
+ schema:name "Flour" .
694
+
695
+ tag:alice@example.com,2026:water a schema:Ingredient ;
696
+ schema:name "Water" .
697
+ ```
698
+
699
+ ### Ordered lists
700
+
701
+ For legacy scenarios like SHACL `sh:in`, `sh:or`, you can manually construct `.rdf:List` structures using explicit syntax:
702
+
703
+ ```md
704
+ [ex] <http://example.org/>
705
+
706
+ # Manual list construction {=ex:manualList label}
707
+ [head] {=ex:l1 ?sh:in .rdf:List}
708
+ [a] {+ex:A ?rdf:first}
709
+ [list2] {=ex:l2 ?rdf:rest}
710
+ [b] {+ex:B ?rdf:first}
711
+ [nil] {+rdf:nil ?rdf:rest}
712
+ ```
713
+
714
+ ---
715
+
716
+ ## 12. Reverse Relationships
717
+
718
+ Reverse predicates flip the direction of a relationship without changing its meaning.
719
+
720
+ ### How It Works
721
+
722
+ **Normal predicate (`p`):** Subject → Object
723
+
724
+ ```md
725
+ # The Mission {ex:mission}
726
+ Includes parts: [Crew] {=ex:crew member}
727
+ ```
728
+
729
+ Creates: `Mission → mamber → Crew`
730
+
731
+ **Reverse predicate (`!p`):** Object → Subject
732
+
733
+ ```md
734
+ # The Crew {=ex:crew}
735
+ Is included in [The Mission] {=ex:mission !member}
736
+ ```
737
+
738
+ Creates the same triple: `Mission → member → Crew`
739
+
740
+ ### Practical Example
741
+
742
+ ```md
743
+ # Flour {=ex:flour}
744
+ Used in: {!ex:hasPart}
745
+ - Bread {=ex:bread}
746
+ ```
747
+
748
+ **Result:**
749
+ ```turtle
750
+ ex:bread ex:hasPart ex:flour .
751
+ ```
752
+
753
+ ### When to Use Reverse Relationships
754
+
755
+ Use `!` when you want to:
756
+ - Point back to the current subject from an object
757
+ - Create bidirectional relationships
758
+ - Express "is part of" vs "has part"
759
+
760
+ **Example:**
761
+ ```md
762
+ [book] <tag:alice@example.com,2026:book:>
763
+
764
+ # Chapter 1 {=book:chapter1 .book:Chapter label}
765
+ Is part of the [Book] {=book:book !book:hasPart ?book:partOf .book:Book book:title}
766
+ ```
767
+
768
+ **Creates:**
769
+ ```turtle
770
+ book:chapter1 a book:Chapter ;
771
+ rdfs:label "Chapter 1";
772
+ book:partOf book:Book .
773
+
774
+ book:book a book:Book ;
775
+ book:title "Book" ;
776
+ book:hasPart book:chapter1 .
777
+ ```
778
+
779
+ ### Key Points
780
+
781
+ - `!` only flips direction, not meaning
782
+ - Useful for creating inverse and mutual relationships
783
+ - The object becomes the subject in the resulting fact
784
+
785
+ ---
786
+
787
+ ## 13. Code Blocks
788
+
789
+ Code blocks can carry annotations when you put `{...}` on the opening fence.
790
+
791
+ ### How It Works
792
+
793
+ ```md
794
+ ``js {=ex:code .exSoftwareSourceCode ex:text}
795
+ console.log("hi")
796
+ ``
797
+ ```
798
+
799
+ The code block content is not parsed as MDLD and is available as the literal value.
800
+
801
+ ### Example
802
+
803
+ ````md
804
+ ```js {=ex:code .ex:SoftwareSourceCode ex:text}
805
+ console.log("hi")
806
+ ```
807
+
808
+ We can add a programming language or any additional info after the block as regular property annotations - *JavaScript* {ex:language}.
809
+ ````
810
+
811
+ ### What It Creates
812
+
813
+ ```turtle
814
+ ex:code a ex:SoftwareSourceCode ;
815
+ ex:text "console.log(\"hi\")" ;
816
+ ex:language "JavaScript" .
817
+ ```
818
+
819
+ ### Key Points
820
+
821
+ - The `{...}` goes on the opening fence line
822
+ - The entire code content becomes the literal
823
+ - Useful for documenting code, scripts, and configuration
824
+
825
+ ---
826
+
827
+ ## 14. Semantic Reset (normative)
828
+
829
+ An empty subject declaration `{=}` establishes a semantic reset boundary.
830
+
831
+ Upon encountering `{=}`, an MD-LD processor MUST:
832
+ - Reset the current subject
833
+ - Reset all active predicates
834
+ - Reset list scopes and reverse predicates
835
+ - Clear any pending annotation context
836
+
837
+ ## 15. Context and Vocabulary
838
+
839
+ Context tells MD-LD how to expand short names into full identifiers.
840
+
841
+ ### Default Context
842
+
843
+ MD-LD always provides this context by default:
844
+
845
+ ```json
846
+ {
847
+ "@vocab": "http://www.w3.org/2000/01/rdf-schema#",
848
+ "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
849
+ "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
850
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
851
+ "sh": "http://www.w3.org/ns/shacl#",
852
+ "prov": "http://www.w3.org/ns/prov#"
853
+ }
854
+ ```
855
+
856
+ This means:
857
+ - `label` expands to `http://www.w3.org/2000/01/rdf-schema#label`
858
+ - `rdf:type` expands to `http://www.w3.org/1999/02/22-rdf-syntax-ns#type`
859
+
860
+
861
+ ### Adding Prefixes
862
+
863
+ Declare prefixes for your own identifiers:
864
+
865
+ ```md
866
+ [alice] <tag:alice@example.com,2026:>
867
+ [wd] <https://www.wikidata.org/entity/>
868
+ ```
869
+
870
+ Now you can use:
871
+ - `alice:person` → `tag:alice@example.com,2026:person`
872
+ - `wd:Q43653` → `https://www.wikidata.org/entity/Q43653`
873
+
874
+ ### Prefix Folding: Hierarchical IRI Authoring
875
+
876
+ Build namespace hierarchies by referencing previously declared prefixes:
877
+
878
+ ```md
879
+ # Domain authority
880
+ [my] <tag:mymail@domain.com,2026:>
881
+
882
+ # Hierarchical prefixes
883
+ [j] <my:journal:>
884
+ [p] <my:property:>
885
+ [c] <my:class:>
886
+ [person] <my:people:>
887
+
888
+ # Multi-level nesting
889
+ [org] <https://org.example.com/>
890
+ [person] <org:person/>
891
+ [emp] <person:employee/>
892
+ [dev] <emp:developer/>
893
+ ```
894
+
895
+ **Resolution Rules:**
896
+ - Prefixes must be declared before they can be referenced (forward-reference only)
897
+ - References are resolved immediately during declaration
898
+ - Circular references are treated as literal strings
899
+ - Later declarations override earlier ones
900
+
901
+ **Examples:**
902
+ - `j:2026-01-27` → `tag:mymail@domain.com,2026:journal:2026-01-27`
903
+ - `emp:harry` → `https://org.example.com/person/employee/harry`
904
+ - `dev:john` → `https://org.example.com/person/employee/developer/john`
905
+
906
+ This enables lightweight IRI authoring without external ontology dependencies, perfect for personal knowledge graphs and domain-specific namespaces.
907
+
908
+ ### Setting Vocabulary
909
+
910
+ Change the default vocabulary (http://www.w3.org/2000/01/rdf-schema#):
911
+
912
+ ```md
913
+ [@vocab] <http://schema.org/>
914
+ ```
915
+
916
+ Now unprefixed terms use your namespace:
917
+ - `name` → `http://schema.org/name`
918
+ - `Person` → `http://schema.org/Person`
919
+
920
+ ### Context Rules
921
+
922
+ - Context applies forward from where you declare it
923
+ - Later declarations override earlier ones
924
+ - Initial context can't be removed, only overridden
925
+ - Works in a single pass - no look-ahead needed
926
+
927
+
928
+ ## 16. What MD-LD Doesn't Do
929
+
930
+ To keep things simple and predictable, MD-LD explicitly avoids these features:
931
+
932
+ ### Forbidden Constructs
933
+
934
+ - **Implicit labels** - No automatic naming from structure
935
+ - **Structural inference** - No guessing from document layout
936
+ - **Auto-subjects** - No automatic subject creation
937
+ - **Literal lists** - Structure doesn't imply semantics
938
+ - **Blank nodes** - Every entity must have a proper identifier
939
+ - **key=value syntax** - Use explicit `{...}` format instead
940
+ - **Predicate guessing** - No automatic predicate selection
941
+ - **Backtracking parses** - Always single-pass, forward-only
942
+ - **CURIE in Markdown links** - Keep links and semantics separate
943
+ - **Semantic list propagation** - No implicit semantics from list structures
944
+
945
+ ### Why These Are Forbidden
946
+
947
+ These restrictions make MD-LD:
948
+ - **Predictable** - Same input always produces same output
949
+ - **Traceable** - Every fact comes from an explicit annotation
950
+ - **Fast** - Can process in a single pass
951
+ - **Clear** - No magic or hidden behavior
952
+
953
+ If you need these features, use them in your application logic, not in the MD-LD syntax itself.
954
+
955
+ ---
956
+
957
+ ## 17. Primary Subject
958
+
959
+ The **Primary Subject** is the main entity described by an MD-LD document. It provides a deterministic way to identify the central focus of a document.
960
+
961
+ ### Selection Criteria
962
+
963
+ The Primary Subject is determined by these rules:
964
+
965
+ 1. **First non-fragment subject declaration** - The first `{=IRI}` declaration in the document becomes the primary subject
966
+ 2. **Fragment declarations are excluded** - `{=#fragment}` declarations do not become primary subjects
967
+ 3. **Fixed once detected** - Once set, the primary subject never changes, even on `{=}` reset
968
+ 4. **No subject means no primary** - If no subject is declared, the primary subject is `null`
969
+
970
+ ### Examples
971
+
972
+ **Simple primary subject:**
973
+ ```md
974
+ [ex] <http://example.org/>
975
+
976
+ # Document {=ex:doc .ex:Article label}
977
+ [Alice] {ex:author}
978
+ ```
979
+ Primary subject: `ex:doc`
980
+
981
+ **Fragment does not become primary:**
982
+ ```md
983
+ [ex] <http://example.org/>
984
+
985
+ # Document {=ex:doc}
986
+ {=#summary}
987
+ [Content] {label}
988
+ ```
989
+ Primary subject: `ex:doc` (fragment `#summary` is ignored)
990
+
991
+ **Subject reset:**
992
+ ```md
993
+ [ex] <http://example.org/>
994
+
995
+ # First {=ex:first}
996
+ [Value] {label}
997
+
998
+ # Reset {=}
999
+
1000
+ # Second {=ex:second}
1001
+ [Value] {label}
1002
+ ```
1003
+ Primary subject: `ex:first` (reset does not clear the primary)
1004
+
1005
+ ### API Return Values
1006
+
1007
+ **parse() returns:**
1008
+ ```javascript
1009
+ {
1010
+ quads: [...],
1011
+ remove: [...],
1012
+ origin: {...},
1013
+ context: {...},
1014
+ primarySubject: string | null
1015
+ }
1016
+ ```
1017
+
1018
+ **merge() returns:**
1019
+ ```javascript
1020
+ {
1021
+ quads: [...],
1022
+ remove: [...],
1023
+ origin: {...},
1024
+ context: {...},
1025
+ primarySubjects: string[] // ordered by merge
1026
+ }
1027
+ ```
1028
+
1029
+ ### Use Cases
1030
+
1031
+ Primary subjects enable:
1032
+ - **Document identification** - Quickly determine what a document is about
1033
+ - **Merge tracking** - Track which entities are being merged across documents
1034
+ - **UI navigation** - Provide a default focus point for document viewers
1035
+ - **Query optimization** - Use primary subject as default query context
1036
+
1037
+ ### Conformance Requirements
1038
+
1039
+ An MD-LD processor MUST:
1040
+ 1. Track the first non-fragment subject declaration as primary subject
1041
+ 2. Return `primarySubject` in parse results (or `null` if none)
1042
+ 3. Return `primarySubjects` array in merge results (ordered by merge)
1043
+ 4. Keep primary subject fixed once detected (never cleared on `{=}` reset)
1044
+
1045
+ ---
1046
+
1047
+ ## 18. Conformance
1048
+
1049
+ An MD-LD processor is conformant if it follows these rules:
1050
+
1051
+ ### Required Behaviors
1052
+
1053
+ 1. **Follow predicate routing rules** - All facts must follow §8 patterns
1054
+ 2. **Explicit source only** - All facts must come from `{...}` blocks
1055
+ 3. **Single-pass parsing** - Must be implementable as streaming algorithm
1056
+ 4. **Deterministic output** - Same input always produces same output
1057
+ 5. **Traceable origins** - Every fact must be traceable to its source
1058
+
1059
+ ### What This Means
1060
+
1061
+ - **No guessing** - Processors can't infer or assume anything
1062
+ - **No blank nodes** - Every entity must have an IRI
1063
+ - **No backtracking** - Must process forward-only
1064
+ - **Round-trip preservation** - MD → RDF → MD should preserve all facts
1065
+
1066
+ If you implement these rules, you have a conformant MD-LD processor.
1067
+
1068
+ ---