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