]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-first-ctm-associations.md
Add string and URI Occurrences with merging and CXTM validation
[topic-maps.git] / docs / reading-first-ctm-associations.md
1 # Reading the First CTM Associations
2
3 Slice 3 starts from accepted commit `66664dbff6275d60dab1bc6a232fa70f7b916b8c`.
4 It adds actual Association and Association Role information items to the
5 existing same-map identity model. It reads one or two Role declarations.
6
7 ## The original unary source
8
9 The unmodified `ctm/in/association.ctm` contains, without a final newline:
10
11 ```ctm
12 assoctype(roletype: topic)
13 ```
14
15 Its Document IRI is:
16
17 ```text
18 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/association.ctm
19 ```
20
21 Writing that IRI as D, the actual model has:
22
23 ```text
24 M : TOPIC-MAP; TOPICS=(T-A T-R T-P); ASSOCIATIONS=(A)
25 T-A : TOPIC; ITEM-IDENTIFIERS={D#assoctype}; PARENT=M
26 T-R : TOPIC; ITEM-IDENTIFIERS={D#roletype}; PARENT=M
27 T-P : TOPIC; ITEM-IDENTIFIERS={D#topic}; PARENT=M
28 A : ASSOCIATION; TYPE=T-A; ROLES=(R); PARENT=M
29 R : ASSOCIATION-ROLE; TYPE=T-R; PLAYER=T-P; PARENT=A
30 T-P.ROLES-PLAYED=(R) [computed]
31 ```
32
33 All three Topics have empty Subject Identifier, Subject Locator and Name sets.
34 The other Topics' computed roles-played sets are empty. No default-name-type
35 Topic is created. Braces denote sets, not CTM or canonical syntax.
36
37 There are **five items apart from the container: three Topics, one Association
38 and one Role**. Including the Topic Map, there are six. The Role is an
39 independent inspectable object. The unchanged CXTM baseline explicitly contains
40 its `role` element, type/player references and the player's `rolePlayed` link.
41
42 ## The original binary source
43
44 The unmodified `ctm/in/association-binary.ctm`, also without a final newline:
45
46 ```ctm
47 assoctype(roletype1: topic1, roletype2 :topic2)
48 ```
49
50 Document IRI:
51
52 ```text
53 https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/association-binary.ctm
54 ```
55
56 The model contains five Topics identified by D plus `#assoctype`, `#roletype1`,
57 `#topic1`, `#roletype2`, `#topic2`; one Association; and two Roles. The
58 Association's type is the first Topic. The Role pairs are `(roletype1, topic1)`
59 and `(roletype2, topic2)`, with the Association as their shared parent. Each
60 player's roles-played set contains its corresponding Role. All Topic parent
61 links point to the same map. Including the map, these are nine information
62 items. Baseline numbering differs from creation order and is not reused as
63 local object identity.
64
65 ## Normative interpretation
66
67 [CTM ISO/IEC 13250-6:2010](https://www.isotopicmaps.org/ctm/ctm.html) §§3.3.7,
68 3.3.11 and 3.13 govern Topic references, types and Association/Role creation.
69 The Role separator needs layout on at least one side of `:`; both source
70 forms above meet the grammar. Existing comment handling also supplies layout.
71
72 [TMDM ISO/IEC 13250-2:2006](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
73 §§5.2, 5.3.5, 5.7 and 5.8 govern containment, roles played, Associations and
74 Roles. Topic merges replace Association type, Role type and Role player
75 references under §6.2. Equal Roles and Associations are normalized under
76 §§6.7 and 6.6 for the implemented empty/null properties.
77
78 Association equality compares type and the unordered structural Role set.
79 Within one Association, a Role is equal by type/player and its shared parent.
80 Roles in different unequal Associations do not coalesce just because their
81 type/player pairs match. Comparing Association Role sets uses those signatures
82 under the compared parents, avoiding the parent/equality cycle. When equal
83 Associations merge, the replacement receives one equal Role set, whose parent
84 references are updated; discarded equivalent Role handles resolve to that set.
85
86 ## The required late-merge investigation
87
88 Construct the Association before merging its participating Topics:
89
90 ```lisp
91 (require :asdf)
92 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
93 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
94 (asdf:load-system "topic-maps/ctm")
95 (defparameter *map*
96 (topic-maps.ctm:deserialize-string "a(a: b)"
97 :document-iri "https://example.invalid/association-merge.ctm"))
98 (defparameter *association* (first (topic-maps.tmdm:topic-map-associations *map*)))
99 (defparameter *role* (first (topic-maps.tmdm:association-roles *association*)))
100 (defparameter *old-a* (topic-maps.tmdm:association-type *association*))
101 (defparameter *old-b* (topic-maps.tmdm:association-role-player *role*))
102 (topic-maps.tmdm:add-topic-identifier *old-a* :subject-identifier "urn:shared")
103 (defparameter *merged*
104 (topic-maps.tmdm:add-topic-identifier *old-b* :subject-identifier "urn:shared"))
105 (list (eq *merged* (topic-maps.tmdm:association-type *association*))
106 (eq *merged* (topic-maps.tmdm:association-role-type *role*))
107 (eq *merged* (topic-maps.tmdm:association-role-player *role*)))
108 ;; => (T T T)
109 (eq *old-a* *merged*) ; => NIL
110 (eq (topic-maps.tmdm:canonical-topic *old-a*) *merged*) ; => T
111 (describe *map*)
112 (describe *association*)
113 (describe *role*)
114 (topic-maps.tmdm:topic-roles-played *old-b*) ; => the one live Role
115 ```
116
117 Stored live references are rewritten, not repaired only by getters. Tests
118 inspect the raw fields as well as the public API. Seven affected-reference
119 combinations, transitive replacements and combined Name/Association references
120 are checked. Duplicate Role and Association removal has its own retained-handle
121 tests. Another 128 graph/order variants construct a binary Association first
122 and then perform all possible four-Topic identity connections.
123
124 ## Public API and scope
125
126 `make-association map type roles` takes a Topic and a nonempty list of
127 `(role-type player)` Topic pairs. It resolves obsolete Topic handles, checks
128 that all references belong to the map before mutation, constructs Role items,
129 normalizes duplicates and returns the live Association. The model operation
130 accepts a nonempty Role set; the CTM reader is limited to at most two Role
131 declarations before duplicate removal. Larger CTM arities signal UNSUPPORTED.
132
133 Accessors: `topic-map-associations`, `association-parent`, `association-type`,
134 `association-roles`, `association-role-parent`, `association-role-type`,
135 `association-role-player`, and computed `topic-roles-played`. Set readers return
136 copies. `canonical-association` and `canonical-association-role` resolve retained
137 handles after duplicate merging; use them before inspecting obsolete objects
138 with DESCRIBE. None of these functions performs CXTM canonicalization.
139
140 An Association's unmaterialized scope is implicitly empty. On Associations and
141 Roles, unmaterialized item identifiers are empty and reifier is null; Roles
142 have no separate scope property. Scope/reification syntax, larger arities, embedded
143 Topics, prefix directives, Templates, typed Names, Occurrences, Variants,
144 cross-map merging and full IRI grammar validation remain outside this slice.
145 No type-instance or supertype-subtype special Associations are introduced.
146
147 ## Evidence boundary
148
149 Eight unchanged originals are exercised: `association.ctm`,
150 `association-binary.ctm`, `association-binary-duplicate.ctm`,
151 `association-type-sid.ctm` and `association-with-comment{,2,3,4}.ctm`.
152 The property oracle matches Topics by separate identifier sets, Associations
153 by type and Role signatures, and checks Role parent/player/type and roles-played
154 links under that mapping. It does not generate or canonicalize XML.
155
156 All previous 16 positive records are unchanged. All 24 inspected positive
157 CXTM-EQUAL contracts remain NOT-RUN; the sole imported PASS remains the specific
158 undefined-prefix rejection. All 272 other imported contracts stay NOT-RUN.
159 The pinned corpus targets draft 2010-03-31; property agreement does not establish
160 full ISO conformity. Consult `slice-3-validation.md` for exact test evidence.