]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-typed-topic-names.md
docs: design draft for a read-only SHOP3 adapter over TMDM objects
[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 Both spellings are supported as different identifiers; see
33 [Two documented default name type identifiers](reading-type-relationships.md#two-documented-default-name-type-identifiers).
34
35 ## Four unchanged original sources
36
37 `name.ctm`:
38 ```ctm
39 topic
40 - "Name";.
41 ```
42
43 `name2.ctm`:
44 ```ctm
45 topic
46 - "Name".
47 ```
48
49 `name-type.ctm`:
50 ```ctm
51 topic
52 - nametype : "Name" .
53 ```
54
55 `name-duplicate.ctm`:
56 ```ctm
57 topic
58 - "Name";
59 - "Name"
60 .
61 ```
62
63 For each file the exact Document IRI is:
64 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/<filename>`.
65 This is a deserialization input, not a reachable Subject URL. Canonicalization
66 uses the same IRI as its Base Locator (CXTM 3.18); this explains the baseline's
67 `#topic` and `#nametype` locators without changing those baseline bytes.
68
69 ## Expected items, baseline evidence and actual observations
70
71 All four documents yield one Map, two Topics, one Name, no Occurrences or
72 Associations. In the first, second and fourth document, the containing Topic
73 has Item Identifier `DocumentIRI#topic`; the other Topic has the default
74 Subject Identifier above. The Name has Value `"Name"`, its Parent is the
75 containing Topic and its Type is that default Topic. The duplicate declaration
76 in `name-duplicate.ctm` does not introduce a second live Name.
77
78 In `name-type.ctm`, the second Topic instead has Item Identifier
79 `DocumentIRI#nametype`, no Subject Identifier and no Subject Locator. The Name's
80 Type is EQ to that actual Topic; Parent is EQ to the `#topic` object. No default
81 Type Topic is present. The baseline numbers the Type Topic as 1 and Parent as
82 2; the generated Name therefore contains:
83 ```xml
84 <value>Name</value>
85 <type topicref="1"></type>
86 ```
87
88 These expectations follow from the cited rules. The upstream XML is separate
89 external evidence. Lisp assertions test actual object identity and raw stored
90 references, while an independent Python check compares identifier sets and
91 Name/Parent/Type relations with the baseline. CXTM byte comparisons are a
92 separate check. Execution results are recorded in `reports/slice-12a/`.
93
94 ## Public API and inspection
95
96 `(topic-maps.tmdm:add-name topic value &key type)` returns a current Name.
97 Omitting `:type` uses the default. Supplying it requires an actual Topic from
98 the same Map; explicitly supplying NIL is an error. Retained Topic handles are
99 resolved before storage. Invalid types are refused before mutation. Equal
100 Value/Type/Parent reuses an existing Name. `add-default-name` remains compatible
101 and delegates to this API.
102
103 Run from the repository root in a fresh SBCL:
104 ```lisp
105 (require :asdf)
106 (asdf:load-asd (truename "topic-maps.asd"))
107 (asdf:load-system "topic-maps/ctm")
108 (let* ((map (topic-maps.ctm:deserialize-string
109 "topic - nametype: \"Name\"."
110 :document-iri "https://example.invalid/names.ctm"))
111 (owner (find-if #'topic-maps.tmdm:topic-names
112 (topic-maps.tmdm:topic-map-topics map)))
113 (name (first (topic-maps.tmdm:topic-names owner))))
114 (assert (= 2 (length (topic-maps.tmdm:topic-map-topics map))))
115 (assert (eq owner (topic-maps.tmdm:topic-name-parent name)))
116 (describe name)
117 (describe (topic-maps.tmdm:topic-name-type name)))
118 ```
119
120 After Type or Parent merging, inspect `(canonical-topic-name retained-name)`;
121 EQ on an obsolete Name is not rewritten. Public Name readers resolve the
122 retained handle. Serialization does not compress forwarding chains or mutate
123 retained objects.
124
125 ## Limits
126
127 Embedded Topics, Scope, Reification, Variants, Templates and cross-map merging
128 remain unsupported. No HyperDoc dependency or navigation code is introduced.
129 The two DateTime baseline discrepancies remain executed FAILs. The other
130 exploratively observed contracts are not promoted by this slice.