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
|
@@ -1,326 +0,0 @@
|
|
|
1
|
-
# Primary Metadata Example
|
|
2
|
-
|
|
3
|
-
This example demonstrates the Primary Metadata feature in MD-LD, which provides immediate access to the main entity, type, label, comment described by a document.
|
|
4
|
-
|
|
5
|
-
## Primary Metadata Quartet
|
|
6
|
-
|
|
7
|
-
MD-LD tracks three primary metadata fields during parsing to provide immediate document identity:
|
|
8
|
-
|
|
9
|
-
| Field | Source | Purpose |
|
|
10
|
-
|-------|--------|---------|
|
|
11
|
-
| **primarySubject** | First non-fragment `{=subject}` | Document identity (canonical append identity) |
|
|
12
|
-
| **primaryType** | First `rdf:type` declaration | Document category (semantic classification) |
|
|
13
|
-
| **primaryLabel** | First `rdfs:label` literal | Human-readable name (UI & display) |
|
|
14
|
-
| **primaryComment** | First `rdfs:comment` literal | Human-readable comment (UI & description) |
|
|
15
|
-
|
|
16
|
-
## Dual-Layer Architecture
|
|
17
|
-
|
|
18
|
-
MD-LD implements a **dual-layer architecture** that separates concerns cleanly:
|
|
19
|
-
|
|
20
|
-
| Layer | Field | Role | Use Cases |
|
|
21
|
-
| ------ | ------ | --------- | ---------- |
|
|
22
|
-
| **Canonical Identity** | `primarySubject` | Storage, routing, synchronization, append operations |
|
|
23
|
-
| **Semantic Surface** | `primary` object | UI rendering, indexing, navigation, agent orientation |
|
|
24
|
-
|
|
25
|
-
## What is a Primary Subject?
|
|
26
|
-
|
|
27
|
-
The Primary Subject is the first non-fragment subject declaration (`{=IRI}`) in a document. It provides a deterministic way to identify the central focus of a document.
|
|
28
|
-
|
|
29
|
-
## What is a Primary Type?
|
|
30
|
-
|
|
31
|
-
The Primary Type is the first `rdf:type` declaration associated with the Primary Subject. It provides a way to identify the type of the main entity described by a document.
|
|
32
|
-
|
|
33
|
-
### 1. First Type Declaration Wins
|
|
34
|
-
|
|
35
|
-
```markdown
|
|
36
|
-
# Person {=my:alice .prov:Person .schema:Person}
|
|
37
|
-
[Details] {label}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
`primaryType` captures the **first rdf:type assertion emitted while current subject == primarySubject**. This is parser-precise and avoids ambiguity with later type declarations for other entities.
|
|
41
|
-
|
|
42
|
-
## What is a Primary Label?
|
|
43
|
-
|
|
44
|
-
The Primary Label is the first `rdfs:label` literal associated with the Primary Subject. It provides a human-readable name for the main entity described by a document.
|
|
45
|
-
|
|
46
|
-
### 2. First Label Declaration Wins
|
|
47
|
-
|
|
48
|
-
```markdown
|
|
49
|
-
# Person {=my:alice .prov:Person label}
|
|
50
|
-
[Alice Smith] {rdfs:label}
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
`primaryLabel` captures the **first emitted rdfs:label literal while current subject == primarySubject**. This ensures the label is associated with the primary subject, not other entities in the document.
|
|
54
|
-
|
|
55
|
-
## Example Document
|
|
56
|
-
|
|
57
|
-
```markdown
|
|
58
|
-
[ex] <http://example.org/>
|
|
59
|
-
|
|
60
|
-
# Article {=ex:article .schema:Article label}
|
|
61
|
-
[Understanding Primary Subjects] {schema:headline}
|
|
62
|
-
|
|
63
|
-
## Author {=ex:author .schema:Person}
|
|
64
|
-
[Alice Smith] {schema:name}
|
|
65
|
-
[alice@example.com] {schema:email}
|
|
66
|
-
|
|
67
|
-
## Abstract
|
|
68
|
-
This article explains the Primary Subject concept in MD-LD, which allows applications to quickly identify the main entity described by a document.
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Parsing with Primary Metadata
|
|
72
|
-
|
|
73
|
-
```javascript
|
|
74
|
-
import { parse } from 'mdld-parse';
|
|
75
|
-
|
|
76
|
-
const md = `[ex] <tag:alice@example.org,2026:articles/>
|
|
77
|
-
[schema] <http://schema.org/>
|
|
78
|
-
|
|
79
|
-
# Understanding Primary Subjects {=ex:understanding-primary-subject .schema:Article label}
|
|
80
|
-
`;
|
|
81
|
-
|
|
82
|
-
const result = parse({ text: md });
|
|
83
|
-
|
|
84
|
-
// Canonical append identity
|
|
85
|
-
console.log('Primary Subject:', result.primarySubject);
|
|
86
|
-
// Semantic surface descriptor
|
|
87
|
-
console.log('Primary Object:', result.primary);
|
|
88
|
-
// Output:
|
|
89
|
-
// Primary Subject: tag:alice@example.org,2026:articles/understanding-primary-subject
|
|
90
|
-
// Primary Object: {
|
|
91
|
-
// subject: 'tag:alice@example.org,2026:articles/understanding-primary-subject',
|
|
92
|
-
// type: 'http://schema.org/Article',
|
|
93
|
-
// label: 'Understanding Primary Subjects'
|
|
94
|
-
// }
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
## Key Behaviors
|
|
98
|
-
|
|
99
|
-
### 1. First Non-Fragment Subject Wins
|
|
100
|
-
|
|
101
|
-
```markdown
|
|
102
|
-
{=#summary} // Fragment - NOT primary
|
|
103
|
-
[Summary] {label}
|
|
104
|
-
|
|
105
|
-
# Document {=ex:doc} // First non-fragment - PRIMARY
|
|
106
|
-
[Alice] {author}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Primary subject: `ex:doc`
|
|
110
|
-
|
|
111
|
-
### 2. Reset Does Not Clear Primary Subject
|
|
112
|
-
|
|
113
|
-
```markdown
|
|
114
|
-
# First {=ex:first}
|
|
115
|
-
[Value] {label}
|
|
116
|
-
|
|
117
|
-
# Reset {=} // Does not clear primary subject
|
|
118
|
-
|
|
119
|
-
# Second {=ex:second}
|
|
120
|
-
[Value] {label}
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Primary subject: `ex:first` (fixed once detected)
|
|
124
|
-
|
|
125
|
-
### 3. No Subject Means No Primary
|
|
126
|
-
|
|
127
|
-
```markdown
|
|
128
|
-
[Just text] {label}
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Primary subject: `null`
|
|
132
|
-
|
|
133
|
-
## Merge with Primary Subjects
|
|
134
|
-
|
|
135
|
-
When merging multiple documents, the `merge()` function returns an array of all primary subjects in merge order:
|
|
136
|
-
|
|
137
|
-
```javascript
|
|
138
|
-
import { merge } from 'mdld-parse';
|
|
139
|
-
|
|
140
|
-
const doc1 = `[ex] <http://example.org/>
|
|
141
|
-
# Document 1 {=ex:doc1}
|
|
142
|
-
[Content] {label}`;
|
|
143
|
-
|
|
144
|
-
const doc2 = `[ex] <http://example.org/>
|
|
145
|
-
# Document 2 {=ex:doc2}
|
|
146
|
-
[Content] {label}`;
|
|
147
|
-
|
|
148
|
-
const result = merge([doc1, doc2], { context: { ex: 'http://example.org/' } });
|
|
149
|
-
|
|
150
|
-
// Canonical append identities
|
|
151
|
-
console.log('Primary Subjects:', result.primarySubjects);
|
|
152
|
-
// Semantic surface descriptors
|
|
153
|
-
console.log('Primary Objects:', result.primary);
|
|
154
|
-
// Output:
|
|
155
|
-
// Primary Subjects: ['http://example.org/doc1', 'http://example.org/doc2']
|
|
156
|
-
// Primary Objects: [
|
|
157
|
-
// { subject: 'http://example.org/doc1', type: 'http://schema.org/Article', label: 'Document 1' },
|
|
158
|
-
// { subject: 'http://example.org/doc2', type: 'http://schema.org/Article', label: 'Document 2' }
|
|
159
|
-
// ]
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
## Use Cases
|
|
163
|
-
|
|
164
|
-
- **Document Identity** - Primary subject + type + label provide complete document fingerprint
|
|
165
|
-
- **Stream Addressing** - Perfect for Nostr tags and distributed systems
|
|
166
|
-
- **Merge Tracking** - Track which entities are being merged across documents
|
|
167
|
-
- **UI Navigation** - Provide default focus and display information for document viewers
|
|
168
|
-
- **Query Optimization** - Use primary metadata as default query context and filters
|
|
169
|
-
- **Content Classification** - Automatic categorization based on primary type
|
|
170
|
-
- **Search Indexing** - Use primary label for human-readable search results
|
|
171
|
-
|
|
172
|
-
## RDF Philosophy Alignment
|
|
173
|
-
|
|
174
|
-
The Primary Subject feature aligns with core W3C/RDF principles:
|
|
175
|
-
|
|
176
|
-
### Document Identity
|
|
177
|
-
RDF 1.1 Named Graphs recognize the importance of document-centric RDF. Primary Subject makes document identity explicit without forcing graph-centric assumptions, supporting the document-centric approach (FOAF profiles, RSS feeds) that's part of the Linked Data ecosystem.
|
|
178
|
-
|
|
179
|
-
### Provenance Tracking (PROV-O)
|
|
180
|
-
The W3C PROV-O standard emphasizes tracking data origin. Primary Subject provides a deterministic way to identify what a document is "about," which is foundational for provenance chains and attribution.
|
|
181
|
-
|
|
182
|
-
### Dereferenceability
|
|
183
|
-
Linked Data principles emphasize that IRIs should be dereferenceable. Having a clear primary subject makes it immediately clear what IRI to dereference when encountering a document, supporting the "follow your nose" navigation pattern.
|
|
184
|
-
|
|
185
|
-
### Minimal Commitment
|
|
186
|
-
RDF's philosophy is about making minimal assertions. Primary Subject is lightweight metadata - it doesn't add triples to the graph, just provides a pointer to the main subject. This aligns with MDLD's "no implicit semantics" principle.
|
|
187
|
-
|
|
188
|
-
### Explicit over Implicit
|
|
189
|
-
The W3C encourages explicit semantics over inference. Primary Subject makes document focus explicit rather than requiring heuristic analysis of the graph to determine "what this document is about."
|
|
190
|
-
|
|
191
|
-
## Grounded Documents: Long-Term Benefits
|
|
192
|
-
|
|
193
|
-
Primary Subject enables a new class of semantic applications that treat documents as meaningful units in knowledge workflows:
|
|
194
|
-
|
|
195
|
-
### Document-Centric Knowledge Graphs
|
|
196
|
-
- Citation networks with clear document identity
|
|
197
|
-
- Document versioning and evolution tracking
|
|
198
|
-
- Cross-document referencing and linking
|
|
199
|
-
- Entity-focused provenance chains
|
|
200
|
-
|
|
201
|
-
### Semantic Search and Discovery
|
|
202
|
-
- Index documents by their main entity
|
|
203
|
-
- Support queries like "find all documents about X" without complex graph pattern matching
|
|
204
|
-
- Entity-based relevance scoring
|
|
205
|
-
|
|
206
|
-
### Incremental Graph Construction
|
|
207
|
-
- Determine which documents describe the same entity (deduplication)
|
|
208
|
-
- Smart merge order and priority decisions
|
|
209
|
-
- Conflict resolution strategies based on entity overlap
|
|
210
|
-
- Graph topology construction guidance
|
|
211
|
-
|
|
212
|
-
### Collaborative Semantic Editing
|
|
213
|
-
- Track which entities are being modified across authors
|
|
214
|
-
- Coordinate concurrent edits at entity level
|
|
215
|
-
- Detect merge conflicts at entity granularity
|
|
216
|
-
- Provide contextual editing assistance
|
|
217
|
-
|
|
218
|
-
### Semantic Version Control
|
|
219
|
-
- Entity-level version tracking within document systems
|
|
220
|
-
- Queries like "show me how entity X has changed across versions"
|
|
221
|
-
- Entity-focused diff and merge operations
|
|
222
|
-
- Granular change attribution
|
|
223
|
-
|
|
224
|
-
### Knowledge Graph Federation
|
|
225
|
-
- Identify overlapping entities across different sources
|
|
226
|
-
- Determine authoritative sources for specific entities
|
|
227
|
-
- Build confidence scores based on document provenance
|
|
228
|
-
- Source-aware query planning
|
|
229
|
-
|
|
230
|
-
### AI/LLM Integration
|
|
231
|
-
- Primary subject provides clear context for document understanding
|
|
232
|
-
- Entity-focused prompt engineering
|
|
233
|
-
- Document retrieval by entity relevance
|
|
234
|
-
- Improved fact-checking and attribution
|
|
235
|
-
|
|
236
|
-
The Primary Subject feature bridges document-centric and graph-centric approaches, enabling semantic applications that treat documents as first-class citizens in knowledge workflows while respecting RDF's core principles of explicit semantics and minimal commitment.
|
|
237
|
-
|
|
238
|
-
## Complete Example
|
|
239
|
-
|
|
240
|
-
```javascript
|
|
241
|
-
import { parse, merge } from 'mdld-parse';
|
|
242
|
-
|
|
243
|
-
// Single document
|
|
244
|
-
const doc1 = `[blog] <https://example.com/blog/>
|
|
245
|
-
# My First Post {=blog:post1 .schema:BlogPosting label}
|
|
246
|
-
[Hello World] {schema:headline}`;
|
|
247
|
-
|
|
248
|
-
const result1 = parse({ text: doc1, context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
|
|
249
|
-
|
|
250
|
-
// Canonical append identity
|
|
251
|
-
console.log('Primary Subject:', result1.primarySubject);
|
|
252
|
-
// Semantic surface descriptor
|
|
253
|
-
console.log('Primary Object:', result1.primary);
|
|
254
|
-
// Output:
|
|
255
|
-
// Primary Subject: https://example.com/blog/post1
|
|
256
|
-
// Primary Object: {
|
|
257
|
-
// subject: 'https://example.com/blog/post1',
|
|
258
|
-
// type: 'http://schema.org/BlogPosting',
|
|
259
|
-
// label: 'My First Post'
|
|
260
|
-
// }
|
|
261
|
-
|
|
262
|
-
// Multiple documents
|
|
263
|
-
const doc2 = `[blog] <https://example.com/blog/>
|
|
264
|
-
# My Second Post {=blog:post2 .schema:BlogPosting label}
|
|
265
|
-
[Hello Again] {schema:headline}`;
|
|
266
|
-
|
|
267
|
-
const merged = merge([doc1, doc2], { context: { blog: 'https://example.com/blog/', schema: 'http://schema.org/' } });
|
|
268
|
-
|
|
269
|
-
// Canonical append identities
|
|
270
|
-
console.log('Primary Subjects:', merged.primarySubjects);
|
|
271
|
-
// Semantic surface descriptors
|
|
272
|
-
console.log('Primary Objects:', merged.primary);
|
|
273
|
-
// Output:
|
|
274
|
-
// Primary Subjects: ['https://example.com/blog/post1', 'https://example.com/blog/post2']
|
|
275
|
-
// Primary Objects: [
|
|
276
|
-
// { subject: 'https://example.com/blog/post1', type: 'http://schema.org/BlogPosting', label: 'My First Post' },
|
|
277
|
-
// { subject: 'https://example.com/blog/post2', type: 'http://schema.org/BlogPosting', label: 'My Second Post' }
|
|
278
|
-
// ]
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
## Document Identity Trio
|
|
282
|
-
|
|
283
|
-
The primary metadata trio provides sufficient document/append stream identity for most scenarios:
|
|
284
|
-
|
|
285
|
-
```javascript
|
|
286
|
-
// Nostr integration example
|
|
287
|
-
const nostrTags = [
|
|
288
|
-
['s', result.primarySubject], // subject addressing (canonical)
|
|
289
|
-
['t', result.primary.type], // type filtering
|
|
290
|
-
['d', result.primary.label] // display identifier
|
|
291
|
-
];
|
|
292
|
-
|
|
293
|
-
// Document fingerprint
|
|
294
|
-
const fingerprint = {
|
|
295
|
-
canonical: result.primarySubject, // What the document is about (append identity)
|
|
296
|
-
semantic: result.primary // How to present and index the document
|
|
297
|
-
};
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
## Primary Metadata is Parser-Level Metadata
|
|
301
|
-
|
|
302
|
-
**Important**: Primary metadata is derived parser state and does not introduce additional RDF triples or semantic entailments. It describes document intent, not graph semantics.
|
|
303
|
-
|
|
304
|
-
### Key Distinctions
|
|
305
|
-
|
|
306
|
-
| Aspect | Primary Metadata | RDF Semantics |
|
|
307
|
-
|---------|------------------|----------------|
|
|
308
|
-
| **Source** | Parser extraction rules | Triple patterns |
|
|
309
|
-
| **Scope** | Document-level intent | Graph-level relationships |
|
|
310
|
-
| **Purpose** | Routing, UI, indexing | Reasoning, inference |
|
|
311
|
-
| **Stability** | Deterministic extraction | Dynamic inference |
|
|
312
|
-
|
|
313
|
-
### Stability Guarantees
|
|
314
|
-
|
|
315
|
-
`primarySubject` is **stable under rewrite() operations that preserve extracted quads**. This means:
|
|
316
|
-
|
|
317
|
-
- Append routing remains consistent across document updates
|
|
318
|
-
- Synchronization identity is preserved during merges
|
|
319
|
-
- File mapping stays stable through rewrite operations
|
|
320
|
-
- Index references remain valid
|
|
321
|
-
|
|
322
|
-
This stability is crucial for distributed systems and local-first architectures.
|
|
323
|
-
|
|
324
|
-
## Specification
|
|
325
|
-
|
|
326
|
-
For complete details on Primary Subject semantics, see the [MD-LD Specification](../spec/Spec.md#17-primary-subject).
|
package/dist/docs/statements.md
DELETED
|
@@ -1,226 +0,0 @@
|
|
|
1
|
-
# Elevated Statements
|
|
2
|
-
|
|
3
|
-
MD-LD provides **elevated statements** through automatic `rdf:Statement` pattern detection, enabling authors to create a "golden graph" of intentionally elevated statements while maintaining complete provenance in the underlying data.
|
|
4
|
-
|
|
5
|
-
## π― Concept Overview
|
|
6
|
-
|
|
7
|
-
Elevated statements allow you to:
|
|
8
|
-
- **Separate signal from noise** - Dashboard apps can use only the elevated statements
|
|
9
|
-
- **Maintain provenance** - Complete context remains available in the full graph
|
|
10
|
-
- **Single-pass parsing** - No performance overhead, detected during normal parsing
|
|
11
|
-
- **Flexible patterns** - Support both IRI references and direct literals
|
|
12
|
-
|
|
13
|
-
## π Pattern Requirements
|
|
14
|
-
|
|
15
|
-
For a statement to be elevated, it must have:
|
|
16
|
-
1. **rdf:type rdf:Statement** - The subject must be typed as an RDF Statement
|
|
17
|
-
2. **rdf:subject** - The subject of the elevated SPO triple
|
|
18
|
-
3. **rdf:predicate** - The predicate of the elevated SPO triple
|
|
19
|
-
4. **rdf:object** - The object of the elevated SPO triple
|
|
20
|
-
|
|
21
|
-
When all four parts are present, the parser automatically creates an elevated SPO quad in the `statements` array.
|
|
22
|
-
|
|
23
|
-
## π§ Syntax Patterns
|
|
24
|
-
|
|
25
|
-
### Basic Pattern with IRIs
|
|
26
|
-
|
|
27
|
-
```markdown
|
|
28
|
-
[ex] <http://example.org/>
|
|
29
|
-
|
|
30
|
-
## Elevated statement {=ex:stmt1 .rdf:Statement}
|
|
31
|
-
**Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
|
|
32
|
-
|
|
33
|
-
**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob} - direct statement
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Pattern with Direct Literals
|
|
37
|
-
|
|
38
|
-
For datatypes and language tags, use direct literals:
|
|
39
|
-
|
|
40
|
-
```markdown
|
|
41
|
-
[ex] <http://example.org/>
|
|
42
|
-
|
|
43
|
-
## Statement with datatype {=ex:stmt1 .rdf:Statement}
|
|
44
|
-
**Alice** {+ex:alice ?rdf:subject} *has age* {+ex:hasAge ?rdf:predicate} **25** {rdf:object ^^xsd:integer}
|
|
45
|
-
|
|
46
|
-
## Statement with language {=ex:stmt2 .rdf:Statement}
|
|
47
|
-
**Alice** {+ex:alice ?rdf:subject} *has name* {+ex:hasName ?rdf:predicate} **Alice** {rdf:object @en}
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### Real-World Example
|
|
51
|
-
|
|
52
|
-
```markdown
|
|
53
|
-
[my] <tag:alice@example.com,2026:>
|
|
54
|
-
[foaf] <http://xmlns.com/foaf/0.1/>
|
|
55
|
-
|
|
56
|
-
My name is **Alice** {=my:Alice .foaf:Person foaf:name}.
|
|
57
|
-
|
|
58
|
-
{=}
|
|
59
|
-
|
|
60
|
-
Today I have learned that my colleague name is [Clair] {=my:Claire .foaf:Person foaf:name}
|
|
61
|
-
|
|
62
|
-
## I know Claire's name {=my:claire-name .rdf:Statement}
|
|
63
|
-
|
|
64
|
-
[My colleague] {+my:Claire ?rdf:subject} [name] {+foaf:name ?rdf:predicate} is [Clair] {rdf:object}.
|
|
65
|
-
|
|
66
|
-
{=}
|
|
67
|
-
|
|
68
|
-
## We've talked! {=my:claire-first-talk .rdf:Statement}
|
|
69
|
-
|
|
70
|
-
Today [I] {+my:Alice ?rdf:subject} came to office a bit earlier and [talked for some time] {+foaf:knows ?rdf:predicate} with [Claire] {+my:Claire ?rdf:object}.
|
|
71
|
-
|
|
72
|
-
Now **I** {=my:Alice} know **Claire** {+my:Claire ?foaf:knows}.
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
## π Usage in Applications
|
|
76
|
-
|
|
77
|
-
### API Access
|
|
78
|
-
|
|
79
|
-
```javascript
|
|
80
|
-
import { parse } from 'mdld-parse';
|
|
81
|
-
|
|
82
|
-
const result = parse({ text: `# Test {=tag:me@example.org,2026:test .prov:Entity label}`});
|
|
83
|
-
console.log(result.quads); // All quads including provenance
|
|
84
|
-
console.log(result.statements); // Elevated SPO quads (detected during parsing)
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
### Dashboard Applications
|
|
88
|
-
|
|
89
|
-
Dashboard applications can:
|
|
90
|
-
|
|
91
|
-
- **Ignore provenance-rich data** by using only `result.statements`
|
|
92
|
-
- **Access the "golden graph"** of intentionally elevated statements
|
|
93
|
-
- **Maintain complete provenance** in `result.quads` when needed
|
|
94
|
-
- **Filter by context** using the origin tracking system
|
|
95
|
-
|
|
96
|
-
### Example: Simple Graph Display
|
|
97
|
-
|
|
98
|
-
```javascript
|
|
99
|
-
import { parse } from 'mdld-parse';
|
|
100
|
-
|
|
101
|
-
function displayElevatedGraph(markdown) {
|
|
102
|
-
const result = parse({text: markdown});
|
|
103
|
-
|
|
104
|
-
// Display only elevated statements
|
|
105
|
-
result.statements.forEach(quad => {
|
|
106
|
-
console.log(`${quad.subject.value} β ${quad.predicate.value} β ${quad.object.value}`);
|
|
107
|
-
});
|
|
108
|
-
|
|
109
|
-
return result.statements.length; // Number of elevated statements
|
|
110
|
-
}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
## π Data Flow
|
|
114
|
-
|
|
115
|
-
```
|
|
116
|
-
MD-LD Document
|
|
117
|
-
β (single-pass parsing)
|
|
118
|
-
All Quads + Elevated Statements
|
|
119
|
-
β
|
|
120
|
-
βββββββββββββββββββ¬ββββββββββββββββββ
|
|
121
|
-
β result.quads βresult.statementsβ
|
|
122
|
-
β (provenance) β (golden graph) β
|
|
123
|
-
βββββββββββββββββββ΄ββββββββββββββββββ
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
## π¨ Best Practices
|
|
127
|
-
|
|
128
|
-
### 1. Use Descriptive Statement IDs
|
|
129
|
-
|
|
130
|
-
```markdown
|
|
131
|
-
## Alice knows Bob {=ex:alice-knows-bob .rdf:Statement}
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
### 2. Preserve Datatypes and Languages
|
|
135
|
-
|
|
136
|
-
```markdown
|
|
137
|
-
## Person's birth date {=ex:birth-date .rdf:Statement}
|
|
138
|
-
**Alice** {+ex:alice ?rdf:subject} *born on* {+ex:bornOn ?rdf:predicate} **1990-01-01** {rdf:object ^^xsd:date}
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
### 3. Mix Elevated and Regular Statements
|
|
142
|
-
|
|
143
|
-
```markdown
|
|
144
|
-
## Elevated: Important fact {=ex:important .rdf:Statement}
|
|
145
|
-
**Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
|
|
146
|
-
|
|
147
|
-
**Alice** {=ex:alice} also knows **Charlie** {?ex:knows +ex:charlie} - regular statement
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
### 4. Use Subject Resets for Organization
|
|
151
|
-
|
|
152
|
-
```markdown
|
|
153
|
-
{=}
|
|
154
|
-
|
|
155
|
-
## New section {=ex:section-stmt .rdf:Statement}
|
|
156
|
-
**Fact** {+ex:fact ?rdf:subject} *has value* {+ex:hasValue ?rdf:predicate} **42** {rdf:object ^^xsd:integer}
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
## π Technical Details
|
|
160
|
-
|
|
161
|
-
### Single-Pass Detection
|
|
162
|
-
|
|
163
|
-
Elevated statements are detected during the normal parsing process:
|
|
164
|
-
|
|
165
|
-
1. **Quad emission** - As each quad is created, the pattern detector runs
|
|
166
|
-
2. **Candidate tracking** - Incomplete patterns are tracked in memory
|
|
167
|
-
3. **Pattern completion** - When all parts are present, elevated SPO is created
|
|
168
|
-
4. **Cleanup** - Completed patterns are removed from tracking
|
|
169
|
-
|
|
170
|
-
### Memory Efficiency
|
|
171
|
-
|
|
172
|
-
- **O(1) additional memory** - Only tracks incomplete patterns
|
|
173
|
-
- **Automatic cleanup** - Completed patterns are removed immediately
|
|
174
|
-
- **No backtracking** - True single-pass processing
|
|
175
|
-
|
|
176
|
-
### Compatibility
|
|
177
|
-
|
|
178
|
-
- **RDF/JS compliant** - Elevated statements are standard RDF quads
|
|
179
|
-
- **Toolchain compatible** - Works with n3.js, rdflib, and other RDF libraries
|
|
180
|
-
- **Streaming friendly** - No additional passes required
|
|
181
|
-
|
|
182
|
-
## π Comparison with Alternatives
|
|
183
|
-
|
|
184
|
-
| Approach | Provenance | Performance | Flexibility | Complexity |
|
|
185
|
-
|----------|------------|-------------|-------------|------------|
|
|
186
|
-
| **Elevated Statements** | β
Complete | β
Single-pass | β
High | π‘ Medium |
|
|
187
|
-
| **Named Graphs** | β
Complete | β‘ Multiple passes | π‘ Medium | π΄ High |
|
|
188
|
-
| **Manual Filtering** | β
Complete | β
Single-pass | π΄ Low | π’ Low |
|
|
189
|
-
| **Separate Documents** | β Lost | β
Single-pass | π΄ Low | π’ Low |
|
|
190
|
-
|
|
191
|
-
## π― Use Cases
|
|
192
|
-
|
|
193
|
-
### Knowledge Management
|
|
194
|
-
- Elevate important facts while preserving context
|
|
195
|
-
- Create "golden graph" for search and discovery
|
|
196
|
-
- Maintain full provenance for audit trails
|
|
197
|
-
|
|
198
|
-
### API Design
|
|
199
|
-
- Provide simplified endpoints with elevated statements only
|
|
200
|
-
- Offer detailed endpoints with full provenance
|
|
201
|
-
- Enable progressive disclosure of information
|
|
202
|
-
|
|
203
|
-
### Content Management
|
|
204
|
-
- Separate published content from editorial metadata
|
|
205
|
-
- Create curated views while preserving edits
|
|
206
|
-
- Support content approval workflows
|
|
207
|
-
|
|
208
|
-
### Data Integration
|
|
209
|
-
- Elevate validated mappings while preserving transformation rules
|
|
210
|
-
- Create clean integration graphs with full audit trails
|
|
211
|
-
- Support data lineage and governance
|
|
212
|
-
|
|
213
|
-
## π§ͺ Testing
|
|
214
|
-
|
|
215
|
-
The elevated statements feature is covered by comprehensive tests:
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
npm test # All 105 tests pass, including elevated statements
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
Test coverage includes:
|
|
222
|
-
- Basic pattern detection
|
|
223
|
-
- Multiple elevated statements
|
|
224
|
-
- Incomplete patterns (ignored)
|
|
225
|
-
- Mixed content scenarios
|
|
226
|
-
- Datatype and language preservation
|