mdld-parse 0.9.9 β†’ 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +263 -326
  2. package/dist/index.js +1860 -1337
  3. package/package.json +4 -4
  4. package/dist/.nojekyll +0 -0
  5. package/dist/CNAME +0 -1
  6. package/dist/README.md +0 -500
  7. package/dist/docs/API.md +0 -435
  8. package/dist/docs/Architecture.md +0 -190
  9. package/dist/docs/Guide.md +0 -816
  10. package/dist/docs/LLM-MDLD-Inducer.md +0 -550
  11. package/dist/docs/LiterateRDF.md +0 -472
  12. package/dist/docs/Parser.md +0 -720
  13. package/dist/docs/Performance.md +0 -238
  14. package/dist/docs/Spec-render.md +0 -1439
  15. package/dist/docs/Subject.md +0 -180
  16. package/dist/docs/Syntax.md +0 -463
  17. package/dist/docs/TodoList.md +0 -215
  18. package/dist/docs/Use-Cases.md +0 -354
  19. package/dist/docs/guide-m.md +0 -56
  20. package/dist/docs/index.html +0 -108
  21. package/dist/docs/index.md +0 -56
  22. package/dist/docs/one-page.md +0 -322
  23. package/dist/docs/origin.md +0 -460
  24. package/dist/docs/polarity.md +0 -586
  25. package/dist/docs/primary-subject.md +0 -326
  26. package/dist/docs/statements.md +0 -226
  27. package/dist/docs/tokenization-performance-report.md +0 -164
  28. package/dist/examples/Cookbook.md +0 -32
  29. package/dist/examples/Status-SHACL.md +0 -31
  30. package/dist/examples/demo/index.md +0 -35
  31. package/dist/examples/demo/journal.md +0 -58
  32. package/dist/examples/demo/minimal.md +0 -23
  33. package/dist/examples/demo/project.md +0 -84
  34. package/dist/examples/demo/prov.md +0 -107
  35. package/dist/examples/demo/rdf.md +0 -69
  36. package/dist/examples/demo/recipe.md +0 -50
  37. package/dist/examples/demo/research.md +0 -84
  38. package/dist/examples/demo/shacl.md +0 -161
  39. package/dist/examples/demo/space-mission.md +0 -58
  40. package/dist/examples/demo/tasks.md +0 -175
  41. package/dist/examples/demo/xsd.md +0 -91
  42. package/dist/examples/dogfood.md +0 -288
  43. package/dist/examples/few-shot.md +0 -309
  44. package/dist/examples/graph/rdf-graph.html +0 -473
  45. package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
  46. package/dist/examples/index.md +0 -45
  47. package/dist/examples/llm-time-workflow.md +0 -173
  48. package/dist/examples/statements.md +0 -43
  49. package/dist/examples/workflow.md +0 -150
  50. package/dist/index.html +0 -3049
  51. package/dist/logo.svg +0 -7
  52. package/dist/spec/Spec-compact.md +0 -368
  53. package/dist/spec/Spec-ultra.md +0 -232
  54. package/dist/spec/Spec.md +0 -1116
  55. 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).
@@ -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