]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-first-five-ctm-documents.md
Implement CTM prefix directives and explicit occurrence datatypes
[topic-maps.git] / docs / reading-first-five-ctm-documents.md
1 # Reading the First Five CTM Documents
2
3 These five documents are the original inputs from the pinned public-domain
4 CXTM corpus at `cd165b150176c1d6842b37be9cc9051b40d4996b`. It targets the
5 **CTM draft dated 2010-03-31**; successful tests alone do not establish full
6 ISO/IEC 13250-6:2010 conformity. The published standards remain authoritative.
7
8 CTM [§3.3.6](https://www.isotopicmaps.org/ctm/ctm.html#sec-topic-identity)
9 determines which identifier property receives each reference. The local form
10 uses the explicit Document IRI. TMDM [§5.3.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/#d0e1029)
11 keeps the three properties distinct and specifies identity. CTM
12 [§3.11](https://www.isotopicmaps.org/ctm/ctm.html#sec-name) supplies the default
13 name-type Subject Identifier; TMDM [§5.4](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/#sect-topic-name)
14 requires a Name item whose type is a Topic.
15
16 The model observations below come from the actual reader results and accessor
17 checks, not from fabricated XML. Ordinals label objects for inspection; they
18 are neither identities nor canonical ordering. Other set-valued properties
19 are implicitly empty and single-valued properties null (CTM §3.2). No scope,
20 variant, role or occurrence syntax is implemented.
21
22 ## simple.ctm
23
24 Actual unmodified source ([original file](../vendor/cxtm/ctm/in/simple.ctm)):
25
26 ```ctm
27 topic.
28 ```
29
30 Original bytes: 6; no terminal newline. The newline before the Markdown closing fence is presentation only.
31
32 Document IRI:
33
34 ```text
35 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/simple.ctm
36 ```
37
38 **Normative expectation:** One Topic with an Item Identifier formed from this Document IRI and `#topic`; no name or name-type Topic.
39
40 Applicable clauses: CTM 3.3.6, CTM 3.8, CTM 3.2, TMDM 5.1, TMDM 5.2, TMDM 5.3.5. TMDM §5.2 supplies the containing Topic Map.
41
42 **Upstream evidence:** [original CXTM baseline](../vendor/cxtm/ctm/baseline/simple.ctm.cxtm) contains the corresponding topics and identifier/name properties. The baseline is unchanged.
43
44 **Local observation:** 1 Topic object(s), 0 Topic Name object(s), inside one Topic Map.
45
46 | Object | Item Identifiers | Subject Identifiers | Subject Locators | Name item(s) |
47 | --- | --- | --- | --- | --- |
48 | Topic 1 | `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/simple.ctm#topic` | empty | empty | none |
49
50 Every Topic parent is the actual containing map. Name type/parent checks use `EQ`, not matching display labels.
51
52 **Result:** semantic assertions PASS; selected baseline-property evidence PASS. The imported `:CXTM-EQUAL` contract remains **NOT-RUN**, because no canonicalizer exists.
53
54 ## subject-identifier.ctm
55
56 Actual unmodified source ([original file](../vendor/cxtm/ctm/in/subject-identifier.ctm)):
57
58 ```ctm
59 <http://psi.example.org/fake>.
60 ```
61
62 Original bytes: 30; no terminal newline. The newline before the Markdown closing fence is presentation only.
63
64 Document IRI:
65
66 ```text
67 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/subject-identifier.ctm
68 ```
69
70 **Normative expectation:** One Topic with the given Subject Identifier; no Item Identifier or Subject Locator is implicitly added.
71
72 Applicable clauses: CTM 3.3.6, CTM 3.8, TMDM 5.1, TMDM 5.2, TMDM 5.3.5. TMDM §5.2 supplies the containing Topic Map.
73
74 **Upstream evidence:** [original CXTM baseline](../vendor/cxtm/ctm/baseline/subject-identifier.ctm.cxtm) contains the corresponding topics and identifier/name properties. The baseline is unchanged.
75
76 **Local observation:** 1 Topic object(s), 0 Topic Name object(s), inside one Topic Map.
77
78 | Object | Item Identifiers | Subject Identifiers | Subject Locators | Name item(s) |
79 | --- | --- | --- | --- | --- |
80 | Topic 1 | empty | `http://psi.example.org/fake` | empty | none |
81
82 Every Topic parent is the actual containing map. Name type/parent checks use `EQ`, not matching display labels.
83
84 **Result:** semantic assertions PASS; selected baseline-property evidence PASS. The imported `:CXTM-EQUAL` contract remains **NOT-RUN**, because no canonicalizer exists.
85
86 ## subject-locator.ctm
87
88 Actual unmodified source ([original file](../vendor/cxtm/ctm/in/subject-locator.ctm)):
89
90 ```ctm
91 =<http://www.example.org/resource>.
92 ```
93
94 Original bytes: 35; no terminal newline. The newline before the Markdown closing fence is presentation only.
95
96 Document IRI:
97
98 ```text
99 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/subject-locator.ctm
100 ```
101
102 **Normative expectation:** One Topic with the given Subject Locator; no Subject Identifier or Item Identifier is implicitly added.
103
104 Applicable clauses: CTM 3.3.6, CTM 3.8, TMDM 5.1, TMDM 5.2, TMDM 5.3.5. TMDM §5.2 supplies the containing Topic Map.
105
106 **Upstream evidence:** [original CXTM baseline](../vendor/cxtm/ctm/baseline/subject-locator.ctm.cxtm) contains the corresponding topics and identifier/name properties. The baseline is unchanged.
107
108 **Local observation:** 1 Topic object(s), 0 Topic Name object(s), inside one Topic Map.
109
110 | Object | Item Identifiers | Subject Identifiers | Subject Locators | Name item(s) |
111 | --- | --- | --- | --- | --- |
112 | Topic 1 | empty | empty | `http://www.example.org/resource` | none |
113
114 Every Topic parent is the actual containing map. Name type/parent checks use `EQ`, not matching display labels.
115
116 **Result:** semantic assertions PASS; selected baseline-property evidence PASS. The imported `:CXTM-EQUAL` contract remains **NOT-RUN**, because no canonicalizer exists.
117
118 ## item-identifier.ctm
119
120 Actual unmodified source ([original file](../vendor/cxtm/ctm/in/item-identifier.ctm)):
121
122 ```ctm
123 ^<http://www.example.org/#topic>.
124 ```
125
126 Original bytes: 33; no terminal newline. The newline before the Markdown closing fence is presentation only.
127
128 Document IRI:
129
130 ```text
131 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/item-identifier.ctm
132 ```
133
134 **Normative expectation:** One Topic with the explicit Item Identifier; its locator is independent of the supplied Document IRI.
135
136 Applicable clauses: CTM 3.3.6, CTM 3.8, TMDM 5.1, TMDM 5.2, TMDM 5.3.5. TMDM §5.2 supplies the containing Topic Map.
137
138 **Upstream evidence:** [original CXTM baseline](../vendor/cxtm/ctm/baseline/item-identifier.ctm.cxtm) contains the corresponding topics and identifier/name properties. The baseline is unchanged.
139
140 **Local observation:** 1 Topic object(s), 0 Topic Name object(s), inside one Topic Map.
141
142 | Object | Item Identifiers | Subject Identifiers | Subject Locators | Name item(s) |
143 | --- | --- | --- | --- | --- |
144 | Topic 1 | `http://www.example.org/#topic` | empty | empty | none |
145
146 Every Topic parent is the actual containing map. Name type/parent checks use `EQ`, not matching display labels.
147
148 **Result:** semantic assertions PASS; selected baseline-property evidence PASS. The imported `:CXTM-EQUAL` contract remains **NOT-RUN**, because no canonicalizer exists.
149
150 ## name.ctm
151
152 Actual unmodified source ([original file](../vendor/cxtm/ctm/in/name.ctm)):
153
154 ```ctm
155 topic
156 - "Name";.
157 ```
158
159 Original bytes: 16; no terminal newline. The newline before the Markdown closing fence is presentation only.
160
161 Document IRI:
162
163 ```text
164 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/name.ctm
165 ```
166
167 **Normative expectation:** Two Topics and one Topic Name: the local Topic, its Name item with value `Name`, and the default type Topic identified by `http://psi.topicmaps.org/iso13250/model/topic-name`. The Name type is that actual Topic object; the Name parent is the local Topic.
168
169 Applicable clauses: CTM 3.8, CTM 3.11, TMDM 5.1, TMDM 5.2, TMDM 5.3.5, TMDM 5.4. The default-type rule is CTM §3.11, not an assumption inferred solely from the baseline. TMDM §5.2 supplies the containing Topic Map.
170
171 **Upstream evidence:** [original CXTM baseline](../vendor/cxtm/ctm/baseline/name.ctm.cxtm) contains the corresponding topics and identifier/name properties. The baseline is unchanged.
172
173 **Local observation:** 2 Topic object(s), 1 Topic Name object(s), inside one Topic Map.
174
175 | Object | Item Identifiers | Subject Identifiers | Subject Locators | Name item(s) |
176 | --- | --- | --- | --- | --- |
177 | Topic 1 | `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/name.ctm#topic` | empty | empty | value `Name`, type → Topic 2, parent → Topic 1 |
178 | Topic 2 | empty | `http://psi.topicmaps.org/iso13250/model/topic-name` | empty | none |
179
180 Every Topic parent is the actual containing map. Name type/parent checks use `EQ`, not matching display labels.
181
182 **Result:** semantic assertions PASS; selected baseline-property evidence PASS. The imported `:CXTM-EQUAL` contract remains **NOT-RUN**, because no canonicalizer exists.
183
184 ## Relative locators in the baselines
185
186 For `simple.ctm` and `name.ctm`, the baseline's `#topic` is interpreted in the
187 recorded Document-IRI context. The actual Item Identifier is the full Document
188 IRI plus that fragment. This selected-property interpretation does not validate
189 a future canonicalizer's relativization or ordering. No XML is produced or
190 compared byte-for-byte by this slice.
191
192 ## The negative case
193
194 `ctm/invalid/prefix-undefined.ctm` contains a leading newline, `ex:fake.`, then a
195 trailing newline. CTM §3.3.4 requires a prefix binding. The actual condition is
196 `TOPIC-MAPS.CTM:UNDEFINED-PREFIX`, code `:UNDEFINED-PREFIX`, character offset 1,
197 line 2, column 1. Its imported `:CTM-REJECTION` contract is PASS. I/O failures,
198 unsupported constructs and unrelated exceptions cannot satisfy this check.
199
200 ## Standard Common Lisp inspection
201
202 Use a new SBCL process. These forms load only the independent project:
203
204 ```lisp
205 (require :asdf)
206 (asdf:initialize-source-registry
207 '(:source-registry :ignore-inherited-configuration))
208 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
209 (asdf:load-system "topic-maps/ctm")
210 (defparameter *document-iri*
211 "https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/name.ctm")
212 (defparameter *map*
213 (topic-maps.ctm:deserialize-file
214 (asdf:system-relative-pathname "topic-maps" "vendor/cxtm/ctm/in/name.ctm")
215 :document-iri *document-iri*))
216 (describe *map*)
217 (defparameter *topic* (first (topic-maps.tmdm:topic-map-topics *map*)))
218 (describe *topic*)
219 (defparameter *name* (first (topic-maps.tmdm:topic-names *topic*)))
220 (describe *name*)
221 (describe (topic-maps.tmdm:topic-name-type *name*))
222 (eq *topic* (topic-maps.tmdm:topic-name-parent *name*)) ; => T
223 ```
224
225 These forms were exercised in a fresh process; the captured
226 [DESCRIBE output](../reports/slice-1/describe.log) exposes the actual objects.
227 Memory addresses in that log are observations of one run, not stable identity.
228 The deterministic [semantic report](../reports/slice-1/semantics.json) exposes
229 properties separately from [imported contracts](../reports/slice-1/validation.json).
230 The test-only `topic-maps.ctm.tests:observations` operation also returns the
231 actual model objects after `asdf:test-system "topic-maps/ctm/tests"`.