mdld-parse 0.9.3 → 0.9.5
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 +4 -3
- package/dist/README.md +4 -3
- package/dist/docs/API.md +3 -1
- package/dist/docs/Guide.md +660 -166
- package/dist/docs/LiterateRDF.md +472 -0
- package/dist/docs/Nostr.md +544 -0
- package/dist/docs/Parser.md +57 -1
- package/dist/docs/guide-m.md +56 -0
- package/dist/docs/one-page.md +322 -0
- package/dist/docs/primary-subject.md +64 -13
- package/dist/examples/Status-SHACL.md +8 -10
- package/dist/examples/demo/journal.md +110 -9
- package/dist/examples/demo/minimal.md +18 -6
- package/dist/examples/demo/project.md +90 -7
- package/dist/examples/demo/prov.md +107 -0
- package/dist/examples/demo/rdf.md +69 -0
- package/dist/examples/demo/recipe.md +79 -15
- package/dist/examples/demo/research.md +110 -30
- package/dist/examples/demo/shacl.md +161 -0
- package/dist/examples/demo/space-mission.md +109 -28
- package/dist/examples/demo/tasks.md +175 -0
- package/dist/examples/demo/xsd.md +91 -0
- package/dist/index.html +686 -260
- package/dist/index.js +474 -248
- package/dist/spec/Spec-compact.md +13 -8
- package/dist/spec/Spec-ultra.md +14 -3
- package/dist/spec/Spec.md +68 -20
- package/package.json +2 -2
- package/dist/examples/prov-o.md +0 -2367
- package/dist/examples/rdf.md +0 -827
- package/dist/examples/shacl.md +0 -3399
package/dist/docs/Guide.md
CHANGED
|
@@ -1,322 +1,816 @@
|
|
|
1
|
-
# MD-LD
|
|
1
|
+
# MD-LD Authoring Guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MD-LD is Markdown with semantic annotations. You write normal prose — notes, plans, journals, documentation — and sprinkle in `{...}` curly-brace hints that tell a parser how to build a knowledge graph from your text. Everything outside `{...}` is free-form and ignored by the graph. You don't have to annotate everything — only what you want in the graph.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
Add `{...}` → you get an RDF graph.
|
|
7
|
-
Delete `{...}` → plain Markdown remains.
|
|
5
|
+
Think of it like highlighters. You pick a color scheme first (prefix declarations), then highlight the parts of your text that carry meaning.
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Your First Note
|
|
10
|
+
|
|
11
|
+
Start with plain Markdown. This is always valid MD-LD — it just produces no graph data:
|
|
12
|
+
|
|
13
|
+
```md
|
|
14
|
+
# Alice's Journal
|
|
15
|
+
|
|
16
|
+
Hi! My name is Alice Smith. This is my personal journal.
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Now add your first annotation. Two things happen: you declare a prefix, and you tag the heading as a named node with a type and a label:
|
|
20
|
+
|
|
21
|
+
```md
|
|
22
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
23
|
+
|
|
24
|
+
# Alice's Journal
|
|
25
|
+
|
|
26
|
+
## Alice {=my:alice .prov:Person label}
|
|
27
|
+
|
|
28
|
+
Hi! My name is Alice Smith. This is my personal journal.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
That one annotation `{=my:alice .prov:Person label}` did three things:
|
|
32
|
+
- `=my:alice` — declared this heading as a named node (the *subject*)
|
|
33
|
+
- `.prov:Person` — typed it as a Person
|
|
34
|
+
- `label` — used the heading text "Alice" as its display label (`rdfs:label`)
|
|
35
|
+
|
|
36
|
+
The generated triples:
|
|
37
|
+
|
|
38
|
+
```ttl
|
|
39
|
+
@prefix my: <tag:alice.smith@example.org,2026:>.
|
|
40
|
+
@prefix prov: <http://www.w3.org/ns/prov#>.
|
|
41
|
+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
42
|
+
|
|
43
|
+
my:alice a prov:Person;
|
|
44
|
+
rdfs:label "Alice".
|
|
45
|
+
```
|
|
10
46
|
|
|
11
47
|
---
|
|
12
48
|
|
|
13
|
-
##
|
|
49
|
+
## 2. Your Personal IRI — the `tag:` Pattern
|
|
14
50
|
|
|
15
|
-
|
|
51
|
+
Every node in a knowledge graph needs a unique identifier — an IRI. If you have a website, use its URL. If you don't, use the RFC 4151 `tag:` scheme. It's yours to own with just an email address or domain:
|
|
16
52
|
|
|
17
53
|
```
|
|
18
|
-
|
|
54
|
+
tag:alice.smith@example.org,2026:
|
|
55
|
+
│ │ └─ your subspace starts here
|
|
56
|
+
│ └──── year you controlled this email
|
|
57
|
+
└─────────────────────────── your authority (email or domain)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Declare it once at the top of your document as a prefix:
|
|
61
|
+
|
|
62
|
+
```md
|
|
63
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
19
64
|
```
|
|
20
65
|
|
|
21
|
-
|
|
66
|
+
Then use it with the short form anywhere:
|
|
67
|
+
|
|
68
|
+
| Short form | Expands to |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `my:alice` | `tag:alice.smith@example.org,2026:alice` |
|
|
71
|
+
| `my:journal/2026-05-06` | `tag:alice.smith@example.org,2026:journal/2026-05-06` |
|
|
72
|
+
| `my:place/central-park` | `tag:alice.smith@example.org,2026:place/central-park` |
|
|
22
73
|
|
|
23
|
-
|
|
74
|
+
You can also add a sub-prefix for a specific domain of your notes:
|
|
24
75
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
| **L** | literal text (from the attached Markdown span/block) |
|
|
76
|
+
```md
|
|
77
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
78
|
+
[j] <my:journal/>
|
|
79
|
+
```
|
|
30
80
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
81
|
+
Now `j:2026-05-06` expands to `tag:alice.smith@example.org,2026:journal/2026-05-06`. Prefix folding — short prefixes built on top of other prefixes — keeps long IRIs readable.
|
|
82
|
+
|
|
83
|
+
**Built-in prefixes** (no declaration needed):
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns#
|
|
87
|
+
rdfs http://www.w3.org/2000/01/rdf-schema#
|
|
88
|
+
xsd http://www.w3.org/2001/XMLSchema#
|
|
89
|
+
sh http://www.w3.org/ns/shacl#
|
|
90
|
+
prov http://www.w3.org/ns/prov#
|
|
91
|
+
```
|
|
34
92
|
|
|
35
93
|
---
|
|
36
94
|
|
|
37
|
-
##
|
|
95
|
+
## 3. Saying Things About Things — Literals
|
|
96
|
+
|
|
97
|
+
Once you've set a subject with `{=...}`, every annotated value below it belongs to that subject until you change it. The basic pattern is:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
[value] {predicate}
|
|
101
|
+
```
|
|
38
102
|
|
|
39
|
-
|
|
103
|
+
The `[value]` is the *carrier* — it can be a bracketed span, bold text, a code span, a heading, a list item, or a blockquote. The `{predicate}` names the property.
|
|
40
104
|
|
|
41
105
|
```md
|
|
42
|
-
[
|
|
106
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
107
|
+
|
|
108
|
+
## Alice {=my:alice .prov:Person label}
|
|
43
109
|
|
|
44
|
-
|
|
110
|
+
Age: [34] {my:age ^^xsd:integer}
|
|
111
|
+
City: [Berlin] {my:city @de}
|
|
112
|
+
Bio: **Loves hiking and graph databases.** {my:bio @en}
|
|
45
113
|
```
|
|
46
114
|
|
|
47
|
-
|
|
115
|
+
Generates:
|
|
48
116
|
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
117
|
+
```ttl
|
|
118
|
+
my:alice a prov:Person;
|
|
119
|
+
rdfs:label "Alice";
|
|
120
|
+
my:age "34"^^xsd:integer;
|
|
121
|
+
my:city "Berlin"@de;
|
|
122
|
+
my:bio "Loves hiking and graph databases."@en.
|
|
53
123
|
```
|
|
54
124
|
|
|
55
|
-
**
|
|
125
|
+
**Carriers at a glance:**
|
|
56
126
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
127
|
+
| Syntax | Example | When to use |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| `[text]` | `[34]` | Inline spans, values mid-sentence |
|
|
130
|
+
| `**text**` | `**Alice**` | Bold emphasis on a value |
|
|
131
|
+
| `` `text` `` | `` `v1.2.0` `` | Code/version values |
|
|
132
|
+
| `# text` | `# Journal` | Heading as value |
|
|
133
|
+
| `- text` | `- Design` | List item as value |
|
|
134
|
+
| `> text` | `> Must be unique` | Block quote as message/note |
|
|
135
|
+
| ` ```text``` ` | code block | Multi-line code or raw data |
|
|
136
|
+
|
|
137
|
+
**Datatype shortcuts:**
|
|
138
|
+
|
|
139
|
+
```md
|
|
140
|
+
[2026-05-06] {my:date ^^xsd:date}
|
|
141
|
+
[14:30:00Z] {my:time ^^xsd:time}
|
|
142
|
+
[42] {my:count ^^xsd:integer}
|
|
143
|
+
[3.14] {my:ratio ^^xsd:decimal}
|
|
144
|
+
[true] {my:active ^^xsd:boolean}
|
|
145
|
+
```
|
|
60
146
|
|
|
61
147
|
---
|
|
62
148
|
|
|
63
|
-
|
|
149
|
+
## 4. Connecting Things — Object Properties
|
|
64
150
|
|
|
65
|
-
|
|
151
|
+
To link two nodes together, use `{+IRI ?predicate}` on the carrier that names the target:
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
[label for target] {+target:iri ?predicate}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The `+` introduces the *object node*. The `?` marks a forward object property (subject → object).
|
|
66
158
|
|
|
67
159
|
```md
|
|
68
|
-
|
|
69
|
-
|
|
160
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
161
|
+
|
|
162
|
+
## Alice {=my:alice .prov:Person label}
|
|
70
163
|
|
|
71
|
-
|
|
72
|
-
[
|
|
73
|
-
[p] <my:property:>
|
|
74
|
-
[c] <my:class:>
|
|
164
|
+
Alice knows [Bob] {+my:bob ?my:knows}.
|
|
165
|
+
She lives near [Central Park] {+my:central-park ?my:livesNear}.
|
|
75
166
|
|
|
76
|
-
|
|
77
|
-
|
|
167
|
+
## Bob {=my:bob .prov:Person label}
|
|
168
|
+
|
|
169
|
+
## Central Park {=my:central-park .prov:Location label}
|
|
78
170
|
```
|
|
79
171
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
172
|
+
Generates:
|
|
173
|
+
|
|
174
|
+
```ttl
|
|
175
|
+
my:alice a prov:Person;
|
|
176
|
+
rdfs:label "Alice";
|
|
177
|
+
my:knows my:bob;
|
|
178
|
+
my:livesNear my:central-park.
|
|
179
|
+
my:bob a prov:Person;
|
|
180
|
+
rdfs:label "Bob".
|
|
181
|
+
my:central-park a prov:Location;
|
|
182
|
+
rdfs:label "Central Park".
|
|
183
|
+
```
|
|
84
184
|
|
|
85
|
-
|
|
185
|
+
Each node is defined exactly once, in its own heading. The `{+my:bob ?my:knows}` annotation only asserts the link — type and label belong on Bob's own section. This keeps the graph clean with no duplicate triples.
|
|
86
186
|
|
|
87
|
-
|
|
187
|
+
### Reverse Links — `!predicate`
|
|
88
188
|
|
|
89
|
-
|
|
189
|
+
Sometimes it's more natural to write the relationship from the other direction. Use `!` for a reverse property — the triple goes *from* the object *to* the current subject:
|
|
90
190
|
|
|
91
|
-
|
|
191
|
+
```md
|
|
192
|
+
## Cookbook {=my:cookbook .my:Collection label}
|
|
92
193
|
|
|
93
|
-
|
|
194
|
+
Recipes in this collection:
|
|
94
195
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
* `` `code` {...}``
|
|
196
|
+
- Apple Pie {+my:apple-pie !my:partOf}
|
|
197
|
+
- Peach Pie {+my:peach-pie !my:partOf}
|
|
98
198
|
|
|
99
|
-
|
|
199
|
+
## Apple Pie {=my:apple-pie .my:Recipe label}
|
|
100
200
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
* Blockquotes
|
|
104
|
-
* Code blocks (fence with `{...}`)
|
|
201
|
+
## Peach Pie {=my:peach-pie .my:Recipe label}
|
|
202
|
+
```
|
|
105
203
|
|
|
106
|
-
|
|
204
|
+
This writes `my:apple-pie my:partOf my:cookbook` — the arrow points from the list item back to the collection. Each recipe is then defined in its own section with type and label there.
|
|
107
205
|
|
|
108
206
|
---
|
|
109
207
|
|
|
110
|
-
##
|
|
208
|
+
## 5. Fragment IRIs — Structuring Within a Document
|
|
209
|
+
|
|
210
|
+
Fragments (`#section`) let you create multiple related nodes inside one document without long IRIs:
|
|
211
|
+
|
|
212
|
+
```md
|
|
213
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
214
|
+
|
|
215
|
+
# Project Alpha {=my:ProjectAlpha .my:Project label}
|
|
111
216
|
|
|
112
|
-
|
|
217
|
+
- Design {+#task-design ?my:hasTask .my:Task label}
|
|
218
|
+
- Build {+#task-build ?my:hasTask .my:Task label}
|
|
219
|
+
- Ship {+#task-ship ?my:hasTask .my:Task label}
|
|
113
220
|
|
|
114
|
-
|
|
115
|
-
| ----- | ------- |
|
|
116
|
-
| `p` | `S → L` |
|
|
117
|
-
| `?p` | `S → O` |
|
|
118
|
-
| `!p` | `O → S` |
|
|
221
|
+
## Design Task {=#task-design}
|
|
119
222
|
|
|
120
|
-
|
|
223
|
+
Status: [done] {my:status}
|
|
121
224
|
|
|
122
|
-
|
|
225
|
+
## Build Task {=#task-build}
|
|
226
|
+
|
|
227
|
+
Status: [in-progress] {my:status}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
`{=#task-design}` sets the subject to `my:ProjectAlpha#task-design` (it appends the fragment to the current base IRI). `{+#task-design}` references that same IRI as an object.
|
|
231
|
+
|
|
232
|
+
When you need to return to the parent node mid-document, just reset the subject:
|
|
123
233
|
|
|
124
234
|
```md
|
|
125
|
-
|
|
235
|
+
{=my:ProjectAlpha}
|
|
126
236
|
|
|
127
|
-
[
|
|
128
|
-
[Walnut] {+alice:walnut ?hasIngredient}
|
|
129
|
-
[Recipe](https://en.wikipedia.org/wiki/Recipe) {!hasPart}
|
|
237
|
+
[3] {my:taskCount ^^xsd:integer}
|
|
130
238
|
```
|
|
131
239
|
|
|
132
|
-
|
|
240
|
+
Use `{=}` (bare) to clear the subject entirely — subsequent annotations will have no subject until the next `{=...}`.
|
|
133
241
|
|
|
134
242
|
---
|
|
135
243
|
|
|
136
|
-
##
|
|
244
|
+
## 6. The Three Predicate Forms
|
|
245
|
+
|
|
246
|
+
Every annotation uses one of three forms:
|
|
137
247
|
|
|
138
|
-
|
|
248
|
+
| Form | Meaning | Edge | Example |
|
|
249
|
+
|---|---|---|---|
|
|
250
|
+
| `p` | Literal property | S → literal | `[Alice] {my:name}` |
|
|
251
|
+
| `?p` | Object property | S → O | `[Bob] {+my:bob ?my:knows}` |
|
|
252
|
+
| `!p` | Reverse property | O → S | `[Tag] {+my:tag !my:taggedIn}` |
|
|
253
|
+
|
|
254
|
+
You can combine multiple predicates in one annotation:
|
|
139
255
|
|
|
140
256
|
```md
|
|
141
|
-
|
|
142
|
-
[Delicious bread] {description @en}
|
|
257
|
+
## Alice {=my:alice .prov:Person label}
|
|
143
258
|
```
|
|
144
259
|
|
|
145
|
-
|
|
260
|
+
This sets subject, types it, and assigns a label — all at once. Order within `{...}` is flexible.
|
|
146
261
|
|
|
147
262
|
---
|
|
148
263
|
|
|
149
|
-
##
|
|
264
|
+
## 7. A Journal Entry — Putting It Together
|
|
150
265
|
|
|
151
|
-
|
|
266
|
+
Here's a complete personal journal note using everything above:
|
|
152
267
|
|
|
153
268
|
```md
|
|
154
|
-
[
|
|
269
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
270
|
+
[j] <my:journal/>
|
|
271
|
+
|
|
272
|
+
# 2026-05-06 {=j:2026-05-06 .j:Entry j:date ^^xsd:date}
|
|
273
|
+
|
|
274
|
+
## A good walk {label}
|
|
275
|
+
|
|
276
|
+
Mood: [happy] {j:mood}
|
|
277
|
+
Energy: [8] {j:energy ^^xsd:integer}
|
|
155
278
|
|
|
156
|
-
[
|
|
279
|
+
Met [Bob] {+my:bob ?j:met} at [Central Park] {+my:central-park ?j:location}.
|
|
280
|
+
The weather was [sunny] {j:weather}.
|
|
157
281
|
```
|
|
158
282
|
|
|
159
|
-
|
|
283
|
+
Generated triples:
|
|
284
|
+
|
|
285
|
+
```ttl
|
|
286
|
+
j:2026-05-06 a j:Entry;
|
|
287
|
+
j:date "2026-05-06"^^xsd:date;
|
|
288
|
+
rdfs:label "A good walk";
|
|
289
|
+
j:mood "happy";
|
|
290
|
+
j:energy "8"^^xsd:integer;
|
|
291
|
+
j:met my:bob;
|
|
292
|
+
j:location my:central-park;
|
|
293
|
+
j:weather "sunny".
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
`my:bob` and `my:central-park` are referenced by IRI. Their type and label belong in their own definitions — in a people file, a places file, or wherever you keep them. A journal entry only records what happened, not who Bob is.
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## 8. Core Ontologies — Vocabulary You Can Reuse
|
|
301
|
+
|
|
302
|
+
You don't have to invent every predicate. Five vocabularies are built into MD-LD and cover most needs. Here is what each one actually contributes.
|
|
303
|
+
|
|
304
|
+
### rdf — The Bedrock
|
|
305
|
+
|
|
306
|
+
`rdf` provides the primitives everything else is built on.
|
|
307
|
+
|
|
308
|
+
**`rdf:type`** — written as `.Class` in MD-LD — declares what kind of thing a node is. It is the most-used annotation in every graph:
|
|
160
309
|
|
|
161
310
|
```md
|
|
162
|
-
|
|
311
|
+
## Alice {=my:alice .prov:Person}
|
|
312
|
+
## Report {=my:report .prov:Entity}
|
|
313
|
+
## Run {=my:run .prov:Activity}
|
|
163
314
|
```
|
|
164
315
|
|
|
165
|
-
|
|
316
|
+
**`rdf:Property`** — the class of all properties. When you define your own predicate in a vocabulary, type it `.rdf:Property`.
|
|
166
317
|
|
|
167
|
-
|
|
318
|
+
**`rdf:Statement`** with `rdf:subject`, `rdf:predicate`, `rdf:object` — reification. Lets you make a node *about* a triple, so you can attach metadata (confidence, source, timestamp) to a relationship itself. See §9.
|
|
319
|
+
|
|
320
|
+
**`rdf:Bag` / `rdf:Seq` / `rdf:Alt`** — typed containers. `Bag` is unordered, `Seq` is ordered, `Alt` is a set of alternatives. Use them when the container type carries meaning. For a simple untyped collection, `rdfs:Container` is enough.
|
|
168
321
|
|
|
169
|
-
|
|
322
|
+
**`rdf:List`** with `rdf:first` / `rdf:rest` / `rdf:nil` — a linked-list structure required by SHACL's `sh:in` (enumeration) and `sh:and` (logical combination). You rarely author these by hand outside of SHACL shapes.
|
|
170
323
|
|
|
171
|
-
|
|
324
|
+
**`rdf:value`** — an idiomatic property for the "main value" of a structured node, used in qualified PROV-O patterns and compound literals.
|
|
325
|
+
|
|
326
|
+
### rdfs — Schema and Display
|
|
327
|
+
|
|
328
|
+
`rdfs` gives you the vocabulary for naming, describing, and organising your data.
|
|
329
|
+
|
|
330
|
+
**`rdfs:label`** (written as bare `label`) — the display name of any node. Every named node should have one:
|
|
172
331
|
|
|
173
332
|
```md
|
|
174
|
-
|
|
333
|
+
## Alice {=my:alice label}
|
|
334
|
+
## Central Park {=my:place/central-park label}
|
|
335
|
+
```
|
|
175
336
|
|
|
176
|
-
|
|
337
|
+
**`rdfs:comment`** (written as bare `comment`) — a human-readable description of a node, typically used in vocabulary definitions:
|
|
177
338
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
- Water {+alice:water ?member .alice:Ingredient name}
|
|
339
|
+
```md
|
|
340
|
+
> A person who attended the event. {comment @en}
|
|
181
341
|
```
|
|
182
342
|
|
|
183
|
-
|
|
343
|
+
**`rdfs:Class`** (written as `.Class`) — declares that a node *is itself a class*, i.e. a category other nodes can belong to. Different from `.SomeClass` which says a node *is an instance of* SomeClass:
|
|
344
|
+
|
|
345
|
+
```md
|
|
346
|
+
## Person {=my:Person .Class label}
|
|
347
|
+
## Location {=my:Location .Class label}
|
|
348
|
+
```
|
|
184
349
|
|
|
185
|
-
|
|
350
|
+
**`rdfs:subClassOf`** — builds class hierarchies. `prov:Person rdfs:subClassOf prov:Agent` means every Person is also an Agent:
|
|
186
351
|
|
|
187
|
-
**✅ DO - Items with explicit subjects emit semantics:**
|
|
188
352
|
```md
|
|
189
|
-
|
|
190
|
-
|
|
353
|
+
## Employee {=my:Employee .Class label}
|
|
354
|
+
[Person] {+my:Person ?subClassOf}
|
|
191
355
|
```
|
|
192
356
|
|
|
357
|
+
**`rdfs:subPropertyOf`** — builds property hierarchies. Used in vocabulary authoring.
|
|
193
358
|
|
|
194
|
-
|
|
359
|
+
**`rdfs:domain` / `rdfs:range`** — document what class a property applies to and what type its values should be. Used in vocabulary authoring, not in instance data.
|
|
195
360
|
|
|
196
|
-
|
|
361
|
+
**`rdfs:Container` / `rdfs:member`** — an open-ended collection. Any node typed `.Container` is a bag; `?member` adds items to it:
|
|
197
362
|
|
|
198
|
-
**✅ Nested Lists (Pure Structure)**
|
|
199
363
|
```md
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
364
|
+
## Places I've been {=my:places .Container label}
|
|
365
|
+
|
|
366
|
+
- Central Park {+my:place/central-park ?member}
|
|
367
|
+
- Tompkins Square {+my:place/tompkins ?member}
|
|
203
368
|
```
|
|
204
369
|
|
|
205
|
-
|
|
370
|
+
The reverse form — an item declaring which container it belongs to — uses `!member`:
|
|
371
|
+
|
|
206
372
|
```md
|
|
207
|
-
|
|
373
|
+
## Central Park {=my:place/central-park .prov:Location label}
|
|
208
374
|
|
|
209
|
-
|
|
210
|
-
[*Important*] {priority .Important}
|
|
375
|
+
In collection: [places] {+my:places !member}
|
|
211
376
|
```
|
|
212
377
|
|
|
213
|
-
|
|
378
|
+
**`rdfs:seeAlso` / `rdfs:isDefinedBy`** — link a node to related or defining resources. `isDefinedBy` is a sub-property of `seeAlso` and points to the authoritative specification.
|
|
214
379
|
|
|
215
|
-
|
|
380
|
+
### prov — Who Did What When
|
|
216
381
|
|
|
217
|
-
|
|
382
|
+
PROV-O models the three building blocks of provenance: **entities** (things), **activities** (events that happen over time), and **agents** (people, software, organisations that bear responsibility).
|
|
218
383
|
|
|
219
|
-
|
|
384
|
+
The three core classes:
|
|
220
385
|
|
|
221
386
|
```md
|
|
222
|
-
|
|
387
|
+
## Report {=my:report .prov:Entity label}
|
|
388
|
+
## Analysis run {=my:run .prov:Activity label}
|
|
389
|
+
## Alice {=my:alice .prov:Person label} ← prov:Person is a subclass of prov:Agent
|
|
390
|
+
```
|
|
223
391
|
|
|
224
|
-
|
|
392
|
+
The starting-point properties connect them:
|
|
225
393
|
|
|
226
|
-
|
|
394
|
+
```md
|
|
395
|
+
## Analysis run {=my:run .prov:Activity label}
|
|
227
396
|
|
|
228
|
-
|
|
397
|
+
Started: [2026-05-06T09:00:00Z] {prov:startedAtTime ^^xsd:dateTime}
|
|
398
|
+
Ended: [2026-05-06T09:45:00Z] {prov:endedAtTime ^^xsd:dateTime}
|
|
399
|
+
By: [Alice] {+my:alice ?prov:wasAssociatedWith}
|
|
400
|
+
Used: [dataset] {+my:dataset ?prov:used}
|
|
401
|
+
Made: [report] {+my:report ?prov:generated}
|
|
402
|
+
```
|
|
229
403
|
|
|
230
|
-
|
|
404
|
+
Entity-to-entity chains use `prov:wasDerivedFrom` (when the activity is unknown or irrelevant) and `prov:wasAttributedTo` (which agent is responsible for an entity):
|
|
231
405
|
|
|
232
|
-
|
|
406
|
+
```md
|
|
407
|
+
## Bar chart {=my:chart .prov:Entity label}
|
|
408
|
+
|
|
409
|
+
Derived from [regional stats] {+my:stats ?prov:wasDerivedFrom}.
|
|
410
|
+
Attributed to [Alice] {+my:alice ?prov:wasAttributedTo}.
|
|
233
411
|
```
|
|
234
412
|
|
|
235
|
-
|
|
413
|
+
`prov:actedOnBehalfOf` records delegation — a software agent acting on behalf of a person:
|
|
236
414
|
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
tag:alice@example.com,2026:walnut-bread#step-2 a schema:HowToStep ; rdfs:label "Baking" ; schema:text "Bake for 45 minutes" .
|
|
415
|
+
```md
|
|
416
|
+
## Bot {=my:bot .prov:SoftwareAgent label}
|
|
417
|
+
[Alice] {+my:alice ?prov:actedOnBehalfOf}
|
|
241
418
|
```
|
|
242
419
|
|
|
243
|
-
|
|
420
|
+
`prov:wasInformedBy` connects two activities without specifying the intermediate entity:
|
|
244
421
|
|
|
245
|
-
|
|
422
|
+
```md
|
|
423
|
+
## Illustration {=my:illustrate .prov:Activity label}
|
|
424
|
+
[aggregation run] {+my:aggregate ?prov:wasInformedBy}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
All of these have *qualified* forms (via `prov:qualifiedGeneration`, `prov:qualifiedUsage`, `prov:qualifiedAssociation`, etc.) that let you attach additional metadata to a relationship using an intermediate node. The pattern is: state the simple link, then define the qualification node separately.
|
|
246
428
|
|
|
247
|
-
|
|
429
|
+
### xsd — Typed Literals
|
|
430
|
+
|
|
431
|
+
`xsd` datatypes give literals machine-readable types. Without a datatype, everything is a plain string.
|
|
248
432
|
|
|
249
433
|
```md
|
|
250
|
-
|
|
434
|
+
[2026-05-06] {my:date ^^xsd:date}
|
|
435
|
+
[2026-05-06T09:00:00Z] {my:timestamp ^^xsd:dateTime}
|
|
436
|
+
[42] {my:count ^^xsd:integer}
|
|
437
|
+
[3.14] {my:ratio ^^xsd:decimal}
|
|
438
|
+
[true] {my:active ^^xsd:boolean}
|
|
439
|
+
[P1Y6M] {my:duration ^^xsd:duration}
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
### sh — Validation Shapes (SHACL)
|
|
443
|
+
|
|
444
|
+
SHACL lets you declare what valid data looks like. The full pattern is: one `sh:NodeShape` declares all its `sh:property` links upfront, then each `sh:PropertyShape` is defined in its own section:
|
|
445
|
+
|
|
446
|
+
```md
|
|
447
|
+
[my] <tag:you@example.com,2026:>
|
|
448
|
+
|
|
449
|
+
## Person Shape {=my:PersonShape .sh:NodeShape label}
|
|
450
|
+
|
|
451
|
+
Validates all [Person] {+my:Person ?sh:targetClass} nodes with exactly one [name] {+my:PersonShape-name ?sh:property sh:name} and at least one [email] {+my:PersonShape-email ?sh:property sh:name}.
|
|
452
|
+
|
|
453
|
+
### Name rule {=my:PersonShape-name .sh:PropertyShape}
|
|
454
|
+
|
|
455
|
+
Path: [label] {+label ?sh:path}
|
|
456
|
+
Required: [1] {sh:minCount sh:maxCount ^^xsd:integer}
|
|
457
|
+
|
|
458
|
+
> Every person must have exactly one name. {sh:message}
|
|
459
|
+
|
|
460
|
+
### Email rule {=my:PersonShape-email .sh:PropertyShape}
|
|
461
|
+
|
|
462
|
+
Path: [my:email] {+my:email ?sh:path}
|
|
463
|
+
Required: [1] {sh:minCount ^^xsd:integer}
|
|
464
|
+
|
|
465
|
+
> Every person must have an email address. {sh:message}
|
|
251
466
|
```
|
|
252
467
|
|
|
253
|
-
|
|
468
|
+
Targeting options: `?sh:targetClass` (all instances of a class), `?sh:targetNode` (one specific node), `?sh:targetSubjectsOf` (nodes that use a given predicate), `?sh:targetObjectsOf` (nodes that are objects of a given predicate).
|
|
469
|
+
|
|
470
|
+
Common constraint predicates: `sh:minCount`, `sh:maxCount`, `sh:datatype`, `sh:nodeKind`, `sh:minInclusive`, `sh:maxInclusive`, `sh:minLength`, `sh:maxLength`, `sh:pattern`, `sh:hasValue`, `sh:in`, `sh:node`, `sh:not`, `sh:message`, `sh:severity`.
|
|
254
471
|
|
|
255
472
|
---
|
|
256
473
|
|
|
257
|
-
## 9.
|
|
474
|
+
## 9. Tracking Statements — rdf:Statement
|
|
475
|
+
|
|
476
|
+
When you need to annotate a *relationship* itself (e.g. record confidence, source, or time of a claim), use `rdf:Statement`:
|
|
477
|
+
|
|
478
|
+
```md
|
|
479
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
258
480
|
|
|
259
|
-
|
|
260
|
-
[alice] <tag:alice@example.com,2026:>
|
|
481
|
+
## Observation 1 {=my:obs1 .rdf:Statement .prov:Entity label}
|
|
261
482
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
483
|
+
I observed that [Alice] {+my:alice ?rdf:subject} [knows] {+my:knows ?rdf:predicate} [Bob] {+my:bob ?rdf:object}.
|
|
484
|
+
|
|
485
|
+
Confidence: [0.95] {my:confidence ^^xsd:decimal}
|
|
486
|
+
|
|
487
|
+
Source: [field notes] {+my:field-notes ?prov:wasDerivedFrom label}
|
|
265
488
|
```
|
|
266
|
-
````
|
|
267
489
|
|
|
268
|
-
|
|
269
|
-
Language fences stay intact.
|
|
490
|
+
MD-LD automatically extracts the elevated SPO triple (`my:alice my:knows my:bob`) from this pattern alongside the reified statement node.
|
|
270
491
|
|
|
271
492
|
---
|
|
272
493
|
|
|
273
|
-
## 10.
|
|
494
|
+
## 10. Subject Decoupling — The TTL Way
|
|
495
|
+
|
|
496
|
+
Subject context persists until the next `{=...}`. The elegant way to handle multiple related nodes is to declare all of a node's *outgoing links* together — just like Turtle does — then move to each child in its own section:
|
|
274
497
|
|
|
275
498
|
```md
|
|
276
|
-
[
|
|
499
|
+
[my] <tag:alice.smith@example.org,2026:>
|
|
277
500
|
|
|
278
|
-
|
|
501
|
+
# Person Shape {=my:PersonShape .sh:NodeShape label}
|
|
279
502
|
|
|
280
|
-
|
|
281
|
-
|
|
503
|
+
Validates [Person] {+my:Person ?sh:targetClass} with rules:
|
|
504
|
+
[name] {+my:PersonShape-name ?sh:property sh:name} and
|
|
505
|
+
[email] {+my:PersonShape-email ?sh:property sh:name}.
|
|
282
506
|
|
|
283
|
-
|
|
507
|
+
## Name rule {=my:PersonShape-name .sh:PropertyShape}
|
|
508
|
+
|
|
509
|
+
Path: [label] {+label ?sh:path}
|
|
510
|
+
Required: [1] {sh:minCount ^^xsd:integer}
|
|
511
|
+
|
|
512
|
+
> Every person must have a name. {sh:message}
|
|
513
|
+
|
|
514
|
+
## Email rule {=my:PersonShape-email .sh:PropertyShape}
|
|
515
|
+
|
|
516
|
+
Path: [my:email] {+my:email ?sh:path}
|
|
517
|
+
Required: [1] {sh:minCount ^^xsd:integer}
|
|
518
|
+
|
|
519
|
+
> Every person must have an email. {sh:message}
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
The parent shape lists all its `?sh:property` links in one paragraph. Each child `sh:PropertyShape` then gets its own heading section. No resets needed — the `sh:name` value carrier on the `{+...}` block even gives each rule a human-readable name at the point of reference.
|
|
523
|
+
|
|
524
|
+
The `{=my:Shape}` reset is available when you genuinely need to add properties to a parent *after* defining children inline, but the cleaner default is: **finish a node before moving on**.
|
|
525
|
+
|
|
526
|
+
### ❌ Antipattern — typing objects inline
|
|
527
|
+
|
|
528
|
+
Avoid adding `.Class` and `label` directly onto `{+IRI}` references unless that is the *only* place the node ever appears:
|
|
529
|
+
|
|
530
|
+
```md
|
|
531
|
+
← antipattern: Bob gets typed and labelled here, and again wherever else he appears
|
|
532
|
+
Met [Bob] {+my:bob .prov:Person ?j:met label}.
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
This scatters type and label triples across every document that mentions Bob. If graphs are merged, you get duplicate assertions. Instead, define Bob once:
|
|
536
|
+
|
|
537
|
+
```md
|
|
538
|
+
← correct: the journal just records the link
|
|
539
|
+
Met [Bob] {+my:bob ?j:met}.
|
|
540
|
+
|
|
541
|
+
← Bob's definition lives in one place (people.md or similar)
|
|
542
|
+
## Bob {=my:bob .prov:Person label}
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
The one exception: when you are authoring a *vocabulary* or *ontology*, where introducing a term and its type in the same annotation is exactly right — as seen in the PROV-O example above.
|
|
284
546
|
|
|
285
547
|
---
|
|
286
548
|
|
|
287
|
-
## 11.
|
|
549
|
+
## 11. Polarity — Append-Only Editing and Retractions
|
|
550
|
+
|
|
551
|
+
Every predicate, type, and reverse link in MD-LD can be prefixed with `-` to retract it. This turns MD-LD into an append-only semantic ledger: you never delete text from a file, you write a new entry that cancels a previous assertion.
|
|
552
|
+
|
|
553
|
+
### Intra-document cancellation
|
|
554
|
+
|
|
555
|
+
When a retraction matches a positive triple *in the same document*, both cancel out — neither appears in the final graph:
|
|
556
|
+
|
|
557
|
+
```md
|
|
558
|
+
[my] <tag:you@example.com,2026:>
|
|
559
|
+
|
|
560
|
+
## Article {=my:article}
|
|
561
|
+
|
|
562
|
+
[Alice] {my:author} ← add
|
|
563
|
+
[Alice] {-my:author} ← cancel — both disappear
|
|
564
|
+
[Bob] {my:author} ← this survives
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Result: only `my:article my:author "Bob"` in `quads`. Nothing in `remove`.
|
|
568
|
+
|
|
569
|
+
### External retraction
|
|
570
|
+
|
|
571
|
+
When a retraction finds no matching positive in the current document, it becomes an *external retraction* — stored in `remove` rather than `quads`. It waits to cancel a triple from a previously merged document:
|
|
572
|
+
|
|
573
|
+
```md
|
|
574
|
+
[my] <tag:you@example.com,2026:>
|
|
575
|
+
|
|
576
|
+
## Article {=my:article}
|
|
577
|
+
|
|
578
|
+
[Alice] {-my:author} ← external retract: targets a prior document
|
|
579
|
+
[Bob] {my:author}
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
Result: `my:article my:author "Bob"` in `quads`. `my:article my:author "Alice"` in `remove`.
|
|
583
|
+
|
|
584
|
+
### Merge resolution
|
|
585
|
+
|
|
586
|
+
The `merge()` function resolves external retractions against earlier documents. This is how you implement versioning:
|
|
587
|
+
|
|
588
|
+
```md
|
|
589
|
+
v1.md → [Alice] {my:author} [Draft] {my:status}
|
|
590
|
+
v2.md → [Alice] {-my:author} [Bob] {my:author} [Draft] {-my:status} [Published] {my:status}
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
```javascript
|
|
594
|
+
const final = merge([v1, v2]);
|
|
595
|
+
// quads: author=Bob, status=Published
|
|
596
|
+
// remove: [] — all retractions resolved
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
The invariant always holds: **`quads ∩ remove = ∅`** — a triple is never simultaneously present and retracted.
|
|
600
|
+
|
|
601
|
+
### Type and link retractions
|
|
602
|
+
|
|
603
|
+
The `-` prefix works on all annotation forms:
|
|
604
|
+
|
|
605
|
+
```md
|
|
606
|
+
## Alice {=my:alice .ex:Employee -.ex:Contractor} ← add Employee, retract Contractor in same block
|
|
607
|
+
|
|
608
|
+
[project-x] {+my:project-x -?my:assignedTo} ← retract an object link
|
|
609
|
+
[my:team] {+my:team -!my:hasMember} ← retract a reverse link
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
### The ledger pattern
|
|
613
|
+
|
|
614
|
+
The real power is in append-only files — a journal, a log, a knowledge base — where every change is a new entry:
|
|
615
|
+
|
|
616
|
+
```md
|
|
617
|
+
[my] <tag:you@example.com,2026:>
|
|
618
|
+
[j] <my:journal/>
|
|
619
|
+
|
|
620
|
+
# 2026-05-01 — started project {=j:2026-05-01 .j:Entry j:date ^^xsd:date}
|
|
621
|
+
|
|
622
|
+
Project status: [planning] {+my:project ?my:documents ?j:status}
|
|
623
|
+
|
|
624
|
+
# 2026-05-10 — project kicked off {=j:2026-05-10 .j:Entry j:date ^^xsd:date}
|
|
288
625
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
* ❌ No multi-pass parsing
|
|
294
|
-
* ❌ **No semantic list propagation**
|
|
626
|
+
{=my:project}
|
|
627
|
+
[planning] {-my:status}
|
|
628
|
+
[active] {my:status}
|
|
629
|
+
```
|
|
295
630
|
|
|
296
|
-
|
|
631
|
+
Merging these two entries produces `my:project my:status "active"` only. The history of the change lives in the text; the graph holds only the current truth.
|
|
297
632
|
|
|
298
633
|
---
|
|
299
634
|
|
|
300
|
-
## 12.
|
|
635
|
+
## 12. Quick Reference
|
|
636
|
+
|
|
637
|
+
```
|
|
638
|
+
PREFIXES
|
|
639
|
+
[prefix] <IRI> declare a namespace
|
|
640
|
+
[p2] <p1:sub/> fold prefix p2 under p1 (slash for path segments)
|
|
641
|
+
|
|
642
|
+
SUBJECTS
|
|
643
|
+
{=my:node} set subject to full IRI
|
|
644
|
+
{=#fragment} set subject to current-base#fragment
|
|
645
|
+
{=} clear subject
|
|
646
|
+
|
|
647
|
+
OBJECTS
|
|
648
|
+
{+my:node ?predicate} forward link: subject → object
|
|
649
|
+
{+my:node !predicate} reverse link: object → subject
|
|
650
|
+
{+#fragment ?predicate} same with fragment IRI
|
|
651
|
+
|
|
652
|
+
TYPES
|
|
653
|
+
{.my:Class} subject rdf:type my:Class
|
|
654
|
+
|
|
655
|
+
LITERALS (value comes from the carrier)
|
|
656
|
+
[text] {predicate} literal property
|
|
657
|
+
[text] {predicate @en} with language tag
|
|
658
|
+
[text] {predicate ^^xsd:integer} with datatype
|
|
659
|
+
|
|
660
|
+
CARRIERS
|
|
661
|
+
[text] **text** `text` inline spans
|
|
662
|
+
# text - text > text block-level (heading / list / blockquote)
|
|
663
|
+
```fenced``` code block
|
|
664
|
+
|
|
665
|
+
PREDICATE FORMS
|
|
666
|
+
p S → literal [Alice] {my:name}
|
|
667
|
+
?p S → object [Bob] {+my:bob ?my:knows}
|
|
668
|
+
!p object → S [Tag] {+my:tag !my:taggedIn}
|
|
669
|
+
|
|
670
|
+
POLARITY (prefix any predicate or type with -)
|
|
671
|
+
-p retract literal [Alice] {-my:name}
|
|
672
|
+
-?p retract object link [Bob] {+my:bob -?my:knows}
|
|
673
|
+
-!p retract reverse link [Tag] {+my:tag -!my:taggedIn}
|
|
674
|
+
-.Class retract type {-.my:Draft}
|
|
675
|
+
|
|
676
|
+
COMBINING (all valid in one block)
|
|
677
|
+
{=my:node .my:Class label}
|
|
678
|
+
{+my:target ?my:rel sh:name}
|
|
679
|
+
{=my:doc -.ex:Draft .ex:Published -my:version}
|
|
680
|
+
```
|
|
301
681
|
|
|
302
|
-
|
|
682
|
+
---
|
|
303
683
|
|
|
304
|
-
|
|
305
|
-
* **Round-trip safe**
|
|
306
|
-
* **Text-preserving**
|
|
307
|
-
* **SPARQL-addressable**
|
|
684
|
+
## 13. Invariants — What Must Always Hold
|
|
308
685
|
|
|
309
|
-
|
|
686
|
+
These rules are non-negotiable. Violating them produces invalid or empty graph output:
|
|
310
687
|
|
|
311
|
-
|
|
312
|
-
*
|
|
313
|
-
|
|
314
|
-
|
|
688
|
+
- Every triple must come from an annotation `{...}`
|
|
689
|
+
- Every literal must come from a value *carrier* — never write `{predicate "value"}`
|
|
690
|
+
- `{=...}` always declares the subject; it never emits a triple by itself
|
|
691
|
+
- No blank nodes — every node must be a named IRI
|
|
692
|
+
- Do not invent prefixes; declare everything you use
|
|
693
|
+
- `label` without a prefix means `rdfs:label` — use it freely
|
|
694
|
+
- List item annotations apply only to *that* item, not the header or siblings
|
|
695
|
+
- Define nodes once — type and label belong in a node's own section, not scattered across every reference to it
|
|
315
696
|
|
|
316
|
-
|
|
697
|
+
**Invalid:**
|
|
698
|
+
```md
|
|
699
|
+
{my:age "34"^^xsd:integer} ← literal inside braces, no carrier
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
**Valid:**
|
|
703
|
+
```md
|
|
704
|
+
[34] {my:age ^^xsd:integer} ← carrier [34] holds the value
|
|
705
|
+
```
|
|
317
706
|
|
|
318
707
|
---
|
|
319
708
|
|
|
320
|
-
##
|
|
709
|
+
## 14. Worked Patterns
|
|
710
|
+
|
|
711
|
+
### Personal journal entry
|
|
712
|
+
```md
|
|
713
|
+
[my] <tag:you@example.com,2026:>
|
|
714
|
+
[j] <my:journal/>
|
|
715
|
+
|
|
716
|
+
# 2026-05-06 {=j:2026-05-06 .j:Entry j:date ^^xsd:date label}
|
|
717
|
+
|
|
718
|
+
[Productive] {j:mood}. Met [Sam] {+my:sam ?j:met} at [the library] {+my:place/library ?j:location}.
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
### Project with tasks
|
|
722
|
+
```md
|
|
723
|
+
[my] <tag:you@example.com,2026:>
|
|
724
|
+
|
|
725
|
+
# Project Alpha {=my:alpha .my:Project label}
|
|
726
|
+
|
|
727
|
+
Tasks: [design] {+#design ?my:task sh:name}, [build] {+#build ?my:task sh:name}.
|
|
728
|
+
|
|
729
|
+
## Design {=#design .my:Task label}
|
|
730
|
+
[done] {my:status}
|
|
731
|
+
|
|
732
|
+
## Build {=#build .my:Task label}
|
|
733
|
+
[in-progress] {my:status}
|
|
734
|
+
```
|
|
735
|
+
|
|
736
|
+
### Provenance activity
|
|
737
|
+
```md
|
|
738
|
+
[my] <tag:you@example.com,2026:>
|
|
739
|
+
|
|
740
|
+
## Analysis run {=my:run-1 .prov:Activity label}
|
|
741
|
+
|
|
742
|
+
Started: [2026-05-06T09:00:00Z] {prov:startedAtTime ^^xsd:dateTime}
|
|
743
|
+
Ended: [2026-05-06T09:45:00Z] {prov:endedAtTime ^^xsd:dateTime}
|
|
744
|
+
By: [Alice] {+my:alice ?prov:wasAssociatedWith}
|
|
745
|
+
Used: [dataset v2] {+my:dataset-v2 ?prov:used}
|
|
746
|
+
Made: [report] {+my:report ?prov:generated}
|
|
747
|
+
```
|
|
748
|
+
|
|
749
|
+
### SHACL validation shape
|
|
750
|
+
```md
|
|
751
|
+
[my] <tag:you@example.com,2026:>
|
|
321
752
|
|
|
322
|
-
|
|
753
|
+
## User Shape {=my:UserShape .sh:NodeShape label}
|
|
754
|
+
|
|
755
|
+
Validates all [User] {+my:User ?sh:targetClass} with:
|
|
756
|
+
[email rule] {+my:UserShape-email ?sh:property sh:name} and
|
|
757
|
+
[name rule] {+my:UserShape-name ?sh:property sh:name}.
|
|
758
|
+
|
|
759
|
+
### Email rule {=my:UserShape-email .sh:PropertyShape}
|
|
760
|
+
|
|
761
|
+
Path: [my:email] {+my:email ?sh:path}
|
|
762
|
+
Required: [1] {sh:minCount ^^xsd:integer}
|
|
763
|
+
|
|
764
|
+
> User must have an email address. {sh:message}
|
|
765
|
+
|
|
766
|
+
### Name rule {=my:UserShape-name .sh:PropertyShape}
|
|
767
|
+
|
|
768
|
+
Path: [label] {+label ?sh:path}
|
|
769
|
+
Required: [1] {sh:minCount ^^xsd:integer}
|
|
770
|
+
|
|
771
|
+
> User must have a name. {sh:message}
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
### Reified statement with confidence
|
|
775
|
+
```md
|
|
776
|
+
[my] <tag:you@example.com,2026:>
|
|
777
|
+
|
|
778
|
+
## Claim {=my:claim-1 .rdf:Statement label}
|
|
779
|
+
|
|
780
|
+
[Alice] {+my:alice ?rdf:subject} [knows] {+my:knows ?rdf:predicate} [Bob] {+my:bob ?rdf:object}.
|
|
781
|
+
Confidence: [0.9] {my:confidence ^^xsd:decimal}
|
|
782
|
+
Recorded: [2026-05-06] {prov:generatedAtTime ^^xsd:date}
|
|
783
|
+
```
|
|
784
|
+
|
|
785
|
+
### People and places — define once, reference everywhere
|
|
786
|
+
```md
|
|
787
|
+
[my] <tag:you@example.com,2026:>
|
|
788
|
+
|
|
789
|
+
# People
|
|
790
|
+
|
|
791
|
+
## Alice {=my:alice .prov:Person label}
|
|
792
|
+
[alice@example.com] {my:email}
|
|
793
|
+
|
|
794
|
+
## Bob {=my:bob .prov:Person label}
|
|
795
|
+
|
|
796
|
+
# Places
|
|
797
|
+
|
|
798
|
+
## Central Park {=my:place/central-park .prov:Location label}
|
|
799
|
+
[New York] {my:city}
|
|
800
|
+
```
|
|
801
|
+
|
|
802
|
+
### Versioned knowledge — append-only ledger
|
|
803
|
+
```md
|
|
804
|
+
[my] <tag:you@example.com,2026:>
|
|
805
|
+
[j] <my:journal/>
|
|
806
|
+
|
|
807
|
+
# 2026-05-01 {=j:2026-05-01 .j:Entry j:date ^^xsd:date label}
|
|
808
|
+
|
|
809
|
+
Project Alpha kicked off: [planning] {+my:alpha ?my:status}
|
|
810
|
+
|
|
811
|
+
# 2026-05-10 {=j:2026-05-10 .j:Entry j:date ^^xsd:date label}
|
|
812
|
+
|
|
813
|
+
{=my:alpha}
|
|
814
|
+
[planning] {-my:status}
|
|
815
|
+
[active] {my:status}
|
|
816
|
+
```
|