mdld-parse 0.9.2 → 0.9.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +1 -0
- package/dist/README.md +425 -0
- package/dist/docs/API.md +397 -0
- package/dist/docs/Architecture.md +190 -0
- package/dist/docs/Guide.md +816 -0
- package/dist/docs/LLM-MDLD-Inducer.md +550 -0
- package/dist/docs/Parser.md +654 -0
- package/dist/docs/Performance.md +238 -0
- package/dist/docs/Spec-render.md +1439 -0
- package/dist/docs/Subject.md +180 -0
- package/dist/docs/Syntax.md +463 -0
- package/dist/docs/TodoList.md +215 -0
- package/dist/docs/Use-Cases.md +354 -0
- package/dist/docs/guide-m.md +56 -0
- package/dist/docs/index.html +108 -0
- package/dist/docs/index.md +56 -0
- package/dist/docs/one-page.md +322 -0
- package/dist/docs/origin.md +459 -0
- package/dist/docs/polarity.md +586 -0
- package/dist/docs/primary-subject.md +199 -0
- package/dist/docs/statements.md +226 -0
- package/dist/docs/tokenization-performance-report.md +164 -0
- package/dist/examples/Cookbook.md +32 -0
- package/dist/examples/Status-SHACL.md +31 -0
- package/dist/examples/demo/index.md +35 -0
- package/dist/examples/demo/journal.md +119 -0
- package/dist/examples/demo/minimal.md +23 -0
- package/dist/examples/demo/project.md +98 -0
- package/dist/examples/demo/prov.md +107 -0
- package/dist/examples/demo/rdf.md +69 -0
- package/dist/examples/demo/recipe.md +95 -0
- package/dist/examples/demo/research.md +126 -0
- package/dist/examples/demo/shacl.md +161 -0
- package/dist/examples/demo/space-mission.md +129 -0
- package/dist/examples/demo/tasks.md +175 -0
- package/dist/examples/demo/xsd.md +91 -0
- package/dist/examples/dogfood.md +288 -0
- package/dist/examples/few-shot.md +309 -0
- package/dist/examples/graph/rdf-graph.html +473 -0
- package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
- package/dist/examples/index.md +45 -0
- package/dist/examples/llm-time-workflow.md +173 -0
- package/dist/examples/statements.md +43 -0
- package/dist/examples/workflow.md +150 -0
- package/dist/index.html +3253 -0
- package/dist/index.js +1770 -0
- package/dist/logo.svg +7 -0
- package/dist/spec/Spec-compact.md +363 -0
- package/dist/spec/Spec-ultra.md +221 -0
- package/dist/spec/Spec.md +1068 -0
- package/dist/spec/index.md +46 -0
- package/package.json +7 -8
- package/src/constants.js +0 -31
- package/src/generate.js +0 -245
- package/src/highlight.js +0 -362
- package/src/index.js +0 -13
- package/src/locate.js +0 -23
- package/src/merge.js +0 -157
- package/src/parse.js +0 -711
- package/src/render.js +0 -576
- package/src/shared.js +0 -577
- package/src/tokenizers.js +0 -594
- package/src/utils.js +0 -430
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
[mdld] <https://mdld.js.org/>
|
|
2
|
+
[xsd] <http://www.w3.org/2001/XMLSchema#>
|
|
3
|
+
[@vocab] <http://www.w3.org/2000/01/rdf-schema#>
|
|
4
|
+
[my] <tag:mdld@example.com,2026:>
|
|
5
|
+
[ex] <my:example:>
|
|
6
|
+
|
|
7
|
+
# MD-LD: Complete Syntax Specification {=mdld:dogfood .Class label}
|
|
8
|
+
|
|
9
|
+
> MD-LD is a **semantic annotation layer** for CommonMark Markdown that creates RDF knowledge graphs from explicit `{...}` annotations. {mdld:dogfood comment}
|
|
10
|
+
|
|
11
|
+
## Default Context {=mdld:default-context .Class label}
|
|
12
|
+
|
|
13
|
+
MD-LD provides these built-in prefixes and vocabulary:
|
|
14
|
+
|
|
15
|
+
Default vocabulary and prefixes: {mdld:includes .Class label}
|
|
16
|
+
- `@vocab`: `http://www.w3.org/2000/01/rdf-schema#` {=mdld:vocab}
|
|
17
|
+
- `rdf`: `http://www.w3.org/1999/02/22-rdf-syntax-ns#` {=mdld:rdf-prefix}
|
|
18
|
+
- `rdfs`: `http://www.w3.org/2000/01/rdf-schema#` {=mdld:rdfs-prefix}
|
|
19
|
+
- `xsd`: `http://www.w3.org/2001/XMLSchema#` {=mdld:xsd-prefix}
|
|
20
|
+
- `sh`: `http://www.w3.org/ns/shacl#` {=mdld:sh-prefix}
|
|
21
|
+
- `prov`: `http://www.w3.org/ns/prov#` {=mdld:prov-prefix}
|
|
22
|
+
|
|
23
|
+
## Prefix Folding {=mdld:prefix-folding .Container label}
|
|
24
|
+
|
|
25
|
+
MD-LD supports hierarchical namespace building through prefix folding:
|
|
26
|
+
|
|
27
|
+
Base namespace declaration:
|
|
28
|
+
- `[my] <tag:mdld@example.com,2026:>` {+mdld:base-namespace ?member}
|
|
29
|
+
|
|
30
|
+
Derived namespaces using CURIE syntax:
|
|
31
|
+
- `[ex] <my:example:>` {+mdld:derived-namespace ?member}
|
|
32
|
+
|
|
33
|
+
This resolves to: `tag:mdld@example.com,2026:example:`
|
|
34
|
+
|
|
35
|
+
**Resolution Rules:**
|
|
36
|
+
- Prefixes must be declared before they can be referenced (forward-reference only)
|
|
37
|
+
- Circular references are treated as literal strings
|
|
38
|
+
- Later declarations override earlier ones
|
|
39
|
+
|
|
40
|
+
**Examples:**
|
|
41
|
+
- `ex:doc` → `tag:mdld@example.com,2026:example:doc`
|
|
42
|
+
- `my:journal:2026-01-27` → `tag:mdld@example.com,2026:journal:2026-01-27`
|
|
43
|
+
|
|
44
|
+
### Prefix Folding Examples
|
|
45
|
+
Demonstrated namespaces:
|
|
46
|
+
- Document: [Example doc] {+ex:doc .Class label ?member}
|
|
47
|
+
- Feature: [Example feature] {+ex:feature .Class label ?member}
|
|
48
|
+
- Parser: [Example parser] {+ex:parser .Class label ?member}
|
|
49
|
+
|
|
50
|
+
## Angle-Bracket URLs {=mdld:angle-urls .Container label}
|
|
51
|
+
|
|
52
|
+
MD-LD supports angle-bracket URLs as value carriers with soft subject behavior:
|
|
53
|
+
|
|
54
|
+
### URL Value Carriers
|
|
55
|
+
External resources as soft subjects:
|
|
56
|
+
- <https://www.w3.org/TR/rdf11-concepts/> {.Specification label}
|
|
57
|
+
- <https://github.com/mdld-js/mdld-parse> {?mdld:implementation .Repository label}
|
|
58
|
+
- <https://arxiv.org/abs/2301.07041> {!mdld:cites .Paper label}
|
|
59
|
+
|
|
60
|
+
### URL Behavior Rules
|
|
61
|
+
Angle-bracket URLs follow these rules:
|
|
62
|
+
- Type declarations use URL as subject: `<URL> {.Type}`
|
|
63
|
+
- Object predicates use current subject: `<URL> {?predicate}`
|
|
64
|
+
- Reverse predicates use URL as subject: `<URL> {!predicate}`
|
|
65
|
+
- Literal predicates are ignored: `<URL> {literal}` (no output)
|
|
66
|
+
|
|
67
|
+
## Core Classes {=mdld:classes .Container label}
|
|
68
|
+
|
|
69
|
+
All classes used in this document:
|
|
70
|
+
|
|
71
|
+
- Document {+mdld:Document ?member .Class label}
|
|
72
|
+
- Concept {+mdld:Concept ?member .Class label}
|
|
73
|
+
- Resource {+mdld:Resource ?member .Class label}
|
|
74
|
+
- Principle {+mdld:Principle ?member .Class label}
|
|
75
|
+
- Feature {+mdld:Feature ?member .Class label}
|
|
76
|
+
- Layer {+mdld:Layer ?member .Class label}
|
|
77
|
+
- Component {+mdld:Component ?member .Class label}
|
|
78
|
+
- Software {+mdld:Software ?member .Class label}
|
|
79
|
+
|
|
80
|
+
## Parser Architecture {=mdld:parser-arch .Container label}
|
|
81
|
+
|
|
82
|
+
### Tokenization Phase
|
|
83
|
+
The parser processes documents in a single pass with these token types: {mdld:includes .Class label}
|
|
84
|
+
|
|
85
|
+
Token types created during scanning:
|
|
86
|
+
- `prefix` - Context declarations `[name] <IRI>`
|
|
87
|
+
- `heading` - Markdown headings `# text {attrs}`
|
|
88
|
+
- `list` - List items `- text {attrs}` or `1. text {attrs}`
|
|
89
|
+
- `blockquote` - Blockquotes `> text {attrs}`
|
|
90
|
+
- `code` - Code blocks with annotations
|
|
91
|
+
- `para` - Paragraphs with potential inline carriers
|
|
92
|
+
|
|
93
|
+
### Processing Pipeline
|
|
94
|
+
Document processing follows this pipeline:
|
|
95
|
+
1. **Line-by-line scanning** {+#line-by-line .Class label ?member}
|
|
96
|
+
2. **Context resolution** {+#context-resolution .Class label ?member}
|
|
97
|
+
3. **Subject tracking** {+#subject-tracking .Class label ?member}
|
|
98
|
+
4. **Annotation processing** {+#annotation-processing .Class label ?member}
|
|
99
|
+
5. **Quad emission** {+#quad-emission .Class label ?member}
|
|
100
|
+
|
|
101
|
+
### Semantic Block Processing
|
|
102
|
+
Annotations are parsed using cached semantic blocks: {mdld:includes .Class label}
|
|
103
|
+
- Parse `{...}` blocks into structured semantic objects
|
|
104
|
+
- Cache frequently used patterns for performance
|
|
105
|
+
- Extract subjects, predicates, types, and modifiers
|
|
106
|
+
- Handle all three predicate forms (`p`, `?p`, `!p`)
|
|
107
|
+
|
|
108
|
+
## Context Declarations {=mdld:context .Container label}
|
|
109
|
+
|
|
110
|
+
MD-LD supports prefix and vocabulary declarations following JSON-LD patterns:
|
|
111
|
+
|
|
112
|
+
Prefix declarations:
|
|
113
|
+
- `[mdld] <https://mdld.js.org/>` {+mdld:prefix .Class label ?member}
|
|
114
|
+
- `[xsd] <http://www.w3.org/2001/XMLSchema#>` {+mdld:xsd .Class label ?member}
|
|
115
|
+
- `[@vocab] <http://www.w3.org/2000/01/rdf-schema#>` {+mdld:vocab .Class label ?member}
|
|
116
|
+
|
|
117
|
+
## Core Principles {=mdld:principles .Container label}
|
|
118
|
+
|
|
119
|
+
MD-LD follows strict rules:
|
|
120
|
+
|
|
121
|
+
**Markdown-preserving** {+#markdown-preserving ?member label} - Remove `{...}` → valid Markdown
|
|
122
|
+
**Explicit only** {+#explicit-only ?member label} - No implicit semantics or guessing
|
|
123
|
+
**Single-pass** {+#single-pass ?member label} - Streaming-friendly processing
|
|
124
|
+
**Deterministic** {+#deterministic ?member label} - Same input → same output
|
|
125
|
+
**Traceable** {+#traceable ?member label} - Every fact traces to its source
|
|
126
|
+
|
|
127
|
+
## Subject Management {=mdld:subjects .Container label}
|
|
128
|
+
|
|
129
|
+
### Full IRI Subjects
|
|
130
|
+
[Document with full IRI] {+mdld:doc-full ?member .Class label} demonstrates persistent subjects
|
|
131
|
+
|
|
132
|
+
### Fragment Subjects
|
|
133
|
+
[Section with fragment] {+#fragment-example ?member .Class label} creates relative identifiers
|
|
134
|
+
|
|
135
|
+
### Subject Reset
|
|
136
|
+
[{=}] {+mdld:reset ?member label} shows subject clearing
|
|
137
|
+
|
|
138
|
+
### Temporary Objects
|
|
139
|
+
[Related concept] {+mdld:temporary ?member label} demonstrates block-scoped objects
|
|
140
|
+
|
|
141
|
+
### Soft Fragments
|
|
142
|
+
[Soft fragment example] {+#soft-fragment ?member label} demonstrates temporary fragments
|
|
143
|
+
|
|
144
|
+
**Use cases:**
|
|
145
|
+
- `[Related Item] {+ex:related ?schema:isRelatedTo}` - Links to a local fragment
|
|
146
|
+
- `[Parent] {+ex:parent !schema:hasPart}` - Reverse relationship
|
|
147
|
+
- `[Section] {+#section1 name ?hasPart}` - Object property with fragment
|
|
148
|
+
|
|
149
|
+
The soft IRI only exists within the current annotation block.
|
|
150
|
+
|
|
151
|
+
## Value Carriers {=mdld:carriers .Container label}
|
|
152
|
+
|
|
153
|
+
### Inline Elements
|
|
154
|
+
**Inline elements:** [*italic*] {+mdld:italic ?member} [**bold**] {+mdld:bold ?member} [`code`] {+mdld:code ?member}
|
|
155
|
+
|
|
156
|
+
### Block Elements
|
|
157
|
+
**Block elements:** # [Headings] {+mdld:heading ?member} > [Quotes] {+mdld:quote ?member}
|
|
158
|
+
|
|
159
|
+
### Links and Media
|
|
160
|
+
**Links:** [MD-LD Website](https://mdld.js.org) {?member}
|
|
161
|
+
**Images:**  {?member}
|
|
162
|
+
|
|
163
|
+
## Predicate Forms {=mdld:predicates .Class label}
|
|
164
|
+
|
|
165
|
+
Three predicate directions create different relationships:
|
|
166
|
+
|
|
167
|
+
- **Subject→Literal**: [MD-LD] {label} creates `mdld:doc label "MD-LD"`
|
|
168
|
+
- **Subject→Object**: [RDF](https://www.w3.org/RDF) {mdld:seeAlso} creates `mdld:doc rdfs:seeAlso <https://www.w3.org/RDF>`
|
|
169
|
+
- **Object→Subject**: [Example] {mdld:isDefinedBy} creates `mdld:example mdld:isDefinedBy mdld:doc`
|
|
170
|
+
|
|
171
|
+
## Type Declarations {=mdld:types .Container label}
|
|
172
|
+
|
|
173
|
+
### Single Types
|
|
174
|
+
[Single type example] {+mdld:single ?member .Class label}
|
|
175
|
+
|
|
176
|
+
### Multiple Types
|
|
177
|
+
[Multiple types example] {+mdld:multiple ?member .Class .mdld:Class1 label}
|
|
178
|
+
|
|
179
|
+
## Literal Modifiers {=mdld:literals .Container label}
|
|
180
|
+
|
|
181
|
+
### Typed Literals
|
|
182
|
+
[2024] {mdld:year ^^xsd:gYear}
|
|
183
|
+
[3.14159] {mdld:pi ^^xsd:decimal}
|
|
184
|
+
[true] {mdld:bool ^^xsd:boolean}
|
|
185
|
+
|
|
186
|
+
### Language-Tagged Literals
|
|
187
|
+
[Hello] {mdld:english @en}
|
|
188
|
+
[Bonjour] {mdld:french @fr}
|
|
189
|
+
[Hola] {mdld:spanish @es}
|
|
190
|
+
|
|
191
|
+
## Lists and Nesting {=mdld:lists .Container label}
|
|
192
|
+
|
|
193
|
+
Lists are pure Markdown structure with **no semantic scope**. Each list item requires explicit annotations.
|
|
194
|
+
|
|
195
|
+
### List Item Requirements
|
|
196
|
+
|
|
197
|
+
**Critical Rule**: All list items must have explicit subject (`{=iri}` or `{+iri}`) to emit semantics.
|
|
198
|
+
|
|
199
|
+
### Simple Lists
|
|
200
|
+
Research team members:
|
|
201
|
+
|
|
202
|
+
- **Principal investigator** {+#pi ?member .mdld:Role label}
|
|
203
|
+
- **Research assistant** {+#assistant ?member .mdld:Role label}
|
|
204
|
+
- **Lab technician** {+#tech ?member .mdld:Role label}
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
## Code Blocks {=mdld:code-blocks .Container label}
|
|
208
|
+
|
|
209
|
+
### Annotated Code Blocks
|
|
210
|
+
```javascript {=mdld:example-code .Class text}
|
|
211
|
+
console.log("MD-LD creates RDF from Markdown");
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Parser Implementation Examples
|
|
215
|
+
```javascript {=mdld:parser-code .Class text}
|
|
216
|
+
// Token scanning implementation
|
|
217
|
+
function scanTokens(text) {
|
|
218
|
+
const tokens = [];
|
|
219
|
+
const lines = text.split('\n');
|
|
220
|
+
// Process each line for tokens...
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### EBNF Grammar Examples
|
|
225
|
+
```txt {=mdld:ebnf-grammar .Class text}
|
|
226
|
+
attrsBlock = "{" , whitespace* , attrsTokens? , whitespace* , "}" ;
|
|
227
|
+
attrsTokens = attrsToken , { whitespace+ , attrsToken } ;
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
This *JavaScript* {=mdld:js label} code shows annotation syntax.
|
|
231
|
+
|
|
232
|
+
## Blockquotes {=mdld:blockquote .Class label}
|
|
233
|
+
|
|
234
|
+
> Blockquotes serve as carriers for normative statements and comments. {mdld:blockquote comment}
|
|
235
|
+
|
|
236
|
+
> **Important**: All semantics must be explicit - no implicit inference. {mdld:normative comment}
|
|
237
|
+
|
|
238
|
+
> **Parser Note**: The implementation uses token-based scanning, not AST building. {mdld:parser-note comment}
|
|
239
|
+
|
|
240
|
+
## Advanced Features {=mdld:advanced .Class label}
|
|
241
|
+
|
|
242
|
+
### Soft Fragments
|
|
243
|
+
[Soft fragment example] {+#soft-fragment mdld:seeAlso label} demonstrates temporary fragments
|
|
244
|
+
|
|
245
|
+
### Complex Annotations
|
|
246
|
+
[Complex example] {=mdld:complex .Class label comment mdld:seeAlso} shows multiple predicates
|
|
247
|
+
|
|
248
|
+
### Reverse Relationships
|
|
249
|
+
[Target entity] {!mdld:hasPart label} demonstrates reverse predicate form
|
|
250
|
+
|
|
251
|
+
## Processing Model {=mdld:processing .Class label}
|
|
252
|
+
|
|
253
|
+
### Streaming Processing
|
|
254
|
+
MD-LD processes documents in a single pass: {?mdld:includes .Class label}
|
|
255
|
+
- Line-by-line tokenization {=#line-by-line}
|
|
256
|
+
- Subject tracking {=#subject-tracking}
|
|
257
|
+
- Quad emission {=#quad-emission}
|
|
258
|
+
|
|
259
|
+
### Origin Tracking
|
|
260
|
+
Every quad maintains origin information for round-trip serialization:
|
|
261
|
+
- Block identification
|
|
262
|
+
- Position tracking
|
|
263
|
+
- Slot indexing
|
|
264
|
+
|
|
265
|
+
### Semantic Block Caching
|
|
266
|
+
The parser uses caching for performance: {mdld:includes .Class label}
|
|
267
|
+
- Parse semantic blocks once and cache results
|
|
268
|
+
- Avoid repeated parsing of identical annotations
|
|
269
|
+
- Maintain deterministic output while improving speed
|
|
270
|
+
|
|
271
|
+
## Error Handling {=mdld:errors .Class label}
|
|
272
|
+
|
|
273
|
+
### Graceful Degradation
|
|
274
|
+
MD-LD recovers from malformed annotations:
|
|
275
|
+
- Unknown prefixes → skip annotation
|
|
276
|
+
- Malformed IRIs → skip annotation
|
|
277
|
+
- Unbalanced braces → fatal error
|
|
278
|
+
- Invalid carriers → skip annotation
|
|
279
|
+
|
|
280
|
+
## Connected Knowledge Graph {=mdld:graph .Class label}
|
|
281
|
+
|
|
282
|
+
This document demonstrates how MD-LD creates a **self-describing knowledge graph** where:
|
|
283
|
+
- The document explains MD-LD using MD-LD
|
|
284
|
+
- Every concept is explicitly typed and related
|
|
285
|
+
- The resulting RDF graph mirrors the document structure
|
|
286
|
+
- All features connect into a coherent semantic model
|
|
287
|
+
|
|
288
|
+
> The document itself becomes both specification and proof of concept. { comment}
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# MDLD Few-Shot Induction
|
|
2
|
+
|
|
3
|
+
## MENTAL MODEL
|
|
4
|
+
|
|
5
|
+
Annotations generate RDF triples.
|
|
6
|
+
Text outside annotations is free form and is ignored by the graph.
|
|
7
|
+
Subject context persists until next {=...} declaration or explicit `{=}` reset marker
|
|
8
|
+
|
|
9
|
+
## STRICT GRAMMAR
|
|
10
|
+
```
|
|
11
|
+
Prefixes:
|
|
12
|
+
[my] <tag:myemail@example.com,2026:>
|
|
13
|
+
[folded] <my:folded:>
|
|
14
|
+
|
|
15
|
+
Subjects:
|
|
16
|
+
=IRI # Full IRI, persists
|
|
17
|
+
=#fragment # Relative to current subject, replaces current fragment
|
|
18
|
+
|
|
19
|
+
Predicates:
|
|
20
|
+
p # Literal property
|
|
21
|
+
?p # Object property
|
|
22
|
+
!p # Reverse property
|
|
23
|
+
|
|
24
|
+
Objects:
|
|
25
|
+
+iri # Object for local ?/! predicates
|
|
26
|
+
+#fragment # Soft fragment, replaces current fragment
|
|
27
|
+
|
|
28
|
+
Classes:
|
|
29
|
+
.Class # S rdf:type schema:Class
|
|
30
|
+
|
|
31
|
+
Inline value carriers:
|
|
32
|
+
[value] # Literal span
|
|
33
|
+
**value** # Bold span
|
|
34
|
+
`value` # Code span
|
|
35
|
+
[value](url) # Link
|
|
36
|
+
 # Image
|
|
37
|
+
|
|
38
|
+
Block value carriers:
|
|
39
|
+
```value``` # Code block
|
|
40
|
+
> value # Quote
|
|
41
|
+
# value # Headings
|
|
42
|
+
- value # List item
|
|
43
|
+
|
|
44
|
+
Datatypes:
|
|
45
|
+
^^datatypeIRI # Typed data
|
|
46
|
+
@lang # Language tag
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## RULES
|
|
50
|
+
|
|
51
|
+
- {=IRI} sets subject
|
|
52
|
+
- {+IRI} introduces object
|
|
53
|
+
- ?p forward object property
|
|
54
|
+
- !p inverse property
|
|
55
|
+
- literals come only from value carriers
|
|
56
|
+
|
|
57
|
+
## Invariants (strict)
|
|
58
|
+
|
|
59
|
+
- Every triple must come from an annotation
|
|
60
|
+
- Every literal must come from a value carrier
|
|
61
|
+
- {=} always sets the current subject
|
|
62
|
+
- {+IRI} creates a new node reference
|
|
63
|
+
- List headers apply only to immediate list items
|
|
64
|
+
- Do not invent predicates or prefixes
|
|
65
|
+
- No blank nodes - all nodes must be IRIs
|
|
66
|
+
- never use example.org prefix - prefer `tag:myemail@example.com,2026:` as per RFC 4151
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
## Default context
|
|
70
|
+
|
|
71
|
+
The following prefixes are assumed available: `rdf`, `rdfs`, `xsd`, `sh`, `prov`.
|
|
72
|
+
|
|
73
|
+
## Examples
|
|
74
|
+
|
|
75
|
+
### Example 0
|
|
76
|
+
|
|
77
|
+
```plaintext
|
|
78
|
+
Alice knows Bob.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```ttl
|
|
82
|
+
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
|
|
83
|
+
@prefix my: <tag:alice@example.com,2026:>.
|
|
84
|
+
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
|
|
85
|
+
|
|
86
|
+
my:alice foaf:knows my:bob.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```mdld
|
|
90
|
+
[my] <tag:alice@example.com,2026:>
|
|
91
|
+
[foaf] <http://xmlns.com/foaf/0.1/>
|
|
92
|
+
|
|
93
|
+
[Alice] {=my:alice} knows [Bob] {+my:bob ?foaf:knows}.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Example 1
|
|
97
|
+
|
|
98
|
+
```plaintext
|
|
99
|
+
Today was a good day. I was happy and the weather was sunny. I went to Central Park. It felt peaceful and the park was beautiful. I met Sam there. I had my coffee in the morning, so I went straight to dinner.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```ttl
|
|
103
|
+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
104
|
+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
|
|
105
|
+
@prefix my: <tag:alice@example.com,2026:>.
|
|
106
|
+
@prefix j: <tag:alice@example.com,2026:journal:>.
|
|
107
|
+
|
|
108
|
+
j:2026-02-27 a j:Record;
|
|
109
|
+
j:date "2026-02-27"^^xsd:date;
|
|
110
|
+
rdfs:label "A nice day in the park";
|
|
111
|
+
j:mood "happy";
|
|
112
|
+
j:energyLevel 8^^xsd:integer;
|
|
113
|
+
my:location my:central-park;
|
|
114
|
+
my:weather "Sunny";
|
|
115
|
+
j:emotionalState "peaceful";
|
|
116
|
+
j:comment "beautiful";
|
|
117
|
+
j:met my:sam;
|
|
118
|
+
my:central-park a my:Place;
|
|
119
|
+
rdfs:label "Central Park"@en.
|
|
120
|
+
my:sam a my:Person.
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
```mdld
|
|
124
|
+
[my] <tag:alice@example.com,2026:>
|
|
125
|
+
[j] <my:journal:>
|
|
126
|
+
|
|
127
|
+
# 2026-02-27 {=j:2026-02-27 .j:Record j:date ^^xsd:date}
|
|
128
|
+
|
|
129
|
+
## A nice day in the park {label}
|
|
130
|
+
|
|
131
|
+
With a [happy] {j:mood} mood and quite high energy [8] {j:energyLevel ^^xsd:integer} I went to the [Central Park] {+my:central-park ?my:location .my:Place label @en}. The weather was [Sunny] {my:weather}. I felt [peaceful] {j:emotionalState} and the park was [beautiful] {j:comment}.
|
|
132
|
+
|
|
133
|
+
In the park I met [Sam] {+my:sam .my:Person ?j:met}.
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Example 2
|
|
137
|
+
|
|
138
|
+
```plaintext
|
|
139
|
+
Project Alpha has 3 tasks - Design schema, Implement parser and Write documentation.
|
|
140
|
+
Design schema is done, Implement parser is done and Write documentation is in process - we need to add API reference.
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
```ttl
|
|
144
|
+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
145
|
+
|
|
146
|
+
@prefix ex: <http://example.org/>.
|
|
147
|
+
|
|
148
|
+
ex:ProjectAlpha a ex:Project;
|
|
149
|
+
ex:hasTask <http://example.org/ProjectAlpha#task1>, <http://example.org/ProjectAlpha#task2>, <http://example.org/ProjectAlpha#task3>.
|
|
150
|
+
<http://example.org/ProjectAlpha#task1> a ex:Task;
|
|
151
|
+
rdfs:label "Design schema";
|
|
152
|
+
ex:status ex:done.
|
|
153
|
+
<http://example.org/ProjectAlpha#task2> a ex:Task;
|
|
154
|
+
rdfs:label "Implement parser";
|
|
155
|
+
ex:status ex:done.
|
|
156
|
+
<http://example.org/ProjectAlpha#task3> a ex:Task;
|
|
157
|
+
rdfs:label "Write documentation";
|
|
158
|
+
ex:subTask <http://example.org/ProjectAlpha#subtask3a>;
|
|
159
|
+
ex:status ex:in-process.
|
|
160
|
+
<http://example.org/ProjectAlpha#subtask3a> a ex:Task;
|
|
161
|
+
rdfs:label "API reference";
|
|
162
|
+
ex:status ex:todo.
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
```mdld
|
|
168
|
+
[ex] <http://example.org/>
|
|
169
|
+
|
|
170
|
+
# Project Alpha {=ex:ProjectAlpha .ex:Project}
|
|
171
|
+
|
|
172
|
+
Project includes tasks: {}
|
|
173
|
+
|
|
174
|
+
- Design schema {+#task1 ?ex:hasTask .ex:Task label}
|
|
175
|
+
- Implement parser {+#task2 ?ex:hasTask .ex:Task label}
|
|
176
|
+
- Write documentation {=#task3 ?ex:hasTask .ex:Task label}
|
|
177
|
+
with a subtask of {}
|
|
178
|
+
- API reference {+#subtask3a ?ex:subTask .ex:Task label}
|
|
179
|
+
|
|
180
|
+
# Tasks
|
|
181
|
+
|
|
182
|
+
**Design schema** {=#task1} is [ready] {?ex:status +ex:done}, **parser** {=#task2} is also [done] {?ex:status +ex:done}, but **documentation** {=#task3} is still [in process] {?ex:status +ex:in-process} - we are starting documenting the **API** {=#subtask3a} - it's still a [to do] {?ex:status +ex:todo}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Example 3
|
|
186
|
+
|
|
187
|
+
```plaintext
|
|
188
|
+
A lab observation recording a firmware update and resulting system state performed by Dr. Lena Ortiz.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```ttl
|
|
192
|
+
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
|
|
193
|
+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
|
|
194
|
+
@prefix prov: <http://www.w3.org/ns/prov#>.
|
|
195
|
+
@prefix lab: <tag:lab@example.com,2026:>.
|
|
196
|
+
|
|
197
|
+
lab:obsLab1 a rdf:Statement, prov:Entity;
|
|
198
|
+
rdf:subject lab:calibBot;
|
|
199
|
+
rdf:predicate lab:performedUpdate;
|
|
200
|
+
rdf:object lab:spectrometerFW;
|
|
201
|
+
lab:confidence 0.97;
|
|
202
|
+
prov:wasGeneratedBy lab:actLab1.
|
|
203
|
+
lab:obsLab2 a rdf:Statement, prov:Entity;
|
|
204
|
+
rdf:subject lab:spectrometerFW;
|
|
205
|
+
rdf:predicate lab:hasStatus;
|
|
206
|
+
rdf:object lab:stable;
|
|
207
|
+
lab:confidence 0.90;
|
|
208
|
+
prov:wasGeneratedBy lab:actLab1.
|
|
209
|
+
lab:actLab1 a prov:Activity;
|
|
210
|
+
prov:wasAssociatedWith lab:lenaOrtiz;
|
|
211
|
+
prov:endedAtTime "2026-02-18T06:42:00Z"^^xsd:dateTime.
|
|
212
|
+
lab:lenaOrtiz a prov:Agent.
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
```mdld
|
|
217
|
+
[lab] <tag:lab@example.com,2026:>
|
|
218
|
+
|
|
219
|
+
# Lab journal
|
|
220
|
+
|
|
221
|
+
## System update {=lab:obsLab1 .rdf:Statement .prov:Entity}
|
|
222
|
+
|
|
223
|
+
While reviewing the overnight logs, I confirmed that [the calibration bot] {+lab:calibBot ?rdf:subject} successfully [updated] {+lab:performedUpdate ?rdf:predicate} the [spectrometer firmware] {+lab:spectrometerFW ?rdf:object}.
|
|
224
|
+
The change looked routine, but I still recorded the provenance carefully. I assign a confidence of [0.97] {lab:confidence ^^xsd:decimal} to this observation.
|
|
225
|
+
|
|
226
|
+
## System status {=lab:obsLab2 .rdf:Statement .prov:Entity}
|
|
227
|
+
|
|
228
|
+
I also noted that the [spectrometer firmware] {+lab:spectrometerFW ?rdf:subject} remained in [stable condition] {+lab:stable ?rdf:object} according to the [reported status] {+lab:hasStatus ?rdf:predicate}. I assign a confidence of [0.90] {lab:confidence ^^xsd:decimal} to this observation.
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
## Verification activity {=lab:actLab1 .prov:Activity}
|
|
232
|
+
|
|
233
|
+
Has 2 observations stated:
|
|
234
|
+
- System update {+lab:obsLab1 !prov:wasGeneratedBy}
|
|
235
|
+
- System status {+lab:obsLab2 !prov:wasGeneratedBy}
|
|
236
|
+
|
|
237
|
+
The check was performed by [Dr. Lena Ortiz] {+lab:lenaOrtiz .prov:Agent ?prov:wasAssociatedWith} during the early shift, finishing at [2026-02-18T06:42:00Z] {prov:endedAtTime ^^xsd:dateTime}.
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
### Example 4
|
|
242
|
+
|
|
243
|
+
```plaintext
|
|
244
|
+
A product validation SHACL shape defining mandatory name and positive price.
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
```ttl
|
|
248
|
+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
249
|
+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
|
|
250
|
+
@prefix sh: <http://www.w3.org/ns/shacl#>.
|
|
251
|
+
@prefix ex: <http://example.org/>.
|
|
252
|
+
|
|
253
|
+
ex:ProductValidationShape a sh:NodeShape;
|
|
254
|
+
rdfs:label "Product Validation Shape";
|
|
255
|
+
sh:targetClass ex:Product;
|
|
256
|
+
sh:property <http://example.org/#productName>, <http://example.org/#productPrice>.
|
|
257
|
+
<http://example.org/#productName> a sh:PropertyShape;
|
|
258
|
+
sh:path rdfs:label;
|
|
259
|
+
sh:minCount 1^^xsd:integer;
|
|
260
|
+
sh:maxCount 1^^xsd:integer;
|
|
261
|
+
sh:message "Product must have exactly one label".
|
|
262
|
+
<http://example.org/#productPrice> a sh:PropertyShape;
|
|
263
|
+
sh:path ex:price;
|
|
264
|
+
sh:message "Product price must be positive";
|
|
265
|
+
sh:minInclusive 0.01^^xsd:decimal.
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
```mdld
|
|
269
|
+
[ex] <http://example.org/>
|
|
270
|
+
|
|
271
|
+
The **Product Validation Shape** {=ex:ProductValidationShape .sh:NodeShape label} targets all [Products] {+ex:Product ?sh:targetClass} to validate core product requirements.
|
|
272
|
+
|
|
273
|
+
**Product Name Rule** {=ex:#productName .sh:PropertyShape ?sh:property} requires the [label] {+label ?sh:path} property to have exactly [1] {sh:minCount sh:maxCount ^^xsd:integer} value.
|
|
274
|
+
|
|
275
|
+
> Product must have exactly one label {sh:message}
|
|
276
|
+
|
|
277
|
+
We MUST repeat the subject for the second propertyShape to connect to the shape via ?sh:property - always rememeber about subject chaining:
|
|
278
|
+
|
|
279
|
+
{=ex:ProductValidationShape}
|
|
280
|
+
|
|
281
|
+
**Product Price Rule** {=ex:#productPrice .sh:PropertyShape ?sh:property} that requires the [price] {+ex:price ?sh:path} property to be at least [0.01] {sh:minInclusive ^^xsd:decimal}
|
|
282
|
+
|
|
283
|
+
> Product price must be positive {sh:message}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## ❌ Invalid patterns
|
|
287
|
+
|
|
288
|
+
INVALID:
|
|
289
|
+
`{ex:energy "8"^^xsd:integer}`
|
|
290
|
+
|
|
291
|
+
VALID:
|
|
292
|
+
`[8] {ex:energy ^^xsd:integer}`
|
|
293
|
+
|
|
294
|
+
## Pattern Summary:
|
|
295
|
+
|
|
296
|
+
Literal:
|
|
297
|
+
[value] {predicate}
|
|
298
|
+
|
|
299
|
+
Object:
|
|
300
|
+
[value] {+IRI ?predicate}
|
|
301
|
+
|
|
302
|
+
Statement:
|
|
303
|
+
{=stmt .rdf:Statement}
|
|
304
|
+
[A] {+S ?rdf:subject} [B] {+P ?rdf:predicate} [C] {+O ?rdf:object}
|
|
305
|
+
|
|
306
|
+
Activity:
|
|
307
|
+
{=act .prov:Activity}
|
|
308
|
+
[Agent] {+A .prov:Agent ?prov:wasAssociatedWith}
|
|
309
|
+
[time] {prov:endedAtTime ^^xsd:dateTime}
|