mdld-parse 0.9.4 → 0.9.6
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 +45 -8
- package/dist/README.md +45 -8
- package/dist/docs/API.md +41 -3
- package/dist/docs/LiterateRDF.md +472 -0
- package/dist/docs/Parser.md +73 -8
- package/dist/docs/primary-subject.md +143 -17
- package/dist/index.html +9 -9
- package/dist/index.js +37 -28
- 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 +1 -1
|
@@ -116,22 +116,27 @@ Creates a temporary fragment relative to the current subject base.
|
|
|
116
116
|
|
|
117
117
|
The soft IRI only exists within the current annotation block.
|
|
118
118
|
|
|
119
|
-
### Primary
|
|
119
|
+
### Primary Metadata
|
|
120
120
|
|
|
121
|
-
|
|
121
|
+
MD-LD tracks three primary metadata fields during single-pass parsing:
|
|
122
|
+
|
|
123
|
+
| Field | Source | Purpose |
|
|
124
|
+
|-------|--------|---------|
|
|
125
|
+
| **primarySubject** | First non-fragment `{=subject}` | Document identity |
|
|
126
|
+
| **primaryType** | First `.Class` declaration | Document category |
|
|
127
|
+
| **primaryLabel** | First `{label}` literal | Human-readable name |
|
|
122
128
|
|
|
123
129
|
**Selection rules:**
|
|
124
|
-
- First
|
|
125
|
-
-
|
|
126
|
-
-
|
|
127
|
-
- Null if no subject declared
|
|
130
|
+
- First occurrence only (fixed once detected)
|
|
131
|
+
- Never cleared on `{=}` reset
|
|
132
|
+
- Returns `null` if not declared
|
|
128
133
|
|
|
129
134
|
**API returns:**
|
|
130
|
-
- `parse()`: `{ ..., primarySubject: string | null }`
|
|
135
|
+
- `parse()`: `{ ..., primarySubject: string | null, primaryType: string | null, primaryLabel: string | null }`
|
|
131
136
|
- `merge()`: `{ ..., primarySubjects: string[] }` (ordered by merge)
|
|
132
137
|
- `generate({ quads, context, primarySubject })`: Places primary subject first for round-trip safety
|
|
133
138
|
|
|
134
|
-
**Use cases:** Document
|
|
139
|
+
**Use cases:** Document identity, stream addressing, merge tracking, UI navigation, query optimization, content classification, search indexing.
|
|
135
140
|
|
|
136
141
|
---
|
|
137
142
|
|
package/dist/spec/Spec-ultra.md
CHANGED
|
@@ -50,11 +50,22 @@ Ambiguous = no output.
|
|
|
50
50
|
{+#fragment} # Temporary soft fragment
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
### Primary
|
|
53
|
+
### Primary Metadata
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
MD-LD tracks three primary metadata fields during single-pass parsing:
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
| Field | Source | Purpose |
|
|
58
|
+
|-------|--------|---------|
|
|
59
|
+
| **primarySubject** | First non-fragment `{=subject}` | Document identity |
|
|
60
|
+
| **primaryType** | First `.Class` declaration | Document category |
|
|
61
|
+
| **primaryLabel** | First `{label}` literal | Human-readable name |
|
|
62
|
+
|
|
63
|
+
**Selection Rules:**
|
|
64
|
+
- First occurrence only (fixed once detected)
|
|
65
|
+
- Never cleared on `{=}` reset
|
|
66
|
+
- Returns `null` if not declared
|
|
67
|
+
|
|
68
|
+
**parse()**: Returns `{ primarySubject, primaryType, primaryLabel }` (string IRI/null)
|
|
58
69
|
**merge()**: Returns `primarySubjects` array (ordered by merge)
|
|
59
70
|
**generate()**: Accepts `{ quads, context, primarySubject }` — places primary subject first for round-trip safety
|
|
60
71
|
|
package/dist/spec/Spec.md
CHANGED
|
@@ -954,11 +954,21 @@ If you need these features, use them in your application logic, not in the MD-LD
|
|
|
954
954
|
|
|
955
955
|
---
|
|
956
956
|
|
|
957
|
-
## 17. Primary
|
|
957
|
+
## 17. Primary Metadata
|
|
958
|
+
|
|
959
|
+
MD-LD tracks three primary metadata fields during parsing to provide immediate document identity:
|
|
960
|
+
|
|
961
|
+
| Field | Source | Purpose |
|
|
962
|
+
|-------|--------|---------|
|
|
963
|
+
| **primarySubject** | First non-fragment `{=subject}` | Document identity |
|
|
964
|
+
| **primaryType** | First `.Class` declaration | Document category |
|
|
965
|
+
| **primaryLabel** | First `{label}` literal | Human-readable name |
|
|
966
|
+
|
|
967
|
+
### 17.1 Primary Subject
|
|
958
968
|
|
|
959
969
|
The **Primary Subject** is the main entity described by an MD-LD document. It provides a deterministic way to identify the central focus of a document.
|
|
960
970
|
|
|
961
|
-
|
|
971
|
+
#### Selection Criteria
|
|
962
972
|
|
|
963
973
|
The Primary Subject is determined by these rules:
|
|
964
974
|
|
|
@@ -967,16 +977,42 @@ The Primary Subject is determined by these rules:
|
|
|
967
977
|
3. **Fixed once detected** - Once set, the primary subject never changes, even on `{=}` reset
|
|
968
978
|
4. **No subject means no primary** - If no subject is declared, the primary subject is `null`
|
|
969
979
|
|
|
970
|
-
###
|
|
980
|
+
### 17.2 Primary Type
|
|
981
|
+
|
|
982
|
+
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.
|
|
983
|
+
|
|
984
|
+
#### Selection Criteria
|
|
985
|
+
|
|
986
|
+
The Primary Type is determined by these rules:
|
|
987
|
+
|
|
988
|
+
1. **First rdf:type declaration** - The first `.Class` declaration becomes the primary type
|
|
989
|
+
2. **Fixed once detected** - Once set, the primary type never changes
|
|
990
|
+
3. **No type means no primary** - If no type is declared, the primary type is `null`
|
|
971
991
|
|
|
972
|
-
|
|
992
|
+
### 17.3 Primary Label
|
|
993
|
+
|
|
994
|
+
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.
|
|
995
|
+
|
|
996
|
+
#### Selection Criteria
|
|
997
|
+
|
|
998
|
+
The Primary Label is determined by these rules:
|
|
999
|
+
|
|
1000
|
+
1. **First rdfs:label literal** - The first `{label}` literal becomes the primary label
|
|
1001
|
+
2. **Fixed once detected** - Once set, the primary label never changes
|
|
1002
|
+
3. **No label means no primary** - If no label is declared, the primary label is `null`
|
|
1003
|
+
|
|
1004
|
+
### 17.4 Examples
|
|
1005
|
+
|
|
1006
|
+
**Complete primary metadata:**
|
|
973
1007
|
```md
|
|
974
1008
|
[ex] <http://example.org/>
|
|
975
1009
|
|
|
976
|
-
#
|
|
1010
|
+
# Understanding MDLD {=ex:doc .ex:Article label}
|
|
977
1011
|
[Alice] {ex:author}
|
|
978
1012
|
```
|
|
979
1013
|
Primary subject: `ex:doc`
|
|
1014
|
+
Primary type: `ex:Article`
|
|
1015
|
+
Primary label: `Understanding MDLD`
|
|
980
1016
|
|
|
981
1017
|
**Fragment does not become primary:**
|
|
982
1018
|
```md
|
|
@@ -986,23 +1022,28 @@ Primary subject: `ex:doc`
|
|
|
986
1022
|
{=#summary}
|
|
987
1023
|
[Content] {label}
|
|
988
1024
|
```
|
|
989
|
-
Primary subject: `ex:doc`
|
|
1025
|
+
Primary subject: `ex:doc`
|
|
1026
|
+
Primary type: `null`
|
|
1027
|
+
Primary label: `null`
|
|
990
1028
|
|
|
991
1029
|
**Subject reset:**
|
|
992
1030
|
```md
|
|
993
1031
|
[ex] <http://example.org/>
|
|
994
1032
|
|
|
995
|
-
# First {=ex:first}
|
|
1033
|
+
# First {=ex:first .ex:Type}
|
|
996
1034
|
[Value] {label}
|
|
997
1035
|
|
|
998
1036
|
# Reset {=}
|
|
999
1037
|
|
|
1000
|
-
# Second {=ex:second}
|
|
1038
|
+
# Second {=ex:second .ex:OtherType}
|
|
1001
1039
|
[Value] {label}
|
|
1002
1040
|
```
|
|
1003
|
-
Primary subject: `ex:first`
|
|
1041
|
+
Primary subject: `ex:first`
|
|
1042
|
+
Primary type: `ex:Type`
|
|
1043
|
+
Primary label: `First`
|
|
1044
|
+
(Reset does not clear primary metadata)
|
|
1004
1045
|
|
|
1005
|
-
### API Return Values
|
|
1046
|
+
### 17.5 API Return Values
|
|
1006
1047
|
|
|
1007
1048
|
**parse() returns:**
|
|
1008
1049
|
```javascript
|
|
@@ -1011,7 +1052,9 @@ Primary subject: `ex:first` (reset does not clear the primary)
|
|
|
1011
1052
|
remove: [...],
|
|
1012
1053
|
origin: {...},
|
|
1013
1054
|
context: {...},
|
|
1014
|
-
primarySubject: string | null
|
|
1055
|
+
primarySubject: string | null,
|
|
1056
|
+
primaryType: string | null,
|
|
1057
|
+
primaryLabel: string | null
|
|
1015
1058
|
}
|
|
1016
1059
|
```
|
|
1017
1060
|
|
|
@@ -1026,21 +1069,26 @@ Primary subject: `ex:first` (reset does not clear the primary)
|
|
|
1026
1069
|
}
|
|
1027
1070
|
```
|
|
1028
1071
|
|
|
1029
|
-
### Use Cases
|
|
1072
|
+
### 17.6 Use Cases
|
|
1030
1073
|
|
|
1031
|
-
Primary
|
|
1032
|
-
- **Document
|
|
1074
|
+
Primary metadata enables:
|
|
1075
|
+
- **Document identity** - Primary subject + type + label provide complete document fingerprint
|
|
1076
|
+
- **Stream addressing** - Perfect for Nostr tags and distributed systems
|
|
1033
1077
|
- **Merge tracking** - Track which entities are being merged across documents
|
|
1034
|
-
- **UI navigation** - Provide
|
|
1035
|
-
- **Query optimization** - Use primary
|
|
1078
|
+
- **UI navigation** - Provide default focus and display information for document viewers
|
|
1079
|
+
- **Query optimization** - Use primary metadata as default query context and filters
|
|
1080
|
+
- **Content classification** - Automatic categorization based on primary type
|
|
1081
|
+
- **Search indexing** - Use primary label for human-readable search results
|
|
1036
1082
|
|
|
1037
|
-
### Conformance Requirements
|
|
1083
|
+
### 17.7 Conformance Requirements
|
|
1038
1084
|
|
|
1039
1085
|
An MD-LD processor MUST:
|
|
1040
1086
|
1. Track the first non-fragment subject declaration as primary subject
|
|
1041
|
-
2.
|
|
1042
|
-
3.
|
|
1043
|
-
4.
|
|
1087
|
+
2. Track the first rdf:type declaration as primary type
|
|
1088
|
+
3. Track the first rdfs:label literal as primary label
|
|
1089
|
+
4. Return all three primary fields in parse results (or `null` if none)
|
|
1090
|
+
5. Return `primarySubjects` array in merge results (ordered by merge)
|
|
1091
|
+
6. Keep all primary metadata fixed once detected (never cleared on `{=}` reset)
|
|
1044
1092
|
|
|
1045
1093
|
---
|
|
1046
1094
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdld-parse",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.6",
|
|
4
4
|
"description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
|