mdld-parse 0.9.1 → 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.
- package/README.md +34 -1
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +1 -0
- package/dist/README.md +425 -0
- package/dist/docs/API.md +397 -0
- package/dist/docs/Architecture.md +190 -0
- package/dist/docs/Guide.md +322 -0
- package/dist/docs/LLM-MDLD-Inducer.md +550 -0
- package/dist/docs/Parser.md +654 -0
- package/dist/docs/Performance.md +238 -0
- package/dist/docs/Spec-render.md +1439 -0
- package/dist/docs/Subject.md +180 -0
- package/dist/docs/Syntax.md +463 -0
- package/dist/docs/TodoList.md +215 -0
- package/dist/docs/Use-Cases.md +354 -0
- package/dist/docs/index.html +108 -0
- package/dist/docs/index.md +56 -0
- package/dist/docs/origin.md +459 -0
- package/dist/docs/polarity.md +586 -0
- package/dist/docs/primary-subject.md +199 -0
- package/dist/docs/statements.md +226 -0
- package/dist/docs/tokenization-performance-report.md +164 -0
- package/dist/examples/Cookbook.md +32 -0
- package/dist/examples/Status-SHACL.md +33 -0
- package/dist/examples/demo/index.md +35 -0
- package/dist/examples/demo/journal.md +18 -0
- package/dist/examples/demo/minimal.md +11 -0
- package/dist/examples/demo/project.md +15 -0
- package/dist/examples/demo/recipe.md +31 -0
- package/dist/examples/demo/research.md +46 -0
- package/dist/examples/demo/space-mission.md +48 -0
- package/dist/examples/dogfood.md +288 -0
- package/dist/examples/few-shot.md +309 -0
- package/dist/examples/graph/rdf-graph.html +473 -0
- package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
- package/dist/examples/index.md +45 -0
- package/dist/examples/llm-time-workflow.md +173 -0
- package/dist/examples/prov-o.md +2367 -0
- package/dist/examples/rdf.md +827 -0
- package/dist/examples/shacl.md +3399 -0
- package/dist/examples/statements.md +43 -0
- package/dist/examples/workflow.md +150 -0
- package/dist/index.html +2827 -0
- package/dist/index.js +1548 -0
- package/dist/logo.svg +7 -0
- package/dist/spec/Spec-compact.md +363 -0
- package/dist/spec/Spec-ultra.md +221 -0
- package/dist/spec/Spec.md +1068 -0
- package/dist/spec/index.md +46 -0
- package/package.json +13 -8
- package/src/constants.js +0 -31
- package/src/generate.js +0 -245
- package/src/index.js +0 -13
- package/src/locate.js +0 -23
- package/src/merge.js +0 -157
- package/src/parse.js +0 -765
- package/src/render.js +0 -576
- package/src/shared.js +0 -577
- 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
|
+
 {?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 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
|
+
- ` {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: ``
|
|
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
|
+
 {?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
|
+
---
|