mdld-parse 0.9.5 → 0.9.8
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 +56 -51
- package/dist/README.md +56 -51
- package/dist/docs/API.md +41 -5
- package/dist/docs/Parser.md +17 -7
- package/dist/docs/primary-subject.md +99 -23
- package/dist/examples/demo/journal.md +27 -86
- package/dist/examples/demo/project.md +50 -64
- package/dist/examples/demo/recipe.md +24 -69
- package/dist/examples/demo/research.md +37 -79
- package/dist/examples/demo/space-mission.md +32 -103
- package/dist/index.html +192 -422
- package/dist/index.js +35 -29
- package/package.json +1 -1
- package/dist/docs/Nostr.md +0 -544
package/README.md
CHANGED
|
@@ -57,45 +57,12 @@ console.log(result.quads);
|
|
|
57
57
|
- **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
|
|
58
58
|
- **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
|
|
59
59
|
- **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
|
|
60
|
-
- **🏷️ Primary metadata** -
|
|
60
|
+
- **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
|
|
61
61
|
|
|
62
62
|
## 🌟 What is MD-LD?
|
|
63
63
|
|
|
64
64
|
MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
|
|
65
65
|
|
|
66
|
-
## ⚡ Performance & Architecture
|
|
67
|
-
|
|
68
|
-
MD-LD v0.10.0 features a **character-based tokenization system** for optimal performance:
|
|
69
|
-
|
|
70
|
-
- **20-28% faster parsing** than regex-based approaches
|
|
71
|
-
- **Memory-efficient** with ~640 bytes per quad retained
|
|
72
|
-
- **Streaming-friendly** with O(n) linear time complexity
|
|
73
|
-
- **Character-based detection** replaces complex regex patterns
|
|
74
|
-
- **Unified tokenizer architecture** in `src/tokenizers.js`
|
|
75
|
-
|
|
76
|
-
### Tokenizer Architecture
|
|
77
|
-
|
|
78
|
-
The parser uses specialized character-based tokenizers:
|
|
79
|
-
|
|
80
|
-
```javascript
|
|
81
|
-
// Block-level tokenizers
|
|
82
|
-
detectFence() // ```code blocks
|
|
83
|
-
detectPrefix() // [prefix] <iri>
|
|
84
|
-
detectHeading() // # Headings
|
|
85
|
-
detectList() // - List items
|
|
86
|
-
detectBlockquote() // > Blockquotes
|
|
87
|
-
detectStandaloneSubject() // {=subject}
|
|
88
|
-
|
|
89
|
-
// Inline carrier scanner
|
|
90
|
-
scanInlineCarriers() // [text], **bold**, `code`, <URL>
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
This design provides:
|
|
94
|
-
- **Better maintainability** - Easier to debug and extend
|
|
95
|
-
- **Improved error handling** - More precise edge case detection
|
|
96
|
-
- **Cleaner code structure** - No complex regex patterns
|
|
97
|
-
- **Full backward compatibility** - All 127 tests passing
|
|
98
|
-
|
|
99
66
|
```markdown
|
|
100
67
|
[my] <tag:alice@example.com,2026:>
|
|
101
68
|
# 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
|
|
@@ -118,13 +85,15 @@ pnpm install mdld-parse
|
|
|
118
85
|
```javascript
|
|
119
86
|
import { parse } from 'mdld-parse';
|
|
120
87
|
|
|
121
|
-
const markdown =
|
|
122
|
-
[Alice] {author}`;
|
|
88
|
+
const markdown = `[ex] <tag:alice@example.org,2026:>
|
|
123
89
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
}
|
|
90
|
+
# Demo document {=ex:example/doc .prov:Entity label}
|
|
91
|
+
|
|
92
|
+
> A demo document for MD-LD {comment}
|
|
93
|
+
[Alice] {+ex:alice ?ex:author .prov:Person label}
|
|
94
|
+
`;
|
|
95
|
+
|
|
96
|
+
const result = parse({ text: markdown });
|
|
128
97
|
|
|
129
98
|
console.log(result.quads);
|
|
130
99
|
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
@@ -136,7 +105,7 @@ console.log(result.quads);
|
|
|
136
105
|
<script type="module">
|
|
137
106
|
import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
|
|
138
107
|
|
|
139
|
-
const result = parse('# Hello {=ex:hello label}');
|
|
108
|
+
const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
|
|
140
109
|
</script>
|
|
141
110
|
```
|
|
142
111
|
|
|
@@ -154,9 +123,9 @@ Each predicate form determines the graph edge:
|
|
|
154
123
|
|
|
155
124
|
| Form | Edge | Example | Meaning |
|
|
156
125
|
|-------|---------|------------------------------|------------------|
|
|
157
|
-
| `p` | S → L | `[Alice] {
|
|
126
|
+
| `p` | S → L | `[Alice] {label}` | literal property |
|
|
158
127
|
| `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
|
|
159
|
-
| `!p`
|
|
128
|
+
| `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
|
|
160
129
|
|
|
161
130
|
## 📍 Elevated Statements
|
|
162
131
|
|
|
@@ -233,18 +202,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
|
|
|
233
202
|
- `dataFactory` (object, optional) — Custom RDF/JS DataFactory
|
|
234
203
|
- `graph` (string, optional) — Named graph IRI
|
|
235
204
|
|
|
236
|
-
**Returns:** `{ quads, remove, statements, origin, context, primarySubject,
|
|
205
|
+
**Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
|
|
237
206
|
|
|
238
207
|
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
239
208
|
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
240
209
|
- `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
|
|
241
210
|
- `origin` — Lean origin tracking object with quadIndex for UI navigation
|
|
242
211
|
- `context` — Final context used (includes prefixes)
|
|
243
|
-
- `primarySubject` — String IRI or null (
|
|
244
|
-
- `
|
|
245
|
-
- `primaryLabel` — String or null (first rdfs:label literal)
|
|
212
|
+
- `primarySubject` — String IRI or null (canonical append identity)
|
|
213
|
+
- `primary` — Object containing primary metadata (semantic surface descriptor)
|
|
246
214
|
- `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
|
|
247
215
|
|
|
216
|
+
**Dual-Layer Architecture:**
|
|
217
|
+
|
|
218
|
+
| Layer | Field | Purpose | Use Cases |
|
|
219
|
+
|-------|-------|---------|-----------|
|
|
220
|
+
| **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
|
|
221
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
|
|
222
|
+
|
|
223
|
+
**Primary Object Structure:**
|
|
224
|
+
```javascript
|
|
225
|
+
primary: {
|
|
226
|
+
subject: string | null, // First non-fragment subject declaration
|
|
227
|
+
type: string | null, // First rdf:type declaration
|
|
228
|
+
label: string | null // First rdfs:label literal
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
248
232
|
### `merge(docs, options)`
|
|
249
233
|
|
|
250
234
|
Merge multiple MDLD documents with diff polarity resolution.
|
|
@@ -254,13 +238,34 @@ Merge multiple MDLD documents with diff polarity resolution.
|
|
|
254
238
|
- `options` (object, optional):
|
|
255
239
|
- `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
|
|
256
240
|
|
|
257
|
-
**Returns:** `{ quads, remove, origin, context, primarySubjects }`
|
|
241
|
+
**Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
|
|
258
242
|
|
|
259
243
|
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
260
244
|
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
261
|
-
- `origin` — Merge origin
|
|
262
|
-
- `context` — Final
|
|
263
|
-
- `primarySubjects` — Array of string IRIs (
|
|
245
|
+
- `origin` — Merge origin with document tracking
|
|
246
|
+
- `context` — Final context used (includes prefixes)
|
|
247
|
+
- `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
|
|
248
|
+
- `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
|
|
249
|
+
|
|
250
|
+
**Dual-Layer Architecture:**
|
|
251
|
+
|
|
252
|
+
| Layer | Field | Purpose | Use Cases |
|
|
253
|
+
|-------|-------|---------|-----------|
|
|
254
|
+
| **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
|
|
255
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
|
|
256
|
+
|
|
257
|
+
**Primary Object Array Structure:**
|
|
258
|
+
```javascript
|
|
259
|
+
primary: [
|
|
260
|
+
{
|
|
261
|
+
subject: string | null, // First non-fragment subject declaration
|
|
262
|
+
type: string | null, // First rdf:type declaration
|
|
263
|
+
label: string | null // First rdfs:label literal
|
|
264
|
+
},
|
|
265
|
+
// ... one object per document
|
|
266
|
+
]
|
|
267
|
+
```
|
|
268
|
+
|
|
264
269
|
|
|
265
270
|
### `generate({ quads, context, primarySubject })`
|
|
266
271
|
|
package/dist/README.md
CHANGED
|
@@ -57,45 +57,12 @@ console.log(result.quads);
|
|
|
57
57
|
- **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
|
|
58
58
|
- **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
|
|
59
59
|
- **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
|
|
60
|
-
- **🏷️ Primary metadata** -
|
|
60
|
+
- **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
|
|
61
61
|
|
|
62
62
|
## 🌟 What is MD-LD?
|
|
63
63
|
|
|
64
64
|
MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
|
|
65
65
|
|
|
66
|
-
## ⚡ Performance & Architecture
|
|
67
|
-
|
|
68
|
-
MD-LD v0.10.0 features a **character-based tokenization system** for optimal performance:
|
|
69
|
-
|
|
70
|
-
- **20-28% faster parsing** than regex-based approaches
|
|
71
|
-
- **Memory-efficient** with ~640 bytes per quad retained
|
|
72
|
-
- **Streaming-friendly** with O(n) linear time complexity
|
|
73
|
-
- **Character-based detection** replaces complex regex patterns
|
|
74
|
-
- **Unified tokenizer architecture** in `src/tokenizers.js`
|
|
75
|
-
|
|
76
|
-
### Tokenizer Architecture
|
|
77
|
-
|
|
78
|
-
The parser uses specialized character-based tokenizers:
|
|
79
|
-
|
|
80
|
-
```javascript
|
|
81
|
-
// Block-level tokenizers
|
|
82
|
-
detectFence() // ```code blocks
|
|
83
|
-
detectPrefix() // [prefix] <iri>
|
|
84
|
-
detectHeading() // # Headings
|
|
85
|
-
detectList() // - List items
|
|
86
|
-
detectBlockquote() // > Blockquotes
|
|
87
|
-
detectStandaloneSubject() // {=subject}
|
|
88
|
-
|
|
89
|
-
// Inline carrier scanner
|
|
90
|
-
scanInlineCarriers() // [text], **bold**, `code`, <URL>
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
This design provides:
|
|
94
|
-
- **Better maintainability** - Easier to debug and extend
|
|
95
|
-
- **Improved error handling** - More precise edge case detection
|
|
96
|
-
- **Cleaner code structure** - No complex regex patterns
|
|
97
|
-
- **Full backward compatibility** - All 127 tests passing
|
|
98
|
-
|
|
99
66
|
```markdown
|
|
100
67
|
[my] <tag:alice@example.com,2026:>
|
|
101
68
|
# 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
|
|
@@ -118,13 +85,15 @@ pnpm install mdld-parse
|
|
|
118
85
|
```javascript
|
|
119
86
|
import { parse } from 'mdld-parse';
|
|
120
87
|
|
|
121
|
-
const markdown =
|
|
122
|
-
[Alice] {author}`;
|
|
88
|
+
const markdown = `[ex] <tag:alice@example.org,2026:>
|
|
123
89
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
}
|
|
90
|
+
# Demo document {=ex:example/doc .prov:Entity label}
|
|
91
|
+
|
|
92
|
+
> A demo document for MD-LD {comment}
|
|
93
|
+
[Alice] {+ex:alice ?ex:author .prov:Person label}
|
|
94
|
+
`;
|
|
95
|
+
|
|
96
|
+
const result = parse({ text: markdown });
|
|
128
97
|
|
|
129
98
|
console.log(result.quads);
|
|
130
99
|
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
@@ -136,7 +105,7 @@ console.log(result.quads);
|
|
|
136
105
|
<script type="module">
|
|
137
106
|
import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
|
|
138
107
|
|
|
139
|
-
const result = parse('# Hello {=ex:hello label}');
|
|
108
|
+
const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
|
|
140
109
|
</script>
|
|
141
110
|
```
|
|
142
111
|
|
|
@@ -154,9 +123,9 @@ Each predicate form determines the graph edge:
|
|
|
154
123
|
|
|
155
124
|
| Form | Edge | Example | Meaning |
|
|
156
125
|
|-------|---------|------------------------------|------------------|
|
|
157
|
-
| `p` | S → L | `[Alice] {
|
|
126
|
+
| `p` | S → L | `[Alice] {label}` | literal property |
|
|
158
127
|
| `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
|
|
159
|
-
| `!p`
|
|
128
|
+
| `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
|
|
160
129
|
|
|
161
130
|
## 📍 Elevated Statements
|
|
162
131
|
|
|
@@ -233,18 +202,33 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
|
|
|
233
202
|
- `dataFactory` (object, optional) — Custom RDF/JS DataFactory
|
|
234
203
|
- `graph` (string, optional) — Named graph IRI
|
|
235
204
|
|
|
236
|
-
**Returns:** `{ quads, remove, statements, origin, context, primarySubject,
|
|
205
|
+
**Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
|
|
237
206
|
|
|
238
207
|
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
239
208
|
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
240
209
|
- `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
|
|
241
210
|
- `origin` — Lean origin tracking object with quadIndex for UI navigation
|
|
242
211
|
- `context` — Final context used (includes prefixes)
|
|
243
|
-
- `primarySubject` — String IRI or null (
|
|
244
|
-
- `
|
|
245
|
-
- `primaryLabel` — String or null (first rdfs:label literal)
|
|
212
|
+
- `primarySubject` — String IRI or null (canonical append identity)
|
|
213
|
+
- `primary` — Object containing primary metadata (semantic surface descriptor)
|
|
246
214
|
- `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
|
|
247
215
|
|
|
216
|
+
**Dual-Layer Architecture:**
|
|
217
|
+
|
|
218
|
+
| Layer | Field | Purpose | Use Cases |
|
|
219
|
+
|-------|-------|---------|-----------|
|
|
220
|
+
| **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
|
|
221
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
|
|
222
|
+
|
|
223
|
+
**Primary Object Structure:**
|
|
224
|
+
```javascript
|
|
225
|
+
primary: {
|
|
226
|
+
subject: string | null, // First non-fragment subject declaration
|
|
227
|
+
type: string | null, // First rdf:type declaration
|
|
228
|
+
label: string | null // First rdfs:label literal
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
248
232
|
### `merge(docs, options)`
|
|
249
233
|
|
|
250
234
|
Merge multiple MDLD documents with diff polarity resolution.
|
|
@@ -254,13 +238,34 @@ Merge multiple MDLD documents with diff polarity resolution.
|
|
|
254
238
|
- `options` (object, optional):
|
|
255
239
|
- `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
|
|
256
240
|
|
|
257
|
-
**Returns:** `{ quads, remove, origin, context, primarySubjects }`
|
|
241
|
+
**Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
|
|
258
242
|
|
|
259
243
|
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
260
244
|
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
261
|
-
- `origin` — Merge origin
|
|
262
|
-
- `context` — Final
|
|
263
|
-
- `primarySubjects` — Array of string IRIs (
|
|
245
|
+
- `origin` — Merge origin with document tracking
|
|
246
|
+
- `context` — Final context used (includes prefixes)
|
|
247
|
+
- `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
|
|
248
|
+
- `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
|
|
249
|
+
|
|
250
|
+
**Dual-Layer Architecture:**
|
|
251
|
+
|
|
252
|
+
| Layer | Field | Purpose | Use Cases |
|
|
253
|
+
|-------|-------|---------|-----------|
|
|
254
|
+
| **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
|
|
255
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
|
|
256
|
+
|
|
257
|
+
**Primary Object Array Structure:**
|
|
258
|
+
```javascript
|
|
259
|
+
primary: [
|
|
260
|
+
{
|
|
261
|
+
subject: string | null, // First non-fragment subject declaration
|
|
262
|
+
type: string | null, // First rdf:type declaration
|
|
263
|
+
label: string | null // First rdfs:label literal
|
|
264
|
+
},
|
|
265
|
+
// ... one object per document
|
|
266
|
+
]
|
|
267
|
+
```
|
|
268
|
+
|
|
264
269
|
|
|
265
270
|
### `generate({ quads, context, primarySubject })`
|
|
266
271
|
|
package/dist/docs/API.md
CHANGED
|
@@ -14,15 +14,30 @@ Parse MD-LD markdown and return RDF quads.
|
|
|
14
14
|
- `dataFactory` (object, optional) — Custom RDF/JS DataFactory
|
|
15
15
|
- `graph` (string, optional) — Named graph IRI
|
|
16
16
|
|
|
17
|
-
**Returns:** `{ quads, context, primarySubject,
|
|
17
|
+
**Returns:** `{ quads, context, primarySubject, primary, origin, remove, statements }`
|
|
18
18
|
|
|
19
19
|
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
20
20
|
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
21
21
|
- `origin` — Lean origin tracking object with quadIndex for UI navigation
|
|
22
22
|
- `context` — Final context used (includes prefixes)
|
|
23
|
-
- `primarySubject` — String IRI or null (
|
|
24
|
-
- `
|
|
25
|
-
|
|
23
|
+
- `primarySubject` — String IRI or null (canonical append identity)
|
|
24
|
+
- `primary` — Object containing primary metadata (semantic surface descriptor)
|
|
25
|
+
|
|
26
|
+
**Dual-Layer Architecture:**
|
|
27
|
+
|
|
28
|
+
| Layer | Field | Purpose | Use Cases |
|
|
29
|
+
|-------|-------|---------|-----------|
|
|
30
|
+
| **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
|
|
31
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
|
|
32
|
+
|
|
33
|
+
**Primary Object Structure:**
|
|
34
|
+
```javascript
|
|
35
|
+
primary: {
|
|
36
|
+
subject: string | null, // First non-fragment subject declaration
|
|
37
|
+
type: string | null, // First rdf:type declaration
|
|
38
|
+
label: string | null // First rdfs:label literal
|
|
39
|
+
}
|
|
40
|
+
```
|
|
26
41
|
|
|
27
42
|
> Legacy: `parse(text, options)` supported for backward compatibility (deprecated)
|
|
28
43
|
|
|
@@ -125,7 +140,7 @@ Merge multiple MDLD documents with diff polarity resolution.
|
|
|
125
140
|
- `options` (object, optional):
|
|
126
141
|
- `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
|
|
127
142
|
|
|
128
|
-
**Returns:** `{ quads, remove, origin, context }`
|
|
143
|
+
**Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
|
|
129
144
|
|
|
130
145
|
- `quads` — Merged array of RDF/JS Quads
|
|
131
146
|
- `remove` — Array of retractions from merge process
|
|
@@ -133,6 +148,27 @@ Merge multiple MDLD documents with diff polarity resolution.
|
|
|
133
148
|
- `documents` — Array of document metadata
|
|
134
149
|
- `quadIndex` — Combined quad index from all documents
|
|
135
150
|
- `context` — Final merged context
|
|
151
|
+
- `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
|
|
152
|
+
- `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
|
|
153
|
+
|
|
154
|
+
**Dual-Layer Architecture:**
|
|
155
|
+
|
|
156
|
+
| Layer | Field | Purpose | Use Cases |
|
|
157
|
+
|-------|-------|---------|-----------|
|
|
158
|
+
| **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
|
|
159
|
+
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
|
|
160
|
+
|
|
161
|
+
**Primary Object Array Structure:**
|
|
162
|
+
```javascript
|
|
163
|
+
primary: [
|
|
164
|
+
{
|
|
165
|
+
subject: string | null, // First non-fragment subject declaration
|
|
166
|
+
type: string | null, // First rdf:type declaration
|
|
167
|
+
label: string | null // First rdfs:label literal
|
|
168
|
+
},
|
|
169
|
+
// ... one object per document
|
|
170
|
+
]
|
|
171
|
+
```
|
|
136
172
|
|
|
137
173
|
#### Basic Merge Example
|
|
138
174
|
|
package/dist/docs/Parser.md
CHANGED
|
@@ -530,13 +530,23 @@ for (let i = 0; i < tokens.length; i++) {
|
|
|
530
530
|
// Process retractions and ensure hard invariant
|
|
531
531
|
const filteredRemove = processRetractions(state.quads, state.removeSet);
|
|
532
532
|
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
};
|
|
533
|
+
// Create structured primary object for semantic surface
|
|
534
|
+
const primary = {
|
|
535
|
+
subject: state.primarySubject,
|
|
536
|
+
type: state.primaryType,
|
|
537
|
+
label: state.primaryLabel,
|
|
538
|
+
comment: state.primaryComment
|
|
539
|
+
};
|
|
540
|
+
|
|
541
|
+
return {
|
|
542
|
+
quads: state.quads, // Final resolved graph state
|
|
543
|
+
remove: filteredRemove, // External retractions only
|
|
544
|
+
statements: state.statements, // Elevated statements
|
|
545
|
+
origin: state.origin, // Complete provenance
|
|
546
|
+
context: state.ctx, // Final prefix context
|
|
547
|
+
primarySubject: state.primarySubject, // Canonical append identity
|
|
548
|
+
primary // Semantic surface descriptor
|
|
549
|
+
};
|
|
540
550
|
```
|
|
541
551
|
|
|
542
552
|
#### Retraction Processing
|
|
@@ -1,16 +1,26 @@
|
|
|
1
1
|
# Primary Metadata Example
|
|
2
2
|
|
|
3
|
-
This example demonstrates the Primary Metadata feature in MD-LD, which provides immediate access to the main entity, type,
|
|
3
|
+
This example demonstrates the Primary Metadata feature in MD-LD, which provides immediate access to the main entity, type, label, comment described by a document.
|
|
4
4
|
|
|
5
|
-
## Primary Metadata
|
|
5
|
+
## Primary Metadata Quartet
|
|
6
6
|
|
|
7
7
|
MD-LD tracks three primary metadata fields during parsing to provide immediate document identity:
|
|
8
8
|
|
|
9
9
|
| Field | Source | Purpose |
|
|
10
10
|
|-------|--------|---------|
|
|
11
|
-
| **primarySubject** | First non-fragment `{=subject}` | Document identity |
|
|
12
|
-
| **primaryType** | First
|
|
13
|
-
| **primaryLabel** | First `
|
|
11
|
+
| **primarySubject** | First non-fragment `{=subject}` | Document identity (canonical append identity) |
|
|
12
|
+
| **primaryType** | First `rdf:type` declaration | Document category (semantic classification) |
|
|
13
|
+
| **primaryLabel** | First `rdfs:label` literal | Human-readable name (UI & display) |
|
|
14
|
+
| **primaryComment** | First `rdfs:comment` literal | Human-readable comment (UI & description) |
|
|
15
|
+
|
|
16
|
+
## Dual-Layer Architecture
|
|
17
|
+
|
|
18
|
+
MD-LD implements a **dual-layer architecture** that separates concerns cleanly:
|
|
19
|
+
|
|
20
|
+
| Layer | Field | Role | Use Cases |
|
|
21
|
+
| ------ | ------ | --------- | ---------- |
|
|
22
|
+
| **Canonical Identity** | `primarySubject` | Storage, routing, synchronization, append operations |
|
|
23
|
+
| **Semantic Surface** | `primary` object | UI rendering, indexing, navigation, agent orientation |
|
|
14
24
|
|
|
15
25
|
## What is a Primary Subject?
|
|
16
26
|
|
|
@@ -20,10 +30,28 @@ The Primary Subject is the first non-fragment subject declaration (`{=IRI}`) in
|
|
|
20
30
|
|
|
21
31
|
The Primary Type is the first `rdf:type` declaration associated with the Primary Subject. It provides a way to identify the type of the main entity described by a document.
|
|
22
32
|
|
|
33
|
+
### 1. First Type Declaration Wins
|
|
34
|
+
|
|
35
|
+
```markdown
|
|
36
|
+
# Person {=my:alice .prov:Person .schema:Person}
|
|
37
|
+
[Details] {label}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`primaryType` captures the **first rdf:type assertion emitted while current subject == primarySubject**. This is parser-precise and avoids ambiguity with later type declarations for other entities.
|
|
41
|
+
|
|
23
42
|
## What is a Primary Label?
|
|
24
43
|
|
|
25
44
|
The Primary Label is the first `rdfs:label` literal associated with the Primary Subject. It provides a human-readable name for the main entity described by a document.
|
|
26
45
|
|
|
46
|
+
### 2. First Label Declaration Wins
|
|
47
|
+
|
|
48
|
+
```markdown
|
|
49
|
+
# Person {=my:alice .prov:Person label}
|
|
50
|
+
[Alice Smith] {rdfs:label}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`primaryLabel` captures the **first emitted rdfs:label literal while current subject == primarySubject**. This ensures the label is associated with the primary subject, not other entities in the document.
|
|
54
|
+
|
|
27
55
|
## Example Document
|
|
28
56
|
|
|
29
57
|
```markdown
|
|
@@ -53,13 +81,17 @@ const md = `[ex] <tag:alice@example.org,2026:articles/>
|
|
|
53
81
|
|
|
54
82
|
const result = parse({ text: md });
|
|
55
83
|
|
|
84
|
+
// Canonical append identity
|
|
56
85
|
console.log('Primary Subject:', result.primarySubject);
|
|
57
|
-
|
|
58
|
-
console.log('Primary
|
|
86
|
+
// Semantic surface descriptor
|
|
87
|
+
console.log('Primary Object:', result.primary);
|
|
59
88
|
// Output:
|
|
60
89
|
// Primary Subject: tag:alice@example.org,2026:articles/understanding-primary-subject
|
|
61
|
-
// Primary
|
|
62
|
-
//
|
|
90
|
+
// Primary Object: {
|
|
91
|
+
// subject: 'tag:alice@example.org,2026:articles/understanding-primary-subject',
|
|
92
|
+
// type: 'http://schema.org/Article',
|
|
93
|
+
// label: 'Understanding Primary Subjects'
|
|
94
|
+
// }
|
|
63
95
|
```
|
|
64
96
|
|
|
65
97
|
## Key Behaviors
|
|
@@ -115,8 +147,16 @@ const doc2 = `[ex] <http://example.org/>
|
|
|
115
147
|
|
|
116
148
|
const result = merge([doc1, doc2], { context: { ex: 'http://example.org/' } });
|
|
117
149
|
|
|
118
|
-
|
|
119
|
-
|
|
150
|
+
// Canonical append identities
|
|
151
|
+
console.log('Primary Subjects:', result.primarySubjects);
|
|
152
|
+
// Semantic surface descriptors
|
|
153
|
+
console.log('Primary Objects:', result.primary);
|
|
154
|
+
// Output:
|
|
155
|
+
// Primary Subjects: ['http://example.org/doc1', 'http://example.org/doc2']
|
|
156
|
+
// Primary Objects: [
|
|
157
|
+
// { subject: 'http://example.org/doc1', type: 'http://schema.org/Article', label: 'Document 1' },
|
|
158
|
+
// { subject: 'http://example.org/doc2', type: 'http://schema.org/Article', label: 'Document 2' }
|
|
159
|
+
// ]
|
|
120
160
|
```
|
|
121
161
|
|
|
122
162
|
## Use Cases
|
|
@@ -206,13 +246,18 @@ const doc1 = `[blog] <https://example.com/blog/>
|
|
|
206
246
|
[Hello World] {schema:headline}`;
|
|
207
247
|
|
|
208
248
|
const result1 = parse({ text: doc1, context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
|
|
249
|
+
|
|
250
|
+
// Canonical append identity
|
|
209
251
|
console.log('Primary Subject:', result1.primarySubject);
|
|
210
|
-
|
|
211
|
-
console.log('Primary
|
|
252
|
+
// Semantic surface descriptor
|
|
253
|
+
console.log('Primary Object:', result1.primary);
|
|
212
254
|
// Output:
|
|
213
255
|
// Primary Subject: https://example.com/blog/post1
|
|
214
|
-
// Primary
|
|
215
|
-
//
|
|
256
|
+
// Primary Object: {
|
|
257
|
+
// subject: 'https://example.com/blog/post1',
|
|
258
|
+
// type: 'http://schema.org/BlogPosting',
|
|
259
|
+
// label: 'My First Post'
|
|
260
|
+
// }
|
|
216
261
|
|
|
217
262
|
// Multiple documents
|
|
218
263
|
const doc2 = `[blog] <https://example.com/blog/>
|
|
@@ -221,8 +266,16 @@ const doc2 = `[blog] <https://example.com/blog/>
|
|
|
221
266
|
|
|
222
267
|
const merged = merge([doc1, doc2], { context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
|
|
223
268
|
|
|
224
|
-
|
|
225
|
-
|
|
269
|
+
// Canonical append identities
|
|
270
|
+
console.log('Primary Subjects:', merged.primarySubjects);
|
|
271
|
+
// Semantic surface descriptors
|
|
272
|
+
console.log('Primary Objects:', merged.primary);
|
|
273
|
+
// Output:
|
|
274
|
+
// Primary Subjects: ['https://example.com/blog/post1', 'https://example.com/blog/post2']
|
|
275
|
+
// Primary Objects: [
|
|
276
|
+
// { subject: 'https://example.com/blog/post1', type: 'http://schema.org/BlogPosting', label: 'My First Post' },
|
|
277
|
+
// { subject: 'https://example.com/blog/post2', type: 'http://schema.org/BlogPosting', label: 'My Second Post' }
|
|
278
|
+
// ]
|
|
226
279
|
```
|
|
227
280
|
|
|
228
281
|
## Document Identity Trio
|
|
@@ -232,19 +285,42 @@ The primary metadata trio provides sufficient document/append stream identity fo
|
|
|
232
285
|
```javascript
|
|
233
286
|
// Nostr integration example
|
|
234
287
|
const nostrTags = [
|
|
235
|
-
['s', result.primarySubject],
|
|
236
|
-
['t', result.
|
|
237
|
-
['d', result.
|
|
288
|
+
['s', result.primarySubject], // subject addressing (canonical)
|
|
289
|
+
['t', result.primary.type], // type filtering
|
|
290
|
+
['d', result.primary.label] // display identifier
|
|
238
291
|
];
|
|
239
292
|
|
|
240
293
|
// Document fingerprint
|
|
241
294
|
const fingerprint = {
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
label: result.primaryLabel // Human-readable name
|
|
295
|
+
canonical: result.primarySubject, // What the document is about (append identity)
|
|
296
|
+
semantic: result.primary // How to present and index the document
|
|
245
297
|
};
|
|
246
298
|
```
|
|
247
299
|
|
|
300
|
+
## Primary Metadata is Parser-Level Metadata
|
|
301
|
+
|
|
302
|
+
**Important**: Primary metadata is derived parser state and does not introduce additional RDF triples or semantic entailments. It describes document intent, not graph semantics.
|
|
303
|
+
|
|
304
|
+
### Key Distinctions
|
|
305
|
+
|
|
306
|
+
| Aspect | Primary Metadata | RDF Semantics |
|
|
307
|
+
|---------|------------------|----------------|
|
|
308
|
+
| **Source** | Parser extraction rules | Triple patterns |
|
|
309
|
+
| **Scope** | Document-level intent | Graph-level relationships |
|
|
310
|
+
| **Purpose** | Routing, UI, indexing | Reasoning, inference |
|
|
311
|
+
| **Stability** | Deterministic extraction | Dynamic inference |
|
|
312
|
+
|
|
313
|
+
### Stability Guarantees
|
|
314
|
+
|
|
315
|
+
`primarySubject` is **stable under rewrite() operations that preserve extracted quads**. This means:
|
|
316
|
+
|
|
317
|
+
- Append routing remains consistent across document updates
|
|
318
|
+
- Synchronization identity is preserved during merges
|
|
319
|
+
- File mapping stays stable through rewrite operations
|
|
320
|
+
- Index references remain valid
|
|
321
|
+
|
|
322
|
+
This stability is crucial for distributed systems and local-first architectures.
|
|
323
|
+
|
|
248
324
|
## Specification
|
|
249
325
|
|
|
250
326
|
For complete details on Primary Subject semantics, see the [MD-LD Specification](../spec/Spec.md#17-primary-subject).
|