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.
@@ -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 Subject
119
+ ### Primary Metadata
120
120
 
121
- The **Primary Subject** is the first non-fragment subject declaration (`{=IRI}`) in a document.
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 non-fragment `{=IRI}` becomes primary
125
- - Fragments (`{=#fragment}`) excluded
126
- - Fixed once detected (never cleared on `{=}` reset)
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 identification, merge tracking, UI navigation, query optimization.
139
+ **Use cases:** Document identity, stream addressing, merge tracking, UI navigation, query optimization, content classification, search indexing.
135
140
 
136
141
  ---
137
142
 
@@ -50,11 +50,22 @@ Ambiguous = no output.
50
50
  {+#fragment} # Temporary soft fragment
51
51
  ```
52
52
 
53
- ### Primary Subject
53
+ ### Primary Metadata
54
54
 
55
- First non-fragment `{=IRI}` in document. Fixed once detected (never cleared on `{=}`).
55
+ MD-LD tracks three primary metadata fields during single-pass parsing:
56
56
 
57
- **parse()**: Returns `primarySubject` (string IRI or null)
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 Subject
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
- ### Selection Criteria
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
- ### Examples
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
- **Simple primary subject:**
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
- # Document {=ex:doc .ex:Article label}
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` (fragment `#summary` is ignored)
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` (reset does not clear the primary)
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 subjects enable:
1032
- - **Document identification** - Quickly determine what a document is about
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 a default focus point for document viewers
1035
- - **Query optimization** - Use primary subject as default query context
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. Return `primarySubject` in parse results (or `null` if none)
1042
- 3. Return `primarySubjects` array in merge results (ordered by merge)
1043
- 4. Keep primary subject fixed once detected (never cleared on `{=}` reset)
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,9 +1,9 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "0.9.3",
3
+ "version": "0.9.5",
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
- "packageManager": "pnpm@10.33.3",
6
+ "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
7
7
  "main": "index.js",
8
8
  "exports": {
9
9
  ".": "./dist/index.js"