]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-scope.md
Implement CTM Include and source-preserving template import
[topic-maps.git] / docs / reading-scope.md
1 # Reading Scope in CTM and TMDM — Slice 13
2
3 This slice starts from Topic Maps commit
4 `788899aea1a20b9cd8237c6106e6613e180d7362`. It extends the existing information
5 items. It adds neither a Scope information-item class nor HyperDoc integration.
6
7 ## Normative requirements
8
9 - [TMDM §§4.3, 5.3.3](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/):
10 Scope is an unordered set of Topics whose subjects jointly qualify a statement.
11 The empty set is unconstrained Scope. Topic Names (§5.4), Occurrences (§5.6)
12 and Associations (§5.7) carry Scope; Roles have no separate Scope (§5.8).
13 - Scope participates in item equality (§§5.4, 5.6–5.7). Topic merging replaces
14 Scope references (§6.2); newly equal items must then merge (§6.1). Name,
15 Occurrence and Association replacement copies their equal Scope (§§6.3, 6.5–6.6).
16 Different scopes are not unioned to force equality. No new Topic identity rule
17 is introduced by Name/Occurrence/Association equality.
18 - [CTM §§3.3.7, 3.3.9, 3.10–3.13](https://www.isotopicmaps.org/ctm/ctm.html):
19 `@ topic-ref (, topic-ref)*` assigns the resolved set after a Name string,
20 Occurrence literal or Association roles. Each statement is constructed after
21 its complete Scope is known. Identity resolution is the existing reader path.
22 - [CXTM §§3.6, 3.8–3.9, 3.12](https://www.isotopicmaps.org/cxtm/cxtm.html):
23 empty Scope has no representation; nonempty Scope emits `scope/scopingTopic`
24 references to canonical Topic numbers. Scope follows Type on Names/Occurrences
25 and Roles on Associations. LF and explicit empty-element end tags follow §3.1.
26 - CXTM §§4.4, 4.6–4.11: Scope members sort as Topics; sets compare by cardinality,
27 then sorted members. Name keys are Value, Type, Scope, Parent; Occurrence keys
28 are Value, Datatype, Type, Scope, Parent; Association keys are Type, Roles,
29 Scope, Parent. RolePlayed references use the resulting Association numbering.
30
31 The pinned corpus remains `cd165b150176c1d6842b37be9cc9051b40d4996b` and targets
32 the CTM draft dated 2010-03-31. Original baselines are evidence, not normative
33 rules. No Scope disagreement was found for these three selected contracts.
34
35 ## Original inputs and expected information items
36
37 Each Document IRI is the existing deterministic
38 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
39 plus its complete case ID, for example `ctm/in/name-scope.ctm`.
40 Local Topic identifiers resolve to that Document IRI plus `#identifier`.
41 The same IRI is passed as CXTM Base Locator; baseline `#...` locators are its
42 canonical relative representation, not the stored identity in the TMDM object.
43
44 Original `ctm/in/name-scope.ctm`:
45
46 ```text
47 topic
48 - "Name" @theme1, theme2.
49 ```
50
51 Four Topics: owner, two themes and default Name Type. One Name with Value
52 `Name`, Parent EQ to the owner, Type EQ to the default-type Topic whose SI is
53 `http://psi.topicmaps.org/iso13250/model/topic-name`. Scope holds the two actual
54 Theme objects. Baseline canonical Theme references: 1, 2.
55
56 Original `ctm/in/occurrence-scope.ctm` (trailing source whitespace is retained
57 in the vendored file and observation report):
58
59 ```text
60 topic
61 occtype: "Occurrence" @theme1, theme2.
62 ```
63
64 Four Topics: owner, Type and two themes. One Occurrence, Value `Occurrence`,
65 Datatype `http://www.w3.org/2001/XMLSchema#string`, Parent/Type EQ to the owner/
66 `occtype` Topics, Scope EQ-member references to the two themes. Baseline Theme
67 references: 2, 3. The Datatype remains a locator, not a Topic.
68
69 Original `ctm/in/association-scope.ctm`:
70
71 ```text
72 assoctype(roletype: topic)@theme1,theme2
73 ```
74
75 Five Topics: Association Type, Role Type, Player and two themes. One Association
76 owned by the Map, with the two-theme Scope and one Role. Role Parent is EQ to
77 that Association; Role Type and Player are EQ to the corresponding Topics.
78 Baseline Theme references: 3, 4. No Role Scope is synthesized.
79
80 The executable report records full unmodified source strings, actual public
81 properties and reference ordinals. Ordinals identify objects within that one
82 observation; they are neither Subject Identifiers nor permanent object addresses.
83 Separate tests assert EQ directly. The independent Python checker maps ordinals
84 back to distinct identifier-property sets before comparing baseline relationships.
85
86 ## Public API and merge contract
87
88 Existing creators now accept `:scope` (default NIL):
89
90 - `add-name topic value &key type scope`
91 - `add-default-name topic value &key scope`
92 - `add-occurrence topic type value &key datatype item-identifiers scope`
93 - `make-association map type roles &key scope`
94
95 `topic-name-scope`, `occurrence-scope` and `association-scope` resolve retained
96 item handles and return copies of the stored set lists. Arguments must be finite
97 proper lists of actual same-map Topics. Retired Topic arguments are resolved via
98 `canonical-topic`. Duplicate members are removed by canonical object identity.
99 Invalid lists, non-Topic members and foreign Themes signal `scope-error`, with
100 `scope-error-code` values `:invalid-scope`, `:invalid-theme`, `:foreign-theme`.
101 Validation occurs before mutation, including before automatic Name-Type creation.
102
103 Merging Theme A and Theme B rewrites all live Scope sets. Thus `{A,B}` becomes
104 `{C}`, while `{A,B,Z}` becomes `{C,Z}`. Formerly different items whose full equality
105 keys now match are replaced using the established canonical-handle contract.
106 Name/Occurrence/Association handles resolve through their existing canonical
107 readers; discarded Role handles also resolve to Roles of the current Association.
108 Occurrence item identifiers are unioned when equal Occurrences merge.
109
110 Stored values, datatypes and existing identity categories retain their earlier
111 semantics. Equal canonical XML is not used as a TMDM equality test.
112 Canonicalization validates current references and never normalizes the model or
113 compresses old handles. Tests compare live and retired states before/after output.
114
115 ## Inspect with ordinary Common Lisp
116
117 Start a fresh process in this checkout. These forms execute no writes or server:
118
119 ```lisp
120 (require :asdf)
121 (asdf:load-asd (merge-pathnames "topic-maps.asd" (uiop:getcwd)))
122 (asdf:load-system "topic-maps/ctm")
123 (let* ((document-iri "https://example.invalid/name-scope.ctm")
124 (map (topic-maps.ctm:deserialize-file
125 #p"vendor/cxtm/ctm/in/name-scope.ctm"
126 :document-iri document-iri))
127 (owner (find-if #'topic-maps.tmdm:topic-names
128 (topic-maps.tmdm:topic-map-topics map)))
129 (name (first (topic-maps.tmdm:topic-names owner)))
130 (themes (topic-maps.tmdm:topic-name-scope name)))
131 (assert (eq owner (topic-maps.tmdm:topic-name-parent name)))
132 (assert (= 2 (length themes)))
133 (assert (every (lambda (theme)
134 (member theme (topic-maps.tmdm:topic-map-topics map) :test #'eq))
135 themes))
136 (describe name)
137 (mapc #'describe themes)
138 (let ((merged (topic-maps.tmdm:merge-topics (first themes) (second themes))))
139 (assert (equal (list merged) (topic-maps.tmdm:topic-name-scope name)))
140 (assert (eq merged (topic-maps.tmdm:canonical-topic (first themes))))
141 (describe (topic-maps.tmdm:canonical-topic-name name))))
142 ```
143
144 The inspection deliberately uses its own absolute Document IRI. Imported byte
145 comparisons use each original contract's Document IRI/Base Locator instead.
146
147 ## Explicit limits
148
149 Only identity references already supported by the reader are accepted as Themes:
150 local identifiers, IRIs/QNames, explicit Item Identifiers and Subject Locators.
151 Embedded Topics, wildcards, Templates, Reification and Variants remain unsupported;
152 full CTM `topic-ref` conformity is not claimed. Missing Themes and malformed
153 comma lists are syntax rejections, with offsets and line/column diagnostics.
154 Scope on a bare Topic or inside a Role is rejected as misplaced syntax.
155
156 For a later Variant slice, CTM §3.12 requires adding the Parent Name Scope to the
157 Variant's stated Scope; TMDM §5.5 then requires a true superset. Variant equality,
158 merging and that constraint are not implemented here.
159
160 The HyperDoc Work-Topic `TMDM model` example-reading view still does not establish
161 a TMDM representation of its Work Topic. That separate Slice 12B semantic question
162 is unchanged. No HyperDoc repository, view or running image is modified here.