1 # Reading Prefixes and Explicit Datatypes
3 Slice 6 starts at `437ad53ea7539d36db3fa871d0931650b7a6a03e`. A prefix is a
4 source abbreviation for an IRI, not a Topic. An Occurrence datatype is a locator;
5 its Type is a Topic reference. These two properties remain different even if an
6 author deliberately uses the same IRI for both.
8 ## Normative requirements
10 [ISO/IEC 13250-6:2010](https://www.isotopicmaps.org/ctm/ctm.html):
11 §3.2 processes components in document order. §§3.3.3–3.3.5 form IRIs and resolve
12 QNames by concatenation; undefined prefixes are errors. §3.16.1 binds an
13 identifier to an IRI and permits repeat binding only to the same reference.
14 Its reference production accepts an IRI, not another QName. §§3.4.1–3.4.2 and
15 3.10 assign the quoted/escape-decoded lexical value and the explicit datatype
16 to the Occurrence. A qualifier is `^^` followed by an IRI reference.
18 [TMDM 2006](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/):
19 §4.3 defines string/locator equality. §4.4 permits other datatypes and stores
20 value representations separately from datatype locators. A datatype Topic need
21 not exist. `xsd:anyURI` content must be absolute. §5.6 defines Occurrence
22 properties/equality; §6.5 merges equal Occurrences and unions their identifiers.
23 The existing empty-Scope/null-Reifier subset and replacement handles continue.
25 [ISO/IEC 13250-4:2009](https://www.isotopicmaps.org/cxtm/cxtm.html):
26 §3.14 writes the datatype locator without base stripping. §3.16 uses locator
27 normalization for anyURI, special lexical rules for integer/decimal/date/dateTime,
28 and the string rule for Other. §3.20 applies NFC to encoded string properties.
29 §§4.2–4.5 and 4.9 order Occurrences by value, datatype, Type, Scope, Parent.
30 The serializer's existing §§3.8, 3.18–3.19 numbering/base rules remain unchanged.
32 ## Original inputs and expected items
34 The upstream corpus is unchanged at
35 `cd165b150176c1d6842b37be9cc9051b40d4996b`. It targets draft 2010-03-31;
36 the published standard is authoritative. No conflict blocks these seven cases.
37 The following expectations were established from those clauses and checked
38 against the original baselines before implementation.
40 Every case uses the absolute Document IRI formed by concatenating
41 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
42 and its full `ctm/in/...` or `ctm/invalid/...` case ID. This IRI is also the CXTM
43 Base Locator. It is independent of the physical checkout. Model Item Identifiers
44 remain absolute; the baselines' `#topic`/`#occtype` follow CXTM §3.18. Datatype
45 locators remain full IRIs under §3.14.
47 ### ctm/in/occurrence-explicit-datatype.ctm
50 %prefix xsd http://www.w3.org/2001/XMLSchema#
53 occtype: "Occurrence"^^xsd:string;.
56 The original source has no final LF; the display fence adds only a visual line break.
58 Two Topics, `topic` and `occtype`, each with its document-local Item Identifier. One Occurrence O1: Parent EQ topic, Type EQ occtype, Value `Occurrence`, Datatype `http://www.w3.org/2001/XMLSchema#string`. No Topic for xsd or its datatype. Empty SI/SL and Occurrence identifiers. Original CXTM: 359 bytes.
60 ### ctm/in/occurrence-datatype-unknown.ctm
64 occtype: "BOGUS"^^http://example.com/bogus.
67 The same two Topic identities. One Occurrence O1: Parent EQ topic, Type EQ occtype, Value `BOGUS`, Datatype `http://example.com/bogus`. The unknown datatype is a locator, not a third Topic. Original CXTM: 339 bytes.
69 ### ctm/in/prefix-duplicate.ctm
72 %prefix ex http://psi.example.org/
74 %prefix ex http://psi.example.org/
79 One Topic with SI `http://psi.example.org/fake`, no II or SL. The identical rebinding is permitted and creates no information item. Original CXTM: 141 bytes.
81 ### ctm/in/prefix-duplicate2.ctm
84 %prefix ex http://psi.example.org/
88 %prefix ex http://psi.example.org/
93 Two Topics with SIs `http://psi.example.org/fake` and `http://psi.example.org/fake2`; no II/SL. A binding persists across intervening Topic declarations. Original CXTM: 260 bytes.
95 ### ctm/in/prefix-multiline.ctm
100 http://psi.example.org/ ex:fake.
103 One Topic with SI `http://psi.example.org/fake`, no II/SL. The directive is token based and may span lines; the next Topic can follow its IRI on the same line. Original CXTM: 141 bytes.
105 ### ctm/invalid/prefix-collision.ctm
108 %prefix ex http://www.example.org/
109 %prefix ex http://www.example.net/
113 Reject the second binding: `PREFIX-COLLISION`, a `CTM-REJECTION`, code `:PREFIX-COLLISION`, zero-based offset 43, line 2, column 9 (the second prefix identifier). No map is returned.
115 ### ctm/invalid/prefix-undefined2.ctm
119 # In one of the CTM drafts, xsd was bound to <http://www.w3.org/2001/XMLSchema#>
120 # This binding was removed from CTM
123 foo occ: "1"^^xsd:int .
126 Reject `xsd:int`: `UNDEFINED-PREFIX`, a `CTM-REJECTION`, code `:UNDEFINED-PREFIX`, zero-based offset 136, line 6, column 15. There is no implicit xsd binding. The failure precedes any CXTM datatype processing. No map is returned.
128 ## Observed Lisp objects and results
130 The two Occurrence examples each return a `TOPIC-MAP` with two `TOPIC` structures
131 in source order: T1 owner, T2 type. T1's `topic-occurrences` contains O1, an
132 `OCCURRENCE` structure. O1's raw stored parent/type references are EQ T1/T2.
133 Its value/datatype are exactly the strings stated above; its Item Identifiers
134 are NIL. The owner/type Topics have II `DocumentIRI#topic`/`DocumentIRI#occtype`,
135 SI/SL NIL. No Names or Associations occur. Canonical topic numbers are type=1,
136 owner=2, with Occurrence number 1 inside owner.
138 The three positive prefix-only examples return one/two Topics in source order,
139 with precisely the SI sets above and empty II/SL/Names/Occurrences. Their
140 canonical numbers are fake=1, fake2=2 where applicable. The two negative cases
141 produce the specific conditions above, never I/O/generic failures.
143 These local observations are separately recorded in `reports/slice-6/prefixes.json`;
144 the Python checker independently checks source bytes, ordinal references, values,
145 datatypes and negative source positions. The actual CXTM UTF-8 bytes are compared
146 without any preprocessing to the original upstream baselines. All five comparisons
147 and both rejections pass. The preceding 28 canonical outputs remain byte-identical.
148 See `slice-6-validation.md` for full regression counts and fresh-process commands.
150 ## Public API and inspection
152 Load `topic-maps/ctm` for deserialization and `topic-maps/cxtm` for canonicalization.
153 No API signature changes:
155 - `deserialize-string text :document-iri absolute-iri :source-name optional-name`
156 - `deserialize-file pathname :document-iri absolute-iri :source-name optional-name`
157 - `add-occurrence parent-topic type-topic value :datatype absolute-locator :item-identifiers ids`
158 - `occurrence-value`, `occurrence-datatype`, `occurrence-parent`, `occurrence-type`,
159 `occurrence-item-identifiers`, `canonical-occurrence`
160 - `canonicalize`, `canonicalize-octets`, `write-cxtm`, with explicit `:base-locator`.
162 The new exported `prefix-collision` condition subclasses `ctm-rejection`, as does
163 `undefined-prefix`. Both are distinct from `ctm-unsupported`. Errors expose code,
164 source name, zero-based character offset and one-based line/column.
168 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
169 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
170 (asdf:load-system "topic-maps/ctm")
171 (asdf:load-system "topic-maps/cxtm")
172 (let* ((doc "https://example.invalid/inspection.ctm")
173 (map (topic-maps.ctm:deserialize-string
174 "%prefix ex <urn:example:> owner ex:description: \"00042\"^^ex:custom."
176 (owner (first (topic-maps.tmdm:topic-map-topics map)))
177 (item (first (topic-maps.tmdm:topic-occurrences owner))))
178 (assert (eq owner (topic-maps.tmdm:occurrence-parent item)))
179 (assert (string= "00042" (topic-maps.tmdm:occurrence-value item)))
180 (assert (string= "urn:example:custom" (topic-maps.tmdm:occurrence-datatype item)))
181 (assert (equal '("urn:example:description")
182 (topic-maps.tmdm:topic-subject-identifiers
183 (topic-maps.tmdm:occurrence-type item))))
185 (describe (topic-maps.tmdm:occurrence-type item))
186 (write-string (topic-maps.cxtm:canonicalize map :base-locator doc)))
189 ## Implementation boundaries
191 Bindings are parser-local, case-sensitive and document-ordered. A successful or
192 failed read cannot export a prefix to another read. Prefix IRIs are formed once;
193 QName concatenation neither decodes nor resolves the bound IRI again.
195 Quoted strings preserve their escape-decoded lexical values in TMDM. Datatype
196 IRIs/QNames are resolved as locators and never automatically interned as Topics.
197 Unknown datatypes use CXTM's Other string rule, including normal XML escaping/NFC
198 at output. Their value spaces are not interpreted or validated. No implicit
199 numeric, whitespace, URI-content or date conversion is performed.
201 Explicit integer/decimal/date/dateTime datatype locators can be stored through
202 the general quoted-string qualifier/API, but CXTM reports
203 `CXTM-UNSUPPORTED :UNSUPPORTED-OCCURRENCE-DATATYPE` for these four exact IRIs;
204 §3.16 requires canonical lexical rules outside this slice. Numeric/date sugar
205 still reports `CTM-UNSUPPORTED`. A quoted relative anyURI value is specifically
206 rejected (`:RELATIVE-URI-VALUE`) under TMDM §4.4, never silently resolved; IRI-form
207 values retain the previously implemented CTM IRI-reference behavior.
209 Nonempty Scope, Reification, Variants, Templates, includes/mergemap, cross-document
210 merging, non-UTF-8 encoding declarations and HyperDoc integration remain unsupported.
211 Typed Names and triple-quoted strings remain unsupported. The inherited locator
212 API expects validated/resolved arguments; its scheme check is not a complete RFC
213 3987 validator. The established Unicode 15.1 and normalized Topic-key ambiguity
214 limits, and the previously documented CXTM root-LF interpretation, remain.