]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-topic-references.md
Implement CTM Include and source-preserving template import
[topic-maps.git] / docs / reading-topic-references.md
1 # Reading Wildcards and Embedded Topics — Slice 15
2
3 Base commit: `4f7b4d26d40f8f5566594aa2e3ad6296d44fc4c3`.
4 This slice completes Topic references for the already supported CTM statements.
5 It adds no TMDM class, HyperDoc integration, Template engine or import mechanism.
6
7 ## Normative requirements
8
9 [CTM §3.2](https://www.isotopicmaps.org/ctm/ctm.html) supplies the Document IRI,
10 a Wildcard IRI defaulting to it, and a non-negative Wildcard Counter defaulting
11 to zero. §§3.3.6–3.3.8 map topic identities and references to actual Topics.
12 For an anonymous `?`, increment the counter, then append `#$__` and the decimal
13 counter to Wildcard IRI. First use of `?name` also increments it and appends
14 `.name`; repeated uses reuse the locator. An Embedded Topic's `[` is handled
15 as an anonymous wildcard; its nonempty Topic Tail is processed before `]`.
16 The existing Topic-Tail implementation (§3.9) is reused recursively.
17
18 [TMDM §§5.1/5.3.5 and 6.1–6.7](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
19 govern Item Identifiers, Topic equality and reference replacement. Wildcard
20 locators are Item Identifiers, never Subject Identifiers or separate model items.
21 Explicit identities within an Embedded Tail can merge its Topic with an existing
22 Topic. Callers must receive the current canonical Topic after that Tail.
23
24 [CXTM §§3.4–3.21 and 4.3–4.11](https://www.isotopicmaps.org/cxtm/cxtm.html)
25 apply to the resulting existing model. Embedded Topics have no special CXTM
26 element. Topic numbering, locators, Parent/Type/Player references, Scopes and
27 Variants use the unchanged canonicalizer. Canonicalization never mutates objects.
28
29 The corpus remains pinned to `cd165b150176c1d6842b37be9cc9051b40d4996b`, with
30 its original 2010-03-31 draft qualification. Its sources and XML baselines are
31 unchanged evidence, not the source of the implementation rules.
32
33 ## Public API and environment
34
35 Both `deserialize-string` and `deserialize-file` now accept:
36
37 ```text
38 :document-iri required absolute, fragment-free IRI
39 :source-name optional diagnostic identity
40 :wildcard-iri optional absolute, fragment-free IRI; defaults to Document IRI
41 :wildcard-counter optional non-negative integer; defaults to 0
42 ```
43
44 They return two values: the TMDM Topic Map and the final counter. Existing callers
45 using just the first value retain their behavior. Environment arguments are
46 validated before parsing or file I/O. No global counter or name registry is used.
47 Named wildcard bindings cache locator strings; existing identity resolution finds
48 the current Topic even after replacement merging. Counter arithmetic is arbitrary
49 precision. Wildcard names preserve case and Unicode.
50
51 Document IRI continues to resolve local `identifier`s, relative IRIs and prefix
52 bindings. Wildcard IRI controls only generated Item Identifiers. It is not a
53 new document base. Separate parses have independent environments and objects;
54 no cross-document merging is implied by this API.
55
56 The shared `topic-reference` path handles identity forms and Embedded Topics at
57 Name/Occurrence/Association Type, Role Type/Player and Scope positions. Identity
58 statements in a Tail still add identifiers directly to the owner without an
59 unnecessary intermediate Topic. Nonempty Embedded Tails may have a trailing
60 semicolon; a period does not replace their closing bracket. A bare Embedded
61 Topic is not a top-level Topic declaration, but can be an Association Type.
62
63 ## Original contracts
64
65 The following unmodified original sources execute against their original CXTM
66 baselines. Their Document IRI is the established
67 `https://ctm-tests.example.invalid/<pin>/ctm/in/<filename>.ctm`; Wildcard IRI
68 defaults to it and Counter starts at zero. The same Document IRI is supplied as
69 CXTM Base Locator. Stored generated identifiers are absolute, while baseline
70 `#$__...` strings are their canonical locator representation.
71
72 | Original positive case | Final counter |
73 |---|---:|
74 | wildcard | 1 |
75 | wildcard-named | 1 |
76 | wildcard-named2 | 3 |
77 | wildcard-named-merge | 1 |
78 | association-scope-embedded | 2 |
79 | association-scope-embedded2 | 3 |
80 | association-type-embedded | 1 |
81 | association-type-embedded-merge | 2 |
82 | embedded-semicolon | 1 |
83 | name-scope-embedded | 2 |
84 | name-scope-embedded2 | 3 |
85 | name-type-embedded | 1 |
86 | nested-twice | 2 |
87 | occurrence-scope-embedded | 2 |
88 | occurrence-scope-embedded2 | 3 |
89 | occurrence-type-embedded | 1 |
90 | role-player-embedded | 1 |
91 | role-type-embedded | 1 |
92 | subject-identifier-embedded | 1 |
93 | variant-scope-embedded | 3 |
94 | variant-scope-embedded2 | 4 |
95
96 For example, original `wildcard-named-merge.ctm` is `\n?foo.?foo.`. It creates
97 one Topic with Item Identifier `DocumentIRI#$__1.foo`, not two Topics or a Subject
98 Identifier. Original `association-type-embedded-merge.ctm` creates two generated
99 locators, then its shared SI merges their Topics and the duplicate Associations.
100 Both Item Identifiers remain on the canonical Topic.
101
102 Original `nested-twice.ctm`:
103
104 ```text
105
106 topic
107 [-[-"name"]: "occ-type"]: "Occurrence".
108 ```
109
110 It creates four Topics: the owner, two generated Types and the default Name Type.
111 There are two Names and one Occurrence. The outer Occurrence Type is the first
112 generated Topic; its Name Type is the second generated Topic, whose Name has
113 the default Type. These are actual object references, not label-based links.
114
115 `variant-scope-embedded.ctm` creates seven Topics, five Names and one Variant.
116 The Parent Name has one Theme; the Variant has three actual Themes after union
117 with that Parent Scope. The second case exercises further nesting and identity
118 merging. Explicit Scope remains distinct from resulting TMDM Scope.
119
120 Original negative `ctm/invalid/embedded-topic-global-scope.ctm` is:
121
122 ```text
123 [-"This is not allowed"]
124 ```
125
126 It receives `CTM-REJECTION / :EMBEDDED-TOPIC-AT-TOP-LEVEL` at the end of the
127 source: the complete Embedded Topic is not followed by Association Roles.
128 The Template-dependent `embedded-topic-template.ctm` remains NOT-RUN. A failure
129 at `def` would not establish the required invalid Template-body semantics.
130
131 The reference report contains every full original source, Document IRI, counter
132 and observed graph. Independent Python checks compare identifier-property sets,
133 all Names/Variants/Occurrences/Associations/Roles, Scopes and generated locators
134 with the baselines. Observation ordinals are local references, not persistent IDs.
135
136 ## Executable Lisp inspection
137
138 From the repository root, in a fresh process:
139
140 ```lisp
141 (require :asdf)
142 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
143 (asdf:load-asd (truename "topic-maps.asd"))
144 (asdf:load-system "topic-maps/ctm")
145 (asdf:load-system "topic-maps/cxtm")
146 (defparameter *result*
147 (multiple-value-list
148 (topic-maps.ctm:deserialize-string
149 "owner - [-\"Type\"]: \"Name\" @?view (\"variant\" @[-\"extra\"]). ?view."
150 :document-iri "https://example.invalid/doc.ctm"
151 :wildcard-iri "https://identity.example.invalid/run"
152 :wildcard-counter 40)))
153 (defparameter *map* (first *result*))
154 (assert (= 43 (second *result*)))
155 (defparameter *owner*
156 (find-if (lambda (topic)
157 (member "https://example.invalid/doc.ctm#owner"
158 (topic-maps.tmdm:topic-item-identifiers topic) :test #'string=))
159 (topic-maps.tmdm:topic-map-topics *map*)))
160 (defparameter *name* (first (topic-maps.tmdm:topic-names *owner*)))
161 (assert (eq *owner* (topic-maps.tmdm:topic-name-parent *name*)))
162 (assert (equal '("https://identity.example.invalid/run#$__41")
163 (topic-maps.tmdm:topic-item-identifiers
164 (topic-maps.tmdm:topic-name-type *name*))))
165 (describe (topic-maps.tmdm:topic-name-type *name*))
166 (mapc #'describe (topic-maps.tmdm:topic-name-scope *name*))
167 (describe (first (topic-maps.tmdm:topic-name-variants *name*)))
168 (write-string (topic-maps.cxtm:canonicalize *map* :base-locator "https://example.invalid/doc.ctm"))
169 ```
170
171 ## Preserved boundaries
172
173 Reification, Templates, Include/Mergemap, `isa`/`ako`, CTM `*`, additional
174 Association arity and previously excluded datatype contexts are not implemented.
175 All same-map identity, Scope/Variant invariants and canonical retained-handle
176 contracts remain in the existing TMDM. No TMDM source changes are necessary.
177 The two known DateTime baseline FAILs remain visible. The independent previously
178 unregistered positive probes are not promoted by this slice.