]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-canonical-topic-maps.md
Implement CTM Mergemap with explicit byte resources and isolated environments
[topic-maps.git] / docs / reading-canonical-topic-maps.md
1 # Reading Canonical Topic Maps
2
3 This records Slice 4. [Slice 5](reading-first-occurrences.md) extends the model
4 with Occurrences and supersedes the corresponding limits below.
5
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`.
9
10 ## Normative basis and implementation
11
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.
17
18 | CXTM clauses | Implemented responsibility | Source |
19 | --- | --- | --- |
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` |
29
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.
35
36 ## Document IRI and base locator
37
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:
40
41 ```
42 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/simple.ctm
43 ```
44
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.
52
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.
61
62 ## Public API and inspection
63
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:
67
68 ```lisp
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
72 ```
73
74 To inspect `name.ctm` in a fresh process:
75
76 ```lisp
77 (require :asdf)
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")
83 (defparameter *case*
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*))
87 (defparameter *map*
88 (topic-maps.ctm:deserialize-file
89 (topic-maps.test-foundation:test-case-source-pathname *case*) :document-iri *iri*))
90 (describe *map*)
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*))
94 ```
95
96 Actual output and original expected output are identical (328 UTF-8 bytes,
97 including the final LF):
98
99 ```xml
100 <topicMap>
101 <topic number="1">
102 <itemIdentifiers>
103 <locator>#topic</locator>
104 </itemIdentifiers>
105 <name number="1">
106 <value>Name</value>
107 <type topicref="2"></type>
108 </name>
109 </topic>
110 <topic number="2">
111 <subjectIdentifiers>
112 <locator>http://psi.topicmaps.org/iso13250/model/topic-name</locator>
113 </subjectIdentifiers>
114 </topic>
115 </topicMap>
116 ```
117
118 ## Purity and boundaries
119
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.
125
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.
131
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.
139
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.