mdld-parse 0.9.8 → 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 +243 -262
- package/dist/index.js +1797 -1324
- package/package.json +5 -5
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +0 -1
- package/dist/README.md +0 -431
- 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 -459
- 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 -60
- 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 -3023
- 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
|
|
53
|
+
|
|
54
|
+
// Generate MDLD from quads
|
|
55
|
+
const { text } = generate({ quads: result.quads });
|
|
20
56
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
[Alice] {?ex:author =ex:alice .prov:Person ex:firstName label}
|
|
24
|
-
[Smith] {ex:lastName}`);
|
|
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".
|
|
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.
|
|
71
|
+
|
|
72
|
+
### The MD-LD Solution
|
|
73
|
+
|
|
74
|
+
MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
|
|
75
|
+
|
|
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
|
|
49
83
|
|
|
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
|
|
84
|
+
### Real-World Applications
|
|
61
85
|
|
|
62
|
-
|
|
86
|
+
#### Personal Knowledge Management
|
|
87
|
+
```markdown
|
|
88
|
+
[alice] <tag:alice@example.com,2026:>
|
|
89
|
+
|
|
90
|
+
# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
|
|
63
91
|
|
|
64
|
-
|
|
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}
|
|
98
|
+
```
|
|
65
99
|
|
|
100
|
+
#### Developer Documentation
|
|
66
101
|
```markdown
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
Energy level: [8] {my:energyLevel ^^xsd:integer}
|
|
72
|
-
Met [Sam] {+my:sam .my:Person ?my:attendee} on my regular walk at [Central Park] {+my:central-park ?my:location .my:Place label @en} and talked about [Sunny] {my:weather} weather.
|
|
102
|
+
# API Endpoint {=api:/users/:id .api:Endpoint}
|
|
103
|
+
|
|
104
|
+
[GET] {api:method}
|
|
105
|
+
[/users/:id] {api:path}
|
|
73
106
|
```
|
|
74
107
|
|
|
75
|
-
|
|
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';
|
|
87
|
-
|
|
88
|
-
const markdown = `[ex] <tag:alice@example.org,2026:>
|
|
155
|
+
import { parse, generate, merge } from 'mdld-parse';
|
|
89
156
|
|
|
90
|
-
|
|
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,196 +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.
|
|
291
|
+
**Use case:** CRDT-style state management with append-only documents.
|
|
278
292
|
|
|
279
|
-
|
|
293
|
+
### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove })`
|
|
280
294
|
|
|
281
|
-
|
|
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
|
|
295
|
+
Generate deterministic MDLD from RDF quads.
|
|
287
296
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
- `
|
|
294
|
-
- `
|
|
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
|
-
### Composition Patterns
|
|
309
|
-
|
|
310
|
-
With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
|
|
311
|
-
|
|
312
|
-
```javascript
|
|
313
|
-
import { parse, generate, generateNode } from 'mdld-parse';
|
|
314
|
-
|
|
315
|
-
// Pattern 1: parse → generate (semantic extraction)
|
|
316
|
-
const canonical = generate({ ...parse({ text, context }) });
|
|
317
|
-
// text → quads → canonical MDLD (deterministic, visual styling applied)
|
|
318
|
-
|
|
319
|
-
// Pattern 2: generate → parse (normalize external RDF)
|
|
320
|
-
const normalized = parse({ ...generate({ quads: externalQuads, context }) });
|
|
321
|
-
// external quads → MDLD → validated quads (DataFactory-safe, no blank nodes)
|
|
322
|
-
|
|
323
|
-
// Pattern 3: parse → generateNode (node-centric exploration)
|
|
324
|
-
const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
|
|
325
|
-
// full graph → isolated node view (safe: returns empty if IRI not found)
|
|
326
|
-
```
|
|
297
|
+
**Parameters:**
|
|
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)
|
|
327
304
|
|
|
328
|
-
**
|
|
329
|
-
- `parse()` returns `{ quads, context, primarySubject, md, ... }`
|
|
330
|
-
- `generate()` accepts `{ quads, context, primarySubject }`
|
|
331
|
-
- `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
|
|
332
|
-
- Perfect shape alignment enables elegant `{ ...spread }` composition
|
|
305
|
+
**Returns:** `{ text, context, compactStats }`
|
|
333
306
|
|
|
334
|
-
|
|
307
|
+
- `text` — Generated MDLD text
|
|
308
|
+
- `context` — Full context with prefixes
|
|
309
|
+
- `compactStats` — Compaction metrics
|
|
335
310
|
|
|
336
|
-
|
|
311
|
+
**Features:** Visual styling, label-in-heading, round-trip safe, diff generation.
|
|
337
312
|
|
|
338
|
-
|
|
339
|
-
const result = parse({
|
|
340
|
-
text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
|
|
341
|
-
context: { ex: 'http://example.org/' }
|
|
342
|
-
});
|
|
313
|
+
### `generateNode({ quads, focusIRI, context, compactInline, renderReverse })`
|
|
343
314
|
|
|
344
|
-
|
|
345
|
-
// # Document\nContent
|
|
315
|
+
Generate node-centric MDLD for a specific IRI.
|
|
346
316
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
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`)
|
|
351
323
|
|
|
352
|
-
**
|
|
353
|
-
- Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
|
|
354
|
-
- Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
|
|
355
|
-
- Invalid syntax (annotations not at end-of-line) is preserved as visible markers
|
|
356
|
-
- Headings, lists, blockquotes, code blocks maintain their structure
|
|
357
|
-
- Prefix declarations at start of line are stripped
|
|
358
|
-
- Standalone subject declarations (`{=ex:subject}`) are stripped
|
|
324
|
+
**Returns:** `{ text, context, compactStats }`
|
|
359
325
|
|
|
360
|
-
**
|
|
361
|
-
- **Content extraction** — Get readable Markdown without semantic markup
|
|
362
|
-
- **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
|
|
363
|
-
- **Round-trip testing** — `parse(md).md` should parse to zero quads
|
|
364
|
-
- **Preview generation** — Show clean document before publishing
|
|
326
|
+
**Safety:** Returns empty text if focusIRI not found (prevents accidental full database rendering).
|
|
365
327
|
|
|
366
|
-
### `
|
|
328
|
+
### `updateValue({ text, quad, value, origin })`
|
|
367
329
|
|
|
368
|
-
|
|
330
|
+
Update carrier text of a literal quad in MDLD text.
|
|
369
331
|
|
|
370
332
|
**Parameters:**
|
|
371
|
-
- `
|
|
372
|
-
- `
|
|
333
|
+
- `text` (string) — Original MDLD text
|
|
334
|
+
- `quad` (object) — Quad to update
|
|
335
|
+
- `value` (string) — New carrier text
|
|
336
|
+
- `origin` (object, optional) — ParseResult.origin
|
|
373
337
|
|
|
374
|
-
**Returns:**
|
|
338
|
+
**Returns:** Updated MDLD text (fail-safe)
|
|
375
339
|
|
|
376
|
-
|
|
340
|
+
**Use case:** Editor applications updating literal values.
|
|
377
341
|
|
|
378
|
-
|
|
342
|
+
### `locate(quad, origin)`
|
|
379
343
|
|
|
380
|
-
|
|
381
|
-
- `quads` (array) — Array of RDF/JS Quads to render
|
|
382
|
-
- `options` (object, optional):
|
|
383
|
-
- `context` (object) — Prefix mappings for CURIE shortening
|
|
384
|
-
- `baseIRI` (string) — Base IRI for resolving relative references
|
|
344
|
+
Locate quad origin entry for UI navigation.
|
|
385
345
|
|
|
386
|
-
**Returns:** `{
|
|
346
|
+
**Returns:** `{ blockId, range, valueRange, carrierType, ... }` or `null`
|
|
387
347
|
|
|
388
348
|
### Utility Functions
|
|
389
349
|
|
|
390
350
|
```javascript
|
|
391
351
|
import {
|
|
392
352
|
DEFAULT_CONTEXT, // Default prefix mappings
|
|
393
|
-
DataFactory, // RDF/JS DataFactory
|
|
394
|
-
hash, // String hashing
|
|
395
|
-
expandIRI, // IRI expansion
|
|
396
|
-
shortenIRI, // IRI shortening
|
|
397
|
-
parseSemanticBlock //
|
|
353
|
+
DataFactory, // RDF/JS DataFactory
|
|
354
|
+
hash, // String hashing
|
|
355
|
+
expandIRI, // IRI expansion
|
|
356
|
+
shortenIRI, // IRI shortening
|
|
357
|
+
parseSemanticBlock // Semantic block parsing
|
|
398
358
|
} from 'mdld-parse';
|
|
399
359
|
```
|
|
400
360
|
|
|
401
361
|
## 🏗️ Architecture
|
|
402
362
|
|
|
403
363
|
### Design Principles
|
|
404
|
-
- **Zero dependencies** — Pure JavaScript,
|
|
364
|
+
- **Zero dependencies** — Pure JavaScript, 84KB unminified (19KB gzipped)
|
|
405
365
|
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
406
|
-
- **
|
|
407
|
-
- **
|
|
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
|
|
408
369
|
- **Explicit semantics** — No guessing, inference, or heuristics
|
|
409
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
|
+
|
|
410
377
|
### RDF/JS Compatibility
|
|
411
|
-
Quads
|
|
378
|
+
Quads work with:
|
|
412
379
|
- [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
|
|
413
|
-
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF
|
|
380
|
+
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF stores
|
|
414
381
|
- [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
|
|
415
|
-
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) —
|
|
382
|
+
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — RDF utilities
|
|
416
383
|
|
|
417
|
-
|
|
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
|
|
418
390
|
|
|
419
|
-
|
|
391
|
+
## 🧪 Testing
|
|
420
392
|
|
|
421
393
|
```bash
|
|
422
394
|
pnpm test
|
|
423
395
|
```
|
|
424
396
|
|
|
425
|
-
|
|
426
|
-
-
|
|
427
|
-
-
|
|
428
|
-
-
|
|
429
|
-
-
|
|
430
|
-
-
|
|
431
|
-
- 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)
|