mdld-parse 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +169 -63
- package/dist/index.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,21 @@
|
|
|
1
1
|
# MD-LD
|
|
2
2
|
|
|
3
|
-
**Markdown-Linked Data** —
|
|
3
|
+
**Markdown-Linked Data** — Write RDF knowledge graphs as plain Markdown. Parse to quads, generate back, merge documents. Zero dependencies, round-trip safe.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Unlike Turtle, JSON-LD, or RDF/XML, MD-LD embeds semantic annotations directly into natural Markdown text. A Markdown file becomes a knowledge graph — readable by humans and machines simultaneously.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/mdld-parse)
|
|
8
8
|
|
|
9
|
-
[
|
|
9
|
+
[Homepage](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
## 📚 Documentation Hub
|
|
13
|
+
|
|
14
|
+
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
15
|
+
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
16
|
+
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
17
|
+
- **📚 [Grammar](./grammar/index.md)** — EBNF grammar specification
|
|
18
|
+
- **🧩 [Ontologies](./ontologies/index.md)** — W3C and related standard ontologies used in RDF
|
|
10
19
|
|
|
11
20
|
## 🎯 What is MD-LD?
|
|
12
21
|
|
|
@@ -25,16 +34,17 @@ Human text → Graph immediately
|
|
|
25
34
|
**Core value:** Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.
|
|
26
35
|
|
|
27
36
|
```markdown
|
|
28
|
-
[ex] <
|
|
37
|
+
[ex] <tag:ame@example.com,2026:>
|
|
29
38
|
|
|
30
|
-
#
|
|
39
|
+
# Alice {=ex:alice .prov:Person label}
|
|
31
40
|
|
|
32
|
-
[Alice] {
|
|
33
|
-
[
|
|
41
|
+
[Alice Smith] {ex:fullName}
|
|
42
|
+
[alice@example.com] {ex:email}
|
|
34
43
|
```
|
|
35
44
|
|
|
36
45
|
**Generates RDF quads** that work with n3.js, rdflib, and any RDF/JS-compatible library.
|
|
37
46
|
|
|
47
|
+
|
|
38
48
|
## 🚀 Quick Start
|
|
39
49
|
|
|
40
50
|
```bash
|
|
@@ -74,12 +84,14 @@ Users cannot access the graph directly. Semantics are hidden. Data is locked in
|
|
|
74
84
|
MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
|
|
75
85
|
|
|
76
86
|
**Key benefits:**
|
|
87
|
+
|
|
77
88
|
- **Graph sovereignty** — You own text, graph, provenance, execution, history
|
|
78
89
|
- **No central platform required** — Works offline, in browsers, on servers
|
|
79
90
|
- **Universal semantic substrate** — Agents can read, reason, write, execute, validate
|
|
80
91
|
- **Continuous semantic narrative** — Unifies chat, tasks, notes, emails, calendar, files
|
|
81
92
|
- **Native time dimension** — Every action, statement, correction becomes part of the graph
|
|
82
93
|
- **Decentralized authority** — RFC 4151 tag: URIs enable self-sovereign identity without central registries
|
|
94
|
+
- **Text-native agent memory** - LLM Agent memory substrate in plain text — parse context, write knowledge, merge with other agents, all as Markdown files. No database required.
|
|
83
95
|
|
|
84
96
|
### Real-World Applications
|
|
85
97
|
|
|
@@ -87,47 +99,43 @@ MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes g
|
|
|
87
99
|
```markdown
|
|
88
100
|
[alice] <tag:alice@example.com,2026:>
|
|
89
101
|
|
|
90
|
-
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
|
|
102
|
+
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting label}
|
|
91
103
|
|
|
92
104
|
Attendees:
|
|
93
|
-
|
|
94
|
-
|
|
105
|
+
**Alice** {+alice:alice ?alice:attendee label}
|
|
106
|
+
**Bob** {+alice:bob ?alice:attendee label}
|
|
95
107
|
|
|
96
108
|
Action items:
|
|
97
|
-
|
|
109
|
+
**Review proposal** {+alice:task-1 ?alice:actionItem label}
|
|
98
110
|
```
|
|
99
111
|
|
|
100
112
|
#### Developer Documentation
|
|
101
113
|
```markdown
|
|
102
|
-
|
|
114
|
+
[api] <tag:brian@example.org,2026:app/api/>
|
|
115
|
+
# Get User by ID {=api:/users/:id .api:Endpoint label}
|
|
103
116
|
|
|
104
|
-
[GET] {api:method}
|
|
105
|
-
[/users/:id] {api:path}
|
|
117
|
+
Method: [GET] {+api:methods/GET ?api:method}
|
|
118
|
+
Path: [/users/:id] {api:path}
|
|
119
|
+
Status: [OK] {api:status}
|
|
106
120
|
```
|
|
107
121
|
|
|
108
122
|
#### Academic Research
|
|
109
123
|
```markdown
|
|
110
|
-
|
|
124
|
+
[alice] <tag:alice@example.org,2026:>
|
|
125
|
+
# Semantic Web {=alice:research/paper-semantic-markdown .alice:ScholarlyArticle label}
|
|
126
|
+
Is part of [semantic research] {+alice:research/semantic !member}
|
|
111
127
|
|
|
112
|
-
[
|
|
113
|
-
[Alice Johnson] {=alice:alice-johnson ?alice:author}
|
|
114
|
-
[2024-01] {alice:datePublished ^^xsd:gYear}
|
|
128
|
+
Authored by [Alice Johnson] {+alice:alice-johnson ?alice:author} on [2026-08-12] {alice:datePublished ^^xsd:date}.
|
|
115
129
|
```
|
|
116
130
|
|
|
117
131
|
#### Content Management
|
|
118
132
|
```markdown
|
|
119
|
-
|
|
133
|
+
[blog] <tag:justin@example.org,2026:>
|
|
134
|
+
# Understanding MD-LD {=blog:post-mdld .blog:Post label}
|
|
120
135
|
|
|
121
|
-
[MD-LD] {blog:emphasized
|
|
136
|
+
[MD-LD] {blog:emphasized} allows you to embed RDF directly in Markdown.
|
|
122
137
|
```
|
|
123
138
|
|
|
124
|
-
## 📚 Documentation Hub
|
|
125
|
-
|
|
126
|
-
- **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
|
|
127
|
-
- **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
|
|
128
|
-
- **📋 [Specification](./spec/index.md)** — Formal specification and test suite
|
|
129
|
-
- **🔄 [Diff Generation](./docs/diff.md)** — Automatic diff document generation for CRDT workflows
|
|
130
|
-
|
|
131
139
|
## ✨ Core Features
|
|
132
140
|
|
|
133
141
|
- **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
|
|
@@ -144,40 +152,92 @@ Action items:
|
|
|
144
152
|
- **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
|
|
145
153
|
- **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
|
|
146
154
|
|
|
155
|
+
**Bundle size:** 86KB unminified, 20KB gzipped
|
|
156
|
+
|
|
147
157
|
## 📦 Installation
|
|
148
158
|
|
|
149
159
|
### Node.js
|
|
150
160
|
|
|
151
161
|
```bash
|
|
152
162
|
pnpm install mdld-parse
|
|
163
|
+
node -e "
|
|
164
|
+
import { parse } from 'mdld-parse';
|
|
165
|
+
console.log(parse({ text: '# Test {=tag:test@example.org,2026:index .prov:Entity label}' }));
|
|
166
|
+
"
|
|
153
167
|
```
|
|
154
168
|
|
|
155
|
-
|
|
156
|
-
import { parse, generate, merge } from 'mdld-parse';
|
|
157
|
-
|
|
158
|
-
const mdld = `[ex] <http://example.org/>
|
|
159
|
-
|
|
160
|
-
# Document {=ex:doc .Article label}
|
|
161
|
-
|
|
162
|
-
[Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
|
|
163
|
-
[Smith] {ex:lastName}`;
|
|
164
|
-
|
|
165
|
-
const result = parse({ text: mdld });
|
|
166
|
-
console.log(result.quads); // RDF/JS quads
|
|
167
|
-
console.log(result.primary); // { subject, type, label, comment }
|
|
168
|
-
console.log(result.statements); // Elevated statements
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### Browser (ES Modules)
|
|
169
|
+
### Browser ESM (importmap)
|
|
172
170
|
|
|
173
171
|
```html
|
|
172
|
+
<script type="importmap">
|
|
173
|
+
{
|
|
174
|
+
"imports": {
|
|
175
|
+
"mdld-parse": "https://cdn.jsdelivr.net/npm/mdld-parse/+esm",
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
</script>
|
|
174
179
|
<script type="module">
|
|
175
|
-
import { parse } from '
|
|
176
|
-
const result = parse('[ex] <
|
|
180
|
+
import { parse } from 'mdld-parse';
|
|
181
|
+
const result = parse('[ex] <tag:my@example.com,2026:test/>\n\n# Hello {=ex:init .prov:Activity label}');
|
|
177
182
|
</script>
|
|
178
183
|
```
|
|
179
184
|
|
|
180
|
-
|
|
185
|
+
### Example use in browser console
|
|
186
|
+
|
|
187
|
+
You can copy and paste this code into your browser console to see the list of tasks as an easy to render JSON object.
|
|
188
|
+
|
|
189
|
+
```javascript
|
|
190
|
+
const mdld = await import('https://cdn.jsdelivr.net/npm/mdld-parse/+esm')
|
|
191
|
+
|
|
192
|
+
const text = `[my] <tag:alice@example.org:>
|
|
193
|
+
|
|
194
|
+
# Tasks {=my:tasks .prov:Collection label}
|
|
195
|
+
|
|
196
|
+
## Task 1 {=my:tasks/1 .prov:Activity label}
|
|
197
|
+
One of my [urgent] {my:tasks/status} [tasks] {+my:tasks !prov:hadMember}
|
|
198
|
+
> Explore deeper the concept of a triple in RDF {comment}
|
|
199
|
+
|
|
200
|
+
## Task 2 {=my:tasks/2 .prov:Activity label}
|
|
201
|
+
One of my [tasks] {+my:tasks !prov:hadMember}
|
|
202
|
+
> Start building knowledge graphs {comment}
|
|
203
|
+
`;
|
|
204
|
+
|
|
205
|
+
const result = parse({ text });
|
|
206
|
+
|
|
207
|
+
function extractByType (quads, type) {
|
|
208
|
+
return Object.values(
|
|
209
|
+
quads.reduce((acc, q) => {
|
|
210
|
+
const s = q.subject.value;
|
|
211
|
+
const key = q.predicate.value.split(/[#/]/).pop();
|
|
212
|
+
|
|
213
|
+
(acc[s] ??= { iri: s })[key] = q.object.value;
|
|
214
|
+
|
|
215
|
+
return acc;
|
|
216
|
+
}, {})
|
|
217
|
+
)
|
|
218
|
+
.filter(x => x.type === type)
|
|
219
|
+
.map(({ type, ...x }) => x);
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
const tasks = extractByType(result.quads,"http://www.w3.org/ns/prov#Activity")
|
|
223
|
+
|
|
224
|
+
console.log(tasks);
|
|
225
|
+
/*
|
|
226
|
+
[
|
|
227
|
+
{
|
|
228
|
+
"iri": "tag:alice@example.org:tasks/1",
|
|
229
|
+
"label": "Task 1",
|
|
230
|
+
"status": "urgent",
|
|
231
|
+
"comment": "Explore deeper the concept of a triple in RDF"
|
|
232
|
+
},
|
|
233
|
+
{
|
|
234
|
+
"iri": "tag:alice@example.org:tasks/2",
|
|
235
|
+
"label": "Task 2",
|
|
236
|
+
"comment": "Start building knowledge graphs"
|
|
237
|
+
}
|
|
238
|
+
]
|
|
239
|
+
*/
|
|
240
|
+
```
|
|
181
241
|
|
|
182
242
|
## 🧠 Semantic Model
|
|
183
243
|
|
|
@@ -200,20 +260,29 @@ Each predicate form determines the graph edge:
|
|
|
200
260
|
## 🎨 Syntax Quick Reference
|
|
201
261
|
|
|
202
262
|
### Subject Declaration
|
|
263
|
+
|
|
203
264
|
Set current subject (emits no quads):
|
|
265
|
+
|
|
204
266
|
```markdown
|
|
267
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
205
268
|
## Apollo 11 {=ex:apollo11}
|
|
206
269
|
```
|
|
207
270
|
|
|
208
271
|
### Type Declaration
|
|
272
|
+
|
|
209
273
|
Emit `rdf:type` triple:
|
|
274
|
+
|
|
210
275
|
```markdown
|
|
211
|
-
|
|
276
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
277
|
+
## Apollo 11 {=ex:apollo11 .ex:SpaceMission .prov:Entity}
|
|
212
278
|
```
|
|
213
279
|
|
|
214
280
|
### Literal Properties
|
|
281
|
+
|
|
215
282
|
Inline value carriers emit literal properties:
|
|
283
|
+
|
|
216
284
|
```markdown
|
|
285
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
217
286
|
# Mission {=ex:apollo11}
|
|
218
287
|
[Neil Armstrong] {ex:commander}
|
|
219
288
|
[1969] {ex:year ^^xsd:gYear}
|
|
@@ -221,32 +290,53 @@ Inline value carriers emit literal properties:
|
|
|
221
290
|
```
|
|
222
291
|
|
|
223
292
|
### Object Properties
|
|
293
|
+
|
|
224
294
|
Links create relationships (use `?` prefix):
|
|
295
|
+
|
|
225
296
|
```markdown
|
|
297
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
226
298
|
# Mission {=ex:apollo11}
|
|
227
299
|
[NASA] {=ex:nasa ?ex:organizer}
|
|
228
300
|
```
|
|
229
301
|
|
|
230
302
|
### Resource Declaration
|
|
303
|
+
|
|
231
304
|
Declare resources inline with `{+iri}`:
|
|
305
|
+
|
|
232
306
|
```markdown
|
|
307
|
+
[ex] <tag:nasa@example.org,2026:>
|
|
233
308
|
# Mission {=ex:apollo11}
|
|
234
309
|
[Neil Armstrong] {+ex:armstrong ?ex:commander .Person}
|
|
235
310
|
```
|
|
236
311
|
|
|
237
312
|
### Diff Authoring (Polarity)
|
|
313
|
+
|
|
238
314
|
Use `+` and `-` for retractions:
|
|
315
|
+
|
|
316
|
+
```markdown
|
|
317
|
+
[ex] <tag:carol@example.org,2026:>
|
|
318
|
+
|
|
319
|
+
New student [Alice] {=ex:new-student .prov:Person ex:name} is our [class] {+ex:my-class !member}. I think she might know [Bob] {+ex:bob ?ex:knows}.
|
|
320
|
+
|
|
321
|
+
**Correction:** [Her] {=ex:new-student} name is not [Alice] {-ex:name}, it's [Ellie] {ex:name}.
|
|
322
|
+
|
|
323
|
+
**Correction:** I asked her directly - no, she doesn't know [him] {+ex:bob -?ex:knows}.
|
|
324
|
+
|
|
325
|
+
**IRI replacement:** Let's create a proper [Class] {=ex:my-class} record for [Ellie] {+ex:Ellie .prov:Person ex:name label ?member} instead of temporary [Ellie] {+ex:new-student -.prov:Person -ex:name -?member} record created earlier.
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
After `generate(parse({text}))` would look like this:
|
|
239
329
|
```markdown
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
[
|
|
244
|
-
|
|
245
|
-
#
|
|
246
|
-
[
|
|
247
|
-
[Alice] {-ex:friend}
|
|
330
|
+
[ex] <tag:carol@example.org,2026:>
|
|
331
|
+
|
|
332
|
+
# Ellie {=ex:Ellie .prov:Person label}
|
|
333
|
+
[Ellie] {ex:name}
|
|
334
|
+
|
|
335
|
+
# my-class {=ex:my-class}
|
|
336
|
+
[ex:Ellie] {+ex:Ellie ?member}
|
|
248
337
|
```
|
|
249
338
|
|
|
339
|
+
|
|
250
340
|
## 🔧 API Reference
|
|
251
341
|
|
|
252
342
|
### `parse({ text, context, dataFactory, graph })`
|
|
@@ -372,7 +462,7 @@ import {
|
|
|
372
462
|
## 🏗️ Architecture
|
|
373
463
|
|
|
374
464
|
### Design Principles
|
|
375
|
-
- **Zero dependencies** — Pure JavaScript,
|
|
465
|
+
- **Zero dependencies** — Pure JavaScript, 85KB unminified (20KB gzipped)
|
|
376
466
|
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
377
467
|
- **Character-based tokenization** — 20-28% faster than regex-based approaches
|
|
378
468
|
- **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
|
|
@@ -428,10 +518,26 @@ Comprehensive test suite covering:
|
|
|
428
518
|
- Round-trip parse/generate cycles
|
|
429
519
|
- Origin tracking and provenance
|
|
430
520
|
|
|
431
|
-
##
|
|
521
|
+
## Governance
|
|
522
|
+
|
|
523
|
+
MD-LD is a craft project. Its coherence comes from a single evolving understanding of how semantic text should work — not from consensus, but from sustained attention to the same problem over time.
|
|
524
|
+
|
|
525
|
+
This means:
|
|
526
|
+
|
|
527
|
+
- Decisions are made by the steward, informed by discussion and use
|
|
528
|
+
- The project prioritizes conceptual integrity over inclusiveness
|
|
529
|
+
- Contributions that align with the model are welcomed and incorporated
|
|
530
|
+
- Contributions that expand scope without deepening coherence are respectfully declined
|
|
531
|
+
- The spec will not grow features to attract users — it will grow depth to serve understanding
|
|
532
|
+
|
|
533
|
+
## Licensing
|
|
534
|
+
|
|
535
|
+
MD-LD is published as copyrighted source material. No open-source license applies.
|
|
536
|
+
|
|
537
|
+
Governance and licensing are determined by the author as the project evolves.
|
|
538
|
+
|
|
539
|
+
Individuals and small groups are welcome to study, use, and build with MD-LD.
|
|
540
|
+
|
|
541
|
+
Organizations that need a formal license grant are invited to contact the author.
|
|
432
542
|
|
|
433
|
-
|
|
434
|
-
- **[Specification](./spec/index.md)** — Formal specification
|
|
435
|
-
- **[Examples](./examples/index.md)** — Real-world examples
|
|
436
|
-
- **[Grammar](./grammar/mdld.ebnf)** — EBNF grammar specification
|
|
437
|
-
- **[VS Code Extension](https://marketplace.visualstudio.com/)** — Syntax highlighting (coming soon)
|
|
543
|
+
All rights remain reserved.
|
package/dist/index.js
CHANGED
|
@@ -1837,7 +1837,7 @@ function groupQuadsByNode(quads) {
|
|
|
1837
1837
|
else reverseIndex.set(objectValue, [quad]);
|
|
1838
1838
|
}
|
|
1839
1839
|
ensure(predicate.value).push(quad);
|
|
1840
|
-
if (predicate.value ===
|
|
1840
|
+
if (predicate.value === "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" && object.termType === "NamedNode") ensure(object.value).push(quad);
|
|
1841
1841
|
if (object.termType === "Literal" && object.datatype) ensure(object.datatype.value || object.datatype).push(quad);
|
|
1842
1842
|
}
|
|
1843
1843
|
return {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdld-parse",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.4",
|
|
4
4
|
"description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"scripts": {
|
|
15
15
|
"test": "node tests/index.js",
|
|
16
16
|
"dev": "vite dev",
|
|
17
|
-
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
|
|
17
|
+
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md && cp -r docs.html dist/docs.html && cp -r demo/ dist/demo/"
|
|
18
18
|
},
|
|
19
19
|
"keywords": [
|
|
20
20
|
"mdld",
|