mdld-parse 0.9.9 → 1.0.0
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 +242 -330
- package/dist/index.js +1793 -1336
- package/package.json +4 -4
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +0 -1
- package/dist/README.md +0 -500
- package/dist/docs/API.md +0 -435
- package/dist/docs/Architecture.md +0 -190
- package/dist/docs/Guide.md +0 -816
- package/dist/docs/LLM-MDLD-Inducer.md +0 -550
- package/dist/docs/LiterateRDF.md +0 -472
- package/dist/docs/Parser.md +0 -720
- package/dist/docs/Performance.md +0 -238
- package/dist/docs/Spec-render.md +0 -1439
- package/dist/docs/Subject.md +0 -180
- package/dist/docs/Syntax.md +0 -463
- package/dist/docs/TodoList.md +0 -215
- package/dist/docs/Use-Cases.md +0 -354
- package/dist/docs/guide-m.md +0 -56
- package/dist/docs/index.html +0 -108
- package/dist/docs/index.md +0 -56
- package/dist/docs/one-page.md +0 -322
- package/dist/docs/origin.md +0 -460
- package/dist/docs/polarity.md +0 -586
- package/dist/docs/primary-subject.md +0 -326
- package/dist/docs/statements.md +0 -226
- package/dist/docs/tokenization-performance-report.md +0 -164
- package/dist/examples/Cookbook.md +0 -32
- package/dist/examples/Status-SHACL.md +0 -31
- package/dist/examples/demo/index.md +0 -35
- package/dist/examples/demo/journal.md +0 -58
- package/dist/examples/demo/minimal.md +0 -23
- package/dist/examples/demo/project.md +0 -84
- package/dist/examples/demo/prov.md +0 -107
- package/dist/examples/demo/rdf.md +0 -69
- package/dist/examples/demo/recipe.md +0 -50
- package/dist/examples/demo/research.md +0 -84
- package/dist/examples/demo/shacl.md +0 -161
- package/dist/examples/demo/space-mission.md +0 -58
- package/dist/examples/demo/tasks.md +0 -175
- package/dist/examples/demo/xsd.md +0 -91
- package/dist/examples/dogfood.md +0 -288
- package/dist/examples/few-shot.md +0 -309
- package/dist/examples/graph/rdf-graph.html +0 -473
- package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
- package/dist/examples/index.md +0 -45
- package/dist/examples/llm-time-workflow.md +0 -173
- package/dist/examples/statements.md +0 -43
- package/dist/examples/workflow.md +0 -150
- package/dist/index.html +0 -3049
- package/dist/logo.svg +0 -7
- package/dist/spec/Spec-compact.md +0 -368
- package/dist/spec/Spec-ultra.md +0 -232
- package/dist/spec/Spec.md +0 -1116
- package/dist/spec/index.md +0 -46
package/README.md
CHANGED
|
@@ -1,10 +1,39 @@
|
|
|
1
1
|
# MD-LD
|
|
2
2
|
|
|
3
|
-
**Markdown-Linked Data
|
|
3
|
+
**Markdown-Linked Data** — Human-friendly knowledge graph authoring.
|
|
4
|
+
|
|
5
|
+
Write semantic data in natural Markdown, parse to RDF quads, build deterministic state machines.
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/mdld-parse)
|
|
6
8
|
|
|
7
|
-
[Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
|
|
9
|
+
[Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
|
|
10
|
+
|
|
11
|
+
## 🎯 What is MD-LD?
|
|
12
|
+
|
|
13
|
+
MD-LD is not just another RDF syntax. It's a **universal semantic writing interface** that removes the intermediary between human text and machine-readable graphs.
|
|
14
|
+
|
|
15
|
+
Traditional systems require:
|
|
16
|
+
```
|
|
17
|
+
Human → UI → App Logic → Hidden Database → APIs → Exports
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
MD-LD enables:
|
|
21
|
+
```
|
|
22
|
+
Human text → Graph immediately
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**Core value:** Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.
|
|
26
|
+
|
|
27
|
+
```markdown
|
|
28
|
+
[ex] <http://example.org/>
|
|
29
|
+
|
|
30
|
+
# Document {=ex:doc .Article label}
|
|
31
|
+
|
|
32
|
+
[Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
|
|
33
|
+
[Smith] {ex:lastName}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Generates RDF quads** that work with n3.js, rdflib, and any RDF/JS-compatible library.
|
|
8
37
|
|
|
9
38
|
## 🚀 Quick Start
|
|
10
39
|
|
|
@@ -13,66 +42,106 @@ pnpm install mdld-parse
|
|
|
13
42
|
```
|
|
14
43
|
|
|
15
44
|
```javascript
|
|
16
|
-
import { parse } from 'mdld-parse';
|
|
45
|
+
import { parse, generate, merge } from 'mdld-parse';
|
|
17
46
|
|
|
18
|
-
|
|
19
|
-
|
|
47
|
+
// Parse MDLD to RDF quads
|
|
48
|
+
const result = parse({ text: mdldString });
|
|
49
|
+
console.log(result.quads); // RDF/JS quads
|
|
50
|
+
console.log(result.primary); // Primary metadata (subject, type, label, comment)
|
|
51
|
+
console.log(result.statements); // Elevated statements
|
|
52
|
+
console.log(result.origin); // Provenance tracking
|
|
20
53
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
console.log(result.quads);
|
|
27
|
-
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
28
|
-
// @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
|
|
29
|
-
// @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
30
|
-
// @prefix prov: <http://www.w3.org/ns/prov#>.
|
|
31
|
-
// @prefix ex: <http://example.org/>.
|
|
32
|
-
|
|
33
|
-
// ex:doc a ex:Article;
|
|
34
|
-
// rdfs:label "Document";
|
|
35
|
-
// ex:author ex:alice.
|
|
36
|
-
// ex:alice a prov:Person;
|
|
37
|
-
// rdfs:label "Alice";
|
|
38
|
-
// ex:firstName "Alice";
|
|
39
|
-
// ex:lastName "Smith".
|
|
54
|
+
// Generate MDLD from quads
|
|
55
|
+
const { text } = generate({ quads: result.quads });
|
|
56
|
+
|
|
57
|
+
// Merge multiple documents (CRDT-style)
|
|
58
|
+
const merged = merge([doc1, doc2, doc3]);
|
|
40
59
|
```
|
|
41
60
|
|
|
42
|
-
##
|
|
61
|
+
## 💡 Why MD-LD?
|
|
43
62
|
|
|
44
|
-
|
|
45
|
-
- **🎯 [Examples](./examples/index.md)** - Real-world MD-LD examples and use cases
|
|
46
|
-
- **📋 [Specification](./spec/index.md)** - Formal specification and test suite
|
|
63
|
+
### The Problem with Current Systems
|
|
47
64
|
|
|
48
|
-
|
|
65
|
+
Most software today uses graphs internally but hides them behind UIs:
|
|
66
|
+
- **Notion, Slack, Google Docs** — Human interfaces over hidden graphs
|
|
67
|
+
- **CRMs, task apps, note apps** — Proprietary data silos
|
|
68
|
+
- **Social networks** — Platform-controlled knowledge prisons
|
|
69
|
+
|
|
70
|
+
Users cannot access the graph directly. Semantics are hidden. Data is locked in products.
|
|
49
71
|
|
|
50
|
-
|
|
51
|
-
- **📍 Subject declarations** - `{=IRI}` and `{=#fragment}` for context setting
|
|
52
|
-
- **🎯 Object IRIs** - `{+IRI}` and `{+#fragment}` for temporary object declarations
|
|
53
|
-
- **🔄 Three predicate forms** - `p` (S→L), `?p` (S→O), `!p` (O→S)
|
|
54
|
-
- **🏷️ Type declarations** - `.Class` for rdf:type triples
|
|
55
|
-
- **📅 Datatypes & language** - `^^xsd:date` and `@en` support
|
|
56
|
-
- **🧩 Fragments** - Document structuring with `{=#fragment}`
|
|
57
|
-
- **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
|
|
58
|
-
- **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
|
|
59
|
-
- **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
|
|
60
|
-
- **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
|
|
72
|
+
### The MD-LD Solution
|
|
61
73
|
|
|
62
|
-
|
|
74
|
+
MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
|
|
63
75
|
|
|
64
|
-
|
|
76
|
+
**Key benefits:**
|
|
77
|
+
- **Graph sovereignty** — You own text, graph, provenance, execution, history
|
|
78
|
+
- **No central platform required** — Works offline, in browsers, on servers
|
|
79
|
+
- **Universal semantic substrate** — Agents can read, reason, write, execute, validate
|
|
80
|
+
- **Continuous semantic narrative** — Unifies chat, tasks, notes, emails, calendar, files
|
|
81
|
+
- **Native time dimension** — Every action, statement, correction becomes part of the graph
|
|
82
|
+
- **Decentralized authority** — RFC 4151 tag: URIs enable self-sovereign identity without central registries
|
|
65
83
|
|
|
84
|
+
### Real-World Applications
|
|
85
|
+
|
|
86
|
+
#### Personal Knowledge Management
|
|
66
87
|
```markdown
|
|
67
|
-
[
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
88
|
+
[alice] <tag:alice@example.com,2026:>
|
|
89
|
+
|
|
90
|
+
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
|
|
91
|
+
|
|
92
|
+
Attendees:
|
|
93
|
+
- **Alice** {+alice:alice ?alice:attendee label}
|
|
94
|
+
- **Bob** {+alice:bob ?alice:attendee label}
|
|
95
|
+
|
|
96
|
+
Action items:
|
|
97
|
+
- **Review proposal** {+alice:task-1 ?alice:actionItem label}
|
|
73
98
|
```
|
|
74
99
|
|
|
75
|
-
|
|
100
|
+
#### Developer Documentation
|
|
101
|
+
```markdown
|
|
102
|
+
# API Endpoint {=api:/users/:id .api:Endpoint}
|
|
103
|
+
|
|
104
|
+
[GET] {api:method}
|
|
105
|
+
[/users/:id] {api:path}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
#### Academic Research
|
|
109
|
+
```markdown
|
|
110
|
+
# Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
|
|
111
|
+
|
|
112
|
+
[Semantic Web] {label}
|
|
113
|
+
[Alice Johnson] {=alice:alice-johnson ?alice:author}
|
|
114
|
+
[2024-01] {alice:datePublished ^^xsd:gYear}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### Content Management
|
|
118
|
+
```markdown
|
|
119
|
+
# Understanding MD-LD {=blog:post-mdld .blog:Post}
|
|
120
|
+
|
|
121
|
+
[MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown.
|
|
122
|
+
```
|
|
123
|
+
|
|
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
|
+
## ✨ Core Features
|
|
132
|
+
|
|
133
|
+
- **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
|
|
134
|
+
- **📍 Subject declarations** — `{=IRI}` and `{=#fragment}` for context setting
|
|
135
|
+
- **🎯 Object IRIs** — `{+IRI}` and `{+#fragment}` for temporary object declarations
|
|
136
|
+
- **🔄 Three predicate forms** — `p` (S→L), `?p` (S→O), `!p` (O→S)
|
|
137
|
+
- **🏷️ Type declarations** — `.Class` for rdf:type triples
|
|
138
|
+
- **📅 Datatypes & language** — `^^xsd:date` and `@en` support
|
|
139
|
+
- **🧩 Fragments** — Document structuring with `{=#fragment}`
|
|
140
|
+
- **⚡ Polarity system** — Sophisticated diff authoring with `+` and `-` prefixes
|
|
141
|
+
- **📍 Origin tracking** — Complete provenance with lean quad-to-source mapping
|
|
142
|
+
- **🎯 Elevated statements** — Automatic rdf:Statement pattern detection
|
|
143
|
+
- **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
|
|
144
|
+
- **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
|
|
76
145
|
|
|
77
146
|
## 📦 Installation
|
|
78
147
|
|
|
@@ -83,20 +152,19 @@ pnpm install mdld-parse
|
|
|
83
152
|
```
|
|
84
153
|
|
|
85
154
|
```javascript
|
|
86
|
-
import { parse } from 'mdld-parse';
|
|
155
|
+
import { parse, generate, merge } from 'mdld-parse';
|
|
87
156
|
|
|
88
|
-
const
|
|
89
|
-
|
|
90
|
-
# Demo document {=ex:example/doc .prov:Entity label}
|
|
157
|
+
const mdld = `[ex] <http://example.org/>
|
|
91
158
|
|
|
92
|
-
|
|
93
|
-
[Alice] {+ex:alice ?ex:author .prov:Person label}
|
|
94
|
-
`;
|
|
159
|
+
# Document {=ex:doc .Article label}
|
|
95
160
|
|
|
96
|
-
|
|
161
|
+
[Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
|
|
162
|
+
[Smith] {ex:lastName}`;
|
|
97
163
|
|
|
98
|
-
|
|
99
|
-
// RDF/JS quads
|
|
164
|
+
const result = parse({ text: mdld });
|
|
165
|
+
console.log(result.quads); // RDF/JS quads
|
|
166
|
+
console.log(result.primary); // { subject, type, label, comment }
|
|
167
|
+
console.log(result.statements); // Elevated statements
|
|
100
168
|
```
|
|
101
169
|
|
|
102
170
|
### Browser (ES Modules)
|
|
@@ -104,11 +172,12 @@ console.log(result.quads);
|
|
|
104
172
|
```html
|
|
105
173
|
<script type="module">
|
|
106
174
|
import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
|
|
107
|
-
|
|
108
|
-
const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
|
|
175
|
+
const result = parse('[ex] <http://example.org/>\n\n# Hello {=ex:hello label}');
|
|
109
176
|
</script>
|
|
110
177
|
```
|
|
111
178
|
|
|
179
|
+
**Bundle size:** 84KB unminified, 19KB gzipped
|
|
180
|
+
|
|
112
181
|
## 🧠 Semantic Model
|
|
113
182
|
|
|
114
183
|
MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
|
|
@@ -117,7 +186,7 @@ MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
|
|
|
117
186
|
- **O** — object resource (IRI from link/image)
|
|
118
187
|
- **L** — literal value (string + optional datatype/language)
|
|
119
188
|
|
|
120
|
-
### Predicate Routing
|
|
189
|
+
### Predicate Routing
|
|
121
190
|
|
|
122
191
|
Each predicate form determines the graph edge:
|
|
123
192
|
|
|
@@ -127,23 +196,6 @@ Each predicate form determines the graph edge:
|
|
|
127
196
|
| `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
|
|
128
197
|
| `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
|
|
129
198
|
|
|
130
|
-
## 📍 Elevated Statements
|
|
131
|
-
|
|
132
|
-
MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
|
|
133
|
-
|
|
134
|
-
### Pattern Detection
|
|
135
|
-
|
|
136
|
-
When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, it automatically adds the corresponding SPO quad to the `statements` array:
|
|
137
|
-
|
|
138
|
-
```markdown
|
|
139
|
-
[ex] <http://example.org/>
|
|
140
|
-
|
|
141
|
-
## Elevated statement {=ex:stmt1 .rdf:Statement}
|
|
142
|
-
**Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
|
|
143
|
-
|
|
144
|
-
Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
|
|
145
|
-
```
|
|
146
|
-
|
|
147
199
|
## 🎨 Syntax Quick Reference
|
|
148
200
|
|
|
149
201
|
### Subject Declaration
|
|
@@ -152,19 +204,10 @@ Set current subject (emits no quads):
|
|
|
152
204
|
## Apollo 11 {=ex:apollo11}
|
|
153
205
|
```
|
|
154
206
|
|
|
155
|
-
### Fragment Syntax
|
|
156
|
-
Create fragment IRIs relative to current subject:
|
|
157
|
-
```markdown
|
|
158
|
-
# Document {=ex:document}
|
|
159
|
-
{=#summary}
|
|
160
|
-
[Content] {label}
|
|
161
|
-
```
|
|
162
|
-
Fragments replace any existing fragment and require a current subject.
|
|
163
|
-
|
|
164
207
|
### Type Declaration
|
|
165
208
|
Emit `rdf:type` triple:
|
|
166
209
|
```markdown
|
|
167
|
-
## Apollo 11 {=ex:apollo11 .
|
|
210
|
+
## Apollo 11 {=ex:apollo11 .SpaceMission .Event}
|
|
168
211
|
```
|
|
169
212
|
|
|
170
213
|
### Literal Properties
|
|
@@ -184,50 +227,47 @@ Links create relationships (use `?` prefix):
|
|
|
184
227
|
```
|
|
185
228
|
|
|
186
229
|
### Resource Declaration
|
|
187
|
-
Declare resources inline with `{
|
|
230
|
+
Declare resources inline with `{+iri}`:
|
|
188
231
|
```markdown
|
|
189
232
|
# Mission {=ex:apollo11}
|
|
190
|
-
[Neil Armstrong] {
|
|
233
|
+
[Neil Armstrong] {+ex:armstrong ?ex:commander .Person}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Diff Authoring (Polarity)
|
|
237
|
+
Use `+` and `-` for retractions:
|
|
238
|
+
```markdown
|
|
239
|
+
# Update value
|
|
240
|
+
[Person] {=ex:person}
|
|
241
|
+
[Alice] {-ex:name}
|
|
242
|
+
[Bob] {ex:name}
|
|
243
|
+
|
|
244
|
+
# Remove triple
|
|
245
|
+
[Person] {=ex:person}
|
|
246
|
+
[Alice] {-ex:friend}
|
|
191
247
|
```
|
|
192
248
|
|
|
193
249
|
## 🔧 API Reference
|
|
194
250
|
|
|
195
251
|
### `parse({ text, context, dataFactory, graph })`
|
|
196
252
|
|
|
197
|
-
Parse
|
|
253
|
+
Parse MDLD to RDF quads with lean origin tracking.
|
|
198
254
|
|
|
199
|
-
**Parameters
|
|
200
|
-
- `text` (string, required) —
|
|
201
|
-
- `context` (object, optional) — Prefix mappings
|
|
255
|
+
**Parameters:**
|
|
256
|
+
- `text` (string, required) — MDLD formatted text
|
|
257
|
+
- `context` (object, optional) — Prefix mappings
|
|
202
258
|
- `dataFactory` (object, optional) — Custom RDF/JS DataFactory
|
|
203
259
|
- `graph` (string, optional) — Named graph IRI
|
|
204
260
|
|
|
205
261
|
**Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
|
|
206
262
|
|
|
207
|
-
- `quads` —
|
|
208
|
-
- `remove` —
|
|
209
|
-
- `statements` —
|
|
210
|
-
- `origin` — Lean origin tracking
|
|
211
|
-
- `context` — Final context
|
|
263
|
+
- `quads` — RDF/JS Quads (final resolved graph state)
|
|
264
|
+
- `remove` — RDF/JS Quads (external retractions for diff workflows)
|
|
265
|
+
- `statements` — Elevated SPO quads from rdf:Statement patterns
|
|
266
|
+
- `origin` — Lean origin tracking for UI navigation
|
|
267
|
+
- `context` — Final context with prefixes
|
|
212
268
|
- `primarySubject` — String IRI or null (canonical append identity)
|
|
213
|
-
- `primary` —
|
|
214
|
-
- `md` — Clean Markdown with
|
|
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
|
-
```
|
|
269
|
+
- `primary` — Primary metadata quartet: `{ subject, type, label, comment }`
|
|
270
|
+
- `md` — Clean Markdown with annotations stripped
|
|
231
271
|
|
|
232
272
|
### `merge(docs, options)`
|
|
233
273
|
|
|
@@ -236,265 +276,137 @@ Merge multiple MDLD documents with diff polarity resolution.
|
|
|
236
276
|
**Parameters:**
|
|
237
277
|
- `docs` (array) — Array of markdown strings or ParseResult objects
|
|
238
278
|
- `options` (object, optional):
|
|
239
|
-
- `context` (object) — Prefix mappings
|
|
279
|
+
- `context` (object) — Prefix mappings
|
|
240
280
|
|
|
241
|
-
**Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
|
|
281
|
+
**Returns:** `{ quads, remove, statements, origin, context, primarySubjects, primary }`
|
|
242
282
|
|
|
243
|
-
- `quads` —
|
|
244
|
-
- `remove` —
|
|
283
|
+
- `quads` — RDF/JS Quads (final resolved graph state)
|
|
284
|
+
- `remove` — RDF/JS Quads (external retractions)
|
|
285
|
+
- `statements` — Elevated statements from all documents
|
|
245
286
|
- `origin` — Merge origin with document tracking
|
|
246
|
-
- `context` — Final context
|
|
247
|
-
- `primarySubjects` — Array of string IRIs (canonical
|
|
248
|
-
- `primary` — Array of primary objects
|
|
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
|
-
|
|
269
|
-
|
|
270
|
-
### `generate({ quads, context, primarySubject })`
|
|
271
|
-
|
|
272
|
-
Generate deterministic MDLD from RDF quads with visual styling.
|
|
287
|
+
- `context` — Final context with prefixes
|
|
288
|
+
- `primarySubjects` — Array of string IRIs (canonical identities)
|
|
289
|
+
- `primary` — Array of primary metadata objects
|
|
273
290
|
|
|
274
|
-
**
|
|
275
|
-
- `quads` (array, required) — Array of RDF/JS Quads to convert
|
|
276
|
-
- `context` (object, optional) — Prefix mappings (default: `{}`)
|
|
277
|
-
- `primarySubject` (string, optional) — String IRI to place first in output (ensures round-trip safety). If not provided, falls back to the first subject from quads.
|
|
278
|
-
|
|
279
|
-
**Returns:** `{ text, context }`
|
|
280
|
-
|
|
281
|
-
**Features:**
|
|
282
|
-
- Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
|
|
283
|
-
- Label-in-heading: Uses `rdfs:label` in subject headings when available
|
|
284
|
-
- Multiple labels: First label in heading, additional labels rendered as literals
|
|
285
|
-
- Round-trip safe: All data preserved through parse → generate → parse
|
|
286
|
-
- Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
|
|
287
|
-
|
|
288
|
-
### `generateNode({ quads, focusIRI, context })`
|
|
289
|
-
|
|
290
|
-
Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
|
|
291
|
-
|
|
292
|
-
**Parameters (named object):**
|
|
293
|
-
- `quads` (array, required) — Array of RDF/JS Quads to search
|
|
294
|
-
- `focusIRI` (string, required) — The IRI to center the view on
|
|
295
|
-
- `context` (object, optional) — Prefix mappings (default: `{}`)
|
|
296
|
-
|
|
297
|
-
**Returns:** `{ text, context }`
|
|
298
|
-
|
|
299
|
-
**Behavior (Safety-First):**
|
|
300
|
-
- If `focusIRI` is null/undefined: Returns empty text
|
|
301
|
-
- If `focusIRI` not in graph: Returns empty text (never falls back to all data)
|
|
302
|
-
- If `quads` is empty: Returns empty text
|
|
303
|
-
|
|
304
|
-
**Safety rationale:** Prevents accidental rendering of entire databases on misspelled IRIs—critical for production use with LLM cost per token. Explicit emptiness signals "not found" to the caller.
|
|
305
|
-
|
|
306
|
-
**Use case:** Perfect for exploring a specific node and all its relationships—where it appears as subject, object, predicate, type, or datatype. Creates an exhaustive view of everything related to the focus IRI. Ideal for node-centric knowledge graph explorers.
|
|
307
|
-
|
|
308
|
-
### `updateValue()` — Update Quad Carrier Text in Source Text
|
|
309
|
-
|
|
310
|
-
Update the carrier text of a literal quad in MDLD text. Only the carrier content is replaced — datatype (`^^xsd:integer`) and language (`@en`) annotations inside the `{…}` block are preserved as-is, since they are part of the annotation, not the carrier.
|
|
311
|
-
|
|
312
|
-
```javascript
|
|
313
|
-
import { parse, updateValue } from 'mdld-parse';
|
|
314
|
-
|
|
315
|
-
const mdld = `[ex] <http://example.org/>
|
|
291
|
+
**Use case:** CRDT-style state management with append-only documents.
|
|
316
292
|
|
|
317
|
-
|
|
293
|
+
### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove })`
|
|
318
294
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
const result = parse({ text: mdld });
|
|
322
|
-
const authorQuad = result.quads.find(q =>
|
|
323
|
-
q.subject.value === 'http://example.org/article' &&
|
|
324
|
-
q.predicate.value === 'http://example.org/author'
|
|
325
|
-
);
|
|
326
|
-
|
|
327
|
-
const updatedText = updateValue({
|
|
328
|
-
text: mdld,
|
|
329
|
-
quad: authorQuad,
|
|
330
|
-
value: 'Bob Johnson',
|
|
331
|
-
origin: result.origin // optional (auto-parses if not provided)
|
|
332
|
-
});
|
|
333
|
-
|
|
334
|
-
console.log(updatedText);
|
|
335
|
-
// [ex] <http://example.org/>
|
|
336
|
-
//
|
|
337
|
-
// # Article {=ex:article .ex:Article}
|
|
338
|
-
//
|
|
339
|
-
// [Bob Johnson] {ex:author}
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
**Annotation annotations are preserved:**
|
|
343
|
-
```javascript
|
|
344
|
-
// Original: > 25 {ex:age ^^xsd:integer}
|
|
345
|
-
updateValue({ text, quad, value: '30' });
|
|
346
|
-
// Result: > 30 {ex:age ^^xsd:integer} ← datatype preserved
|
|
347
|
-
|
|
348
|
-
// Original: > Hello {ex:greeting @en}
|
|
349
|
-
updateValue({ text, quad, value: 'Good morning' });
|
|
350
|
-
// Result: > Good morning {ex:greeting @en} ← language tag preserved
|
|
351
|
-
```
|
|
295
|
+
Generate deterministic MDLD from RDF quads.
|
|
352
296
|
|
|
353
297
|
**Parameters:**
|
|
354
|
-
- `
|
|
355
|
-
- `
|
|
356
|
-
- `
|
|
357
|
-
- `
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
**How it works:**
|
|
362
|
-
- Uses `locate()` to find the quad's position in the source text
|
|
363
|
-
- Uses `valueRange` to replace only the carrier text (excluding carrier markers like `[`, `]`)
|
|
364
|
-
- Annotation block `{…}` with predicate, datatype, language is untouched
|
|
365
|
-
- Auto-parses if result not provided (convenient but less efficient)
|
|
366
|
-
|
|
367
|
-
**Fail-safe behavior:**
|
|
368
|
-
- Returns original text if quad cannot be located
|
|
369
|
-
- Returns original text if valueRange is not available
|
|
370
|
-
- Never corrupts the source text
|
|
371
|
-
|
|
372
|
-
**Use case:** Perfect for editor applications that need to update literal values while preserving carrier syntax, datatype annotations, and language tags.
|
|
373
|
-
|
|
374
|
-
### Composition Patterns
|
|
375
|
-
|
|
376
|
-
With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
|
|
377
|
-
|
|
378
|
-
```javascript
|
|
379
|
-
import { parse, generate, generateNode } from 'mdld-parse';
|
|
298
|
+
- `quads` (array, required) — RDF/JS Quads to convert
|
|
299
|
+
- `context` (object, optional) — Prefix mappings
|
|
300
|
+
- `primarySubject` (string, optional) — IRI to place first in output
|
|
301
|
+
- `compactInline` (boolean, optional) — Inline type/label compaction (default: `false`)
|
|
302
|
+
- `renderReverse` (boolean, optional) — Reverse connections as `!p` (default: `false`)
|
|
303
|
+
- `remove` (array, optional) — RDF/JS Quads to retract (for diff generation)
|
|
380
304
|
|
|
381
|
-
|
|
382
|
-
const canonical = generate({ ...parse({ text, context }) });
|
|
383
|
-
// text → quads → canonical MDLD (deterministic, visual styling applied)
|
|
305
|
+
**Returns:** `{ text, context, compactStats }`
|
|
384
306
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
307
|
+
- `text` — Generated MDLD text
|
|
308
|
+
- `context` — Full context with prefixes
|
|
309
|
+
- `compactStats` — Compaction metrics
|
|
388
310
|
|
|
389
|
-
|
|
390
|
-
const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
|
|
391
|
-
// full graph → isolated node view (safe: returns empty if IRI not found)
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
**Why this works:**
|
|
395
|
-
- `parse()` returns `{ quads, context, primarySubject, md, ... }`
|
|
396
|
-
- `generate()` accepts `{ quads, context, primarySubject }`
|
|
397
|
-
- `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
|
|
398
|
-
- Perfect shape alignment enables elegant `{ ...spread }` composition
|
|
399
|
-
|
|
400
|
-
### The `md` Field — Clean Markdown Extraction
|
|
401
|
-
|
|
402
|
-
Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
|
|
311
|
+
**Features:** Visual styling, label-in-heading, round-trip safe, diff generation.
|
|
403
312
|
|
|
404
|
-
|
|
405
|
-
const result = parse({
|
|
406
|
-
text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
|
|
407
|
-
context: { ex: 'http://example.org/' }
|
|
408
|
-
});
|
|
313
|
+
### `generateNode({ quads, focusIRI, context, compactInline, renderReverse })`
|
|
409
314
|
|
|
410
|
-
|
|
411
|
-
// # Document\nContent
|
|
315
|
+
Generate node-centric MDLD for a specific IRI.
|
|
412
316
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
317
|
+
**Parameters:**
|
|
318
|
+
- `quads` (array, required) — RDF/JS Quads to search
|
|
319
|
+
- `focusIRI` (string, required) — IRI to center view on
|
|
320
|
+
- `context` (object, optional) — Prefix mappings
|
|
321
|
+
- `compactInline` (boolean, optional) — Inline compaction (default: `true`)
|
|
322
|
+
- `renderReverse` (boolean, optional) — Reverse connections (default: `true`)
|
|
417
323
|
|
|
418
|
-
**
|
|
419
|
-
- Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
|
|
420
|
-
- Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
|
|
421
|
-
- Invalid syntax (annotations not at end-of-line) is preserved as visible markers
|
|
422
|
-
- Headings, lists, blockquotes, code blocks maintain their structure
|
|
423
|
-
- Prefix declarations at start of line are stripped
|
|
424
|
-
- Standalone subject declarations (`{=ex:subject}`) are stripped
|
|
324
|
+
**Returns:** `{ text, context, compactStats }`
|
|
425
325
|
|
|
426
|
-
**
|
|
427
|
-
- **Content extraction** — Get readable Markdown without semantic markup
|
|
428
|
-
- **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
|
|
429
|
-
- **Round-trip testing** — `parse(md).md` should parse to zero quads
|
|
430
|
-
- **Preview generation** — Show clean document before publishing
|
|
326
|
+
**Safety:** Returns empty text if focusIRI not found (prevents accidental full database rendering).
|
|
431
327
|
|
|
432
|
-
### `
|
|
328
|
+
### `updateValue({ text, quad, value, origin })`
|
|
433
329
|
|
|
434
|
-
|
|
330
|
+
Update carrier text of a literal quad in MDLD text.
|
|
435
331
|
|
|
436
332
|
**Parameters:**
|
|
437
|
-
- `
|
|
438
|
-
- `
|
|
333
|
+
- `text` (string) — Original MDLD text
|
|
334
|
+
- `quad` (object) — Quad to update
|
|
335
|
+
- `value` (string) — New carrier text
|
|
336
|
+
- `origin` (object, optional) — ParseResult.origin
|
|
439
337
|
|
|
440
|
-
**Returns:**
|
|
338
|
+
**Returns:** Updated MDLD text (fail-safe)
|
|
441
339
|
|
|
442
|
-
|
|
443
|
-
- `valueRange`: Character range excluding carrier markers (null if not available)
|
|
340
|
+
**Use case:** Editor applications updating literal values.
|
|
444
341
|
|
|
445
|
-
### `
|
|
446
|
-
|
|
447
|
-
Render RDF quads as HTML+RDFa for web display.
|
|
342
|
+
### `locate(quad, origin)`
|
|
448
343
|
|
|
449
|
-
|
|
450
|
-
- `quads` (array) — Array of RDF/JS Quads to render
|
|
451
|
-
- `options` (object, optional):
|
|
452
|
-
- `context` (object) — Prefix mappings for CURIE shortening
|
|
453
|
-
- `baseIRI` (string) — Base IRI for resolving relative references
|
|
344
|
+
Locate quad origin entry for UI navigation.
|
|
454
345
|
|
|
455
|
-
**Returns:** `{
|
|
346
|
+
**Returns:** `{ blockId, range, valueRange, carrierType, ... }` or `null`
|
|
456
347
|
|
|
457
348
|
### Utility Functions
|
|
458
349
|
|
|
459
350
|
```javascript
|
|
460
351
|
import {
|
|
461
352
|
DEFAULT_CONTEXT, // Default prefix mappings
|
|
462
|
-
DataFactory, // RDF/JS DataFactory
|
|
463
|
-
hash, // String hashing
|
|
464
|
-
expandIRI, // IRI expansion
|
|
465
|
-
shortenIRI, // IRI shortening
|
|
466
|
-
parseSemanticBlock //
|
|
353
|
+
DataFactory, // RDF/JS DataFactory
|
|
354
|
+
hash, // String hashing
|
|
355
|
+
expandIRI, // IRI expansion
|
|
356
|
+
shortenIRI, // IRI shortening
|
|
357
|
+
parseSemanticBlock // Semantic block parsing
|
|
467
358
|
} from 'mdld-parse';
|
|
468
359
|
```
|
|
469
360
|
|
|
470
361
|
## 🏗️ Architecture
|
|
471
362
|
|
|
472
363
|
### Design Principles
|
|
473
|
-
- **Zero dependencies** — Pure JavaScript,
|
|
364
|
+
- **Zero dependencies** — Pure JavaScript, 84KB unminified (19KB gzipped)
|
|
474
365
|
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
475
|
-
- **
|
|
476
|
-
- **
|
|
366
|
+
- **Character-based tokenization** — 20-28% faster than regex-based approaches
|
|
367
|
+
- **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
|
|
368
|
+
- **Deterministic** — Same input always produces same output
|
|
477
369
|
- **Explicit semantics** — No guessing, inference, or heuristics
|
|
478
370
|
|
|
371
|
+
### Performance Characteristics
|
|
372
|
+
- **Real-time (60fps):** Up to 4,527 quads per frame
|
|
373
|
+
- **Batch processing:** Up to 225,059 quads per second
|
|
374
|
+
- **Memory efficient:** ~640 bytes per quad retained after GC
|
|
375
|
+
- **Streaming-friendly:** Full document never in memory
|
|
376
|
+
|
|
479
377
|
### RDF/JS Compatibility
|
|
480
|
-
Quads
|
|
378
|
+
Quads work with:
|
|
481
379
|
- [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
|
|
482
|
-
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF
|
|
380
|
+
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF stores
|
|
483
381
|
- [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
|
|
484
|
-
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) —
|
|
382
|
+
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — RDF utilities
|
|
485
383
|
|
|
486
|
-
|
|
384
|
+
### Standards Compliance
|
|
385
|
+
- **RDF 1.1** — Core RDF concepts
|
|
386
|
+
- **RDFS** — Schema vocabulary
|
|
387
|
+
- **PROV-O** — Provenance ontology
|
|
388
|
+
- **SHACL** — Constraint validation
|
|
389
|
+
- **W3C CURIE 1.0** — Compact URI syntax
|
|
487
390
|
|
|
488
|
-
|
|
391
|
+
## 🧪 Testing
|
|
489
392
|
|
|
490
393
|
```bash
|
|
491
394
|
pnpm test
|
|
492
395
|
```
|
|
493
396
|
|
|
494
|
-
|
|
495
|
-
-
|
|
496
|
-
-
|
|
497
|
-
-
|
|
498
|
-
-
|
|
499
|
-
-
|
|
500
|
-
- Round-trip
|
|
397
|
+
Comprehensive test suite covering:
|
|
398
|
+
- Syntax parsing and tokenization
|
|
399
|
+
- Context management and prefix folding
|
|
400
|
+
- Polarity system and retractions
|
|
401
|
+
- Elevated statements detection
|
|
402
|
+
- Primary metadata extraction
|
|
403
|
+
- Round-trip parse/generate cycles
|
|
404
|
+
- Origin tracking and provenance
|
|
405
|
+
|
|
406
|
+
## 📚 Additional Resources
|
|
407
|
+
|
|
408
|
+
- **[Documentation](./docs/index.md)** — Complete guides and references
|
|
409
|
+
- **[Specification](./spec/index.md)** — Formal specification
|
|
410
|
+
- **[Examples](./examples/index.md)** — Real-world examples
|
|
411
|
+
- **[Grammar](./grammar/mdld.ebnf)** — EBNF grammar specification
|
|
412
|
+
- **[VS Code Extension](https://marketplace.visualstudio.com/)** — Syntax highlighting (coming soon)
|