]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-typed-topic-names.md
feat(xtm): support resource references on name variants
[topic-maps.git] / docs / reading-typed-topic-names.md
1 # Reading Explicitly Typed Topic Names
2
3 Slice 12A builds on `6a2f8446afca0915882f0d4a06cb891ccfcdc96d`.
4 The CTM corpus remains pinned at `cd165b150176c1d6842b37be9cc9051b40d4996b`.
5 Original inputs and baselines are unchanged. The corpus targets the draft of
6 2010-03-31; published normative rules remain authoritative.
7
8 ## Normative requirements
9
10 - [CTM 3.11](https://www.isotopicmaps.org/ctm/ctm.html): a Name's optional
11 `type ':'` refers to a Topic. Without it, the default Type Topic is identified
12 by `http://psi.topicmaps.org/iso13250/model/topic-name`. With an explicit
13 different type, no default Type Topic is required. CTM 3.3.6–3.3.7 and 3.3.11
14 supply the existing identity/reference procedure used for Name types.
15 - [TMDM 5.4](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/): a Name
16 has a string Value, Topic Type and containing Topic Parent. Name equality
17 compares Value, Type, Scope and Parent; equal text with different Types does
18 not establish equality. There is no Name Datatype property.
19 - TMDM 6.2 replaces Topic references when Topics merge; 6.3 replaces equal
20 Names with one Name. Existing forwarding handles implement this contract.
21 TMDM 6.4 concerns Variants, which remain outside this slice; no partial
22 Variant merge implementation has been added.
23 - [CXTM 3.6 and 4.7](https://www.isotopicmaps.org/cxtm/cxtm.html): emit the
24 Name's Value and Type reference, sorting by Value, Type, Scope, Parent. Scope
25 remains empty. The existing canonicalizer already implements these supported
26 properties and is unchanged.
27
28 The default identifier above is taken specifically from CTM 3.11. The linked
29 2006-06-18 TMDM text's 7.5 spells its default identifier `.../name-type`;
30 this slice preserves the CTM-mandated `.../topic-name` and the original CTM
31 baselines rather than silently substituting the other spelling.
32
33 ## Four unchanged original sources
34
35 `name.ctm`:
36 ```ctm
37 topic
38 - "Name";.
39 ```
40
41 `name2.ctm`:
42 ```ctm
43 topic
44 - "Name".
45 ```
46
47 `name-type.ctm`:
48 ```ctm
49 topic
50 - nametype : "Name" .
51 ```
52
53 `name-duplicate.ctm`:
54 ```ctm
55 topic
56 - "Name";
57 - "Name"
58 .
59 ```
60
61 For each file the exact Document IRI is:
62 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/<filename>`.
63 This is a deserialization input, not a reachable Subject URL. Canonicalization
64 uses the same IRI as its Base Locator (CXTM 3.18); this explains the baseline's
65 `#topic` and `#nametype` locators without changing those baseline bytes.
66
67 ## Expected items, baseline evidence and actual observations
68
69 All four documents yield one Map, two Topics, one Name, no Occurrences or
70 Associations. In the first, second and fourth document, the containing Topic
71 has Item Identifier `DocumentIRI#topic`; the other Topic has the default
72 Subject Identifier above. The Name has Value `"Name"`, its Parent is the
73 containing Topic and its Type is that default Topic. The duplicate declaration
74 in `name-duplicate.ctm` does not introduce a second live Name.
75
76 In `name-type.ctm`, the second Topic instead has Item Identifier
77 `DocumentIRI#nametype`, no Subject Identifier and no Subject Locator. The Name's
78 Type is EQ to that actual Topic; Parent is EQ to the `#topic` object. No default
79 Type Topic is present. The baseline numbers the Type Topic as 1 and Parent as
80 2; the generated Name therefore contains:
81 ```xml
82 <value>Name</value>
83 <type topicref="1"></type>
84 ```
85
86 These expectations follow from the cited rules. The upstream XML is separate
87 external evidence. Lisp assertions test actual object identity and raw stored
88 references, while an independent Python check compares identifier sets and
89 Name/Parent/Type relations with the baseline. CXTM byte comparisons are a
90 separate check. Execution results are recorded in `reports/slice-12a/`.
91
92 ## Public API and inspection
93
94 `(topic-maps.tmdm:add-name topic value &key type)` returns a current Name.
95 Omitting `:type` uses the default. Supplying it requires an actual Topic from
96 the same Map; explicitly supplying NIL is an error. Retained Topic handles are
97 resolved before storage. Invalid types are refused before mutation. Equal
98 Value/Type/Parent reuses an existing Name. `add-default-name` remains compatible
99 and delegates to this API.
100
101 Run from the repository root in a fresh SBCL:
102 ```lisp
103 (require :asdf)
104 (asdf:load-asd (truename "topic-maps.asd"))
105 (asdf:load-system "topic-maps/ctm")
106 (let* ((map (topic-maps.ctm:deserialize-string
107 "topic - nametype: \"Name\"."
108 :document-iri "https://example.invalid/names.ctm"))
109 (owner (find-if #'topic-maps.tmdm:topic-names
110 (topic-maps.tmdm:topic-map-topics map)))
111 (name (first (topic-maps.tmdm:topic-names owner))))
112 (assert (= 2 (length (topic-maps.tmdm:topic-map-topics map))))
113 (assert (eq owner (topic-maps.tmdm:topic-name-parent name)))
114 (describe name)
115 (describe (topic-maps.tmdm:topic-name-type name)))
116 ```
117
118 After Type or Parent merging, inspect `(canonical-topic-name retained-name)`;
119 EQ on an obsolete Name is not rewritten. Public Name readers resolve the
120 retained handle. Serialization does not compress forwarding chains or mutate
121 retained objects.
122
123 ## Limits
124
125 Embedded Topics, Scope, Reification, Variants, Templates and cross-map merging
126 remain unsupported. No HyperDoc dependency or navigation code is introduced.
127 The two DateTime baseline discrepancies remain executed FAILs. The other
128 exploratively observed contracts are not promoted by this slice.