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.
Files changed (3) hide show
  1. package/README.md +169 -63
  2. package/dist/index.js +1 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,12 +1,21 @@
1
1
  # MD-LD
2
2
 
3
- **Markdown-Linked Data** — Human-friendly knowledge graph authoring.
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
- Write semantic data in natural Markdown, parse to RDF quads, build deterministic state machines.
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
  [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
8
8
 
9
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
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] <http://example.org/>
37
+ [ex] <tag:ame@example.com,2026:>
29
38
 
30
- # Document {=ex:doc .Article label}
39
+ # Alice {=ex:alice .prov:Person label}
31
40
 
32
- [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
33
- [Smith] {ex:lastName}
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
- - **Alice** {+alice:alice ?alice:attendee label}
94
- - **Bob** {+alice:bob ?alice:attendee label}
105
+ **Alice** {+alice:alice ?alice:attendee label}
106
+ **Bob** {+alice:bob ?alice:attendee label}
95
107
 
96
108
  Action items:
97
- - **Review proposal** {+alice:task-1 ?alice:actionItem label}
109
+ **Review proposal** {+alice:task-1 ?alice:actionItem label}
98
110
  ```
99
111
 
100
112
  #### Developer Documentation
101
113
  ```markdown
102
- # API Endpoint {=api:/users/:id .api:Endpoint}
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
- # Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
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
- [Semantic Web] {label}
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
- # Understanding MD-LD {=blog:post-mdld .blog:Post}
133
+ [blog] <tag:justin@example.org,2026:>
134
+ # Understanding MD-LD {=blog:post-mdld .blog:Post label}
120
135
 
121
- [MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown.
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
- ```javascript
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 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
176
- const result = parse('[ex] <http://example.org/>\n\n# Hello {=ex:hello label}');
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
- **Bundle size:** 84KB unminified, 19KB gzipped
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
- ## Apollo 11 {=ex:apollo11 .SpaceMission .Event}
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
- # Update value
241
- [Person] {=ex:person}
242
- [Alice] {-ex:name}
243
- [Bob] {ex:name}
244
-
245
- # Remove triple
246
- [Person] {=ex:person}
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, 84KB unminified (19KB gzipped)
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
- ## 📚 Additional Resources
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
- - **[Documentation](./docs/index.md)** — Complete guides and references
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 === RDFS_TYPE && object.termType === "NamedNode") ensure(object.value).push(quad);
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.2",
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",