1 # Reading Canonical Topic Maps
3 This records Slice 4. [Slice 5](reading-first-occurrences.md) extends the model
4 with Occurrences and supersedes the corresponding limits below.
6 Slice 4 compares the existing model with the original CXTM, rather than using
7 only property observations. It adds no CTM syntax or TMDM properties. The pinned
8 CTM draft remains 2010-03-31 at `cd165b150176c1d6842b37be9cc9051b40d4996b`.
10 ## Normative basis and implementation
12 Source: [published CXTM text](https://www.isotopicmaps.org/cxtm/cxtm.html),
13 identified as the published version by the [editors' index](https://www.isotopicmaps.org/cxtm/).
14 Its HTML header retains the editorial date 2009-01-27. The ISO edition is
15 [ISO/IEC 13250-4:2009](https://committee.iso.org/standard/52120.html).
16 Baselines are independent test evidence, not the definition of canonicalization.
18 | CXTM clauses | Implemented responsibility | Source |
20 | 3.1, 3.3–3.5 | Document, map, topics, identifiers, roles-played | `src/cxtm/canonicalizer.lisp:125` |
21 | 3.6, 3.9–3.10 | Names, associations and roles | `src/cxtm/canonicalizer.lisp:165` |
22 | 3.11–3.12 | Current null reifiers / empty scopes have no representation | Model schema restriction; `validate-map:73` |
23 | 3.13, 3.15–3.17 | Identifiers, topic references, string values | `emit-locators:117`, serialization below |
24 | 3.18 | Locator rewriting with explicit base | `normalized-locator:11` |
25 | 3.19–3.23 | Numbering, NFC, Infoset defaults | Serializer; `src/cxtm/unicode.lisp:29` |
26 | 4.1, 4.3–4.7 | Set, locator, Topic and Name comparisons | `canonicalizer.lisp:27–50` |
27 | 4.10–4.11 | Association and Role comparisons | `canonicalizer.lisp:51–64` |
28 | XML-C14N 1.0 §2.3 | UTF-8, XML escaping, expanded empty elements | Serializer and `canonicalize-octets` |
30 Mixed-type comparison (§4.2), Variants (§§3.7, 4.8), Occurrences (§§3.8, 4.9)
31 and datatype canonicalization (§3.14, numeric/date parts of §3.16) are not
32 implemented. The existing properties being compared are homogeneous sets.
33 The model has no nonempty Scope, Reifier or non-Topic item identifier properties.
34 An extended item class is rejected, not projected onto a smaller schema.
36 ## Document IRI and base locator
38 The reader keeps absolute locators. The executor supplies the **same explicit
39 Document IRI** as the CXTM Base Locator. For `simple.ctm`, this is:
42 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/simple.ctm
45 Its Topic's Item Identifier ends in `simple.ctm#topic`; §3.18 rewrites it to
46 `#topic`. External locators retain their absolute spelling where no base prefix
47 matches. The comparison reads the original baseline bytes, without trimming,
48 XML reparsing, IRI resolution or XML normalization. Checkout paths never enter
49 the logical IRIs. Equality under different chosen bases does not establish
50 shared absolute Subject Identity or cross-document merging. Tests also cover sibling paths, upward prefix search, queries,
51 fragments, trailing slashes, opaque IRIs and the specified literal prefix match.
53 **Interpretation point:** §3.1 step 2 inserts LF after every element, including
54 the document element. This implementation retains that LF. Generic
55 [XML-C14N §2.1](https://www.w3.org/TR/2001/REC-xml-c14n-20010315)
56 discards whitespace outside the root when reparsing XML. Therefore reparsing
57 and generic XML canonicalization alone are not the CXTM byte oracle here.
58 The supplementary Python XML check restores the specifically required root LF;
59 the actual baseline comparison performs no such modification. This distinction
60 is explicit rather than an undisclosed whitespace tolerance.
62 ## Public API and inspection
64 The independent `topic-maps/cxtm` system depends only on `topic-maps/tmdm`.
65 Its runtime uses ANSI Common Lisp, without Python, a CTM dependency or a
66 second model. The three public functions require an explicit absolute base:
69 (topic-maps.cxtm:canonicalize map :base-locator iri) ; string
70 (topic-maps.cxtm:canonicalize-octets map :base-locator iri) ; UTF-8 byte vector
71 (topic-maps.cxtm:write-cxtm map pathname :base-locator iri) ; file, returns pathname
74 To inspect `name.ctm` in a fresh process:
78 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
79 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
80 (asdf:load-system "topic-maps/ctm")
81 (asdf:load-system "topic-maps/cxtm")
82 (asdf:load-system "topic-maps")
84 (first (topic-maps.test-foundation:select-cases
85 (topic-maps.test-foundation:discover-corpus) :id "ctm/in/name.ctm")))
86 (defparameter *iri* (topic-maps.test-foundation:test-case-document-iri *case*))
88 (topic-maps.ctm:deserialize-file
89 (topic-maps.test-foundation:test-case-source-pathname *case*) :document-iri *iri*))
91 (describe (first (topic-maps.tmdm:topic-names
92 (first (topic-maps.tmdm:topic-map-topics *map*)))))
93 (write-string (topic-maps.cxtm:canonicalize *map* :base-locator *iri*))
96 Actual output and original expected output are identical (328 UTF-8 bytes,
97 including the final LF):
103 <locator>#topic</locator>
107 <type topicref="2"></type>
112 <locator>http://psi.topicmaps.org/iso13250/model/topic-name</locator>
113 </subjectIdentifiers>
118 ## Purity and boundaries
120 Canonicalization validates live membership/parents/references, sorts **copies**,
121 and assigns numbers in temporary EQ tables. It does not call `normalize-topic-map`,
122 merge items, modify identifiers, compress forward links or replace handles.
123 Retained pre-merge handles still resolve through the original canonical-* APIs.
124 Name numbers are local to their Topic; Role numbers are local to their Association.
126 Role comparison inside an Association's set uses player/type signatures: parent
127 is fixed within that context. Comparing Association signatures avoids recursively
128 comparing the same parents through their Roles. Global roles-played comparison
129 also compares parent Associations when player/type tie. Separate tests distinguish
130 Role type order from parent order.
132 Unicode data are pinned to 15.1.0. NFC includes recursive canonical decomposition,
133 stable combining-class ordering, blocked composition, exclusions and algorithmic
134 Hangul. `scripts/generate-nfc-data.py` regenerates the committed facts offline
135 with Python UCD 15.1.0; it is not invoked during deserialization/canonicalization.
136 Unassigned characters in that version yield `cxtm-unsupported` with
137 `:unsupported-unicode-version`. XML-inexpressible text yields `cxtm-error` with
138 `:xml-character`. Private-use characters are supported where XML permits them.
140 If distinct Topics have identical **normalized** identity keys, the canonicalizer
141 raises `cxtm-unsupported` / `:ambiguous-topic-order`. It does not invent an
142 address-based ordering or perform an additional merge. Unknown/extended model
143 classes raise `:unsupported-information-item`; stale/foreign live references
144 raise `:invalid-topic-reference`. Missing/relative base raises `:invalid-base-locator`.
145 No complete IRI validator, general XML canonicalizer, Occurrences, Variants,
146 nonempty Scope, Reification, additional identifier-bearing items, Templates,
147 cross-document merging or HyperDoc integration is supplied by this slice.