]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-item-identifiers.md
Support CTM associations with arbitrarily many roles
[topic-maps.git] / docs / reading-item-identifiers.md
1 # General Item Identifiers — Slice 16A
2
3 An Item Identifier addresses an information item, not automatically its subject.
4 All seven existing TMDM item kinds now store their own identifier set. There is
5 no separate identity registry, no Scope class, and no Reification implementation.
6
7 ## Normative contract and implementation choices
8
9 The published [TMDM](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
10 is authoritative: §5.1 defines identifier uniqueness; §§5.2–5.8 assign the
11 property to all seven item kinds. §§4.2–4.3 determine locator equality, and
12 §5.3.5 retains the distinct Topic II/SI/SL identity rules. §§6.2–6.7 require
13 identifier unions when the respective items merge. Non-Topic identifier equality
14 is not an additional structural equality rule.
15
16 The implementation compares stored resolved locator strings with `STRING=`.
17 It does not use CXTM base-relative or NFC-normalized output as identity keys.
18 Identifier collisions across distinct live items are rejected before mutation;
19 Topic–Topic collisions follow the existing Topic merge/preflight operation.
20 Equal Names, Variants, Occurrences, Associations and Roles retain their existing
21 structural equality rules and union their identifier metadata during replacement.
22
23 Returning replacement handles, rejecting invalid operations atomically and
24 copying locator strings are Lisp API choices. They preserve the existing API's
25 model invariants; they are not additional TMDM axioms.
26
27 ## Public API
28
29 ```lisp
30 (topic-maps.tmdm:item-identifiers item)
31 (topic-maps.tmdm:add-item-identifier item "urn:example:item")
32 ```
33
34 The first form returns a fresh list containing fresh strings. The second adds
35 one already validated, resolved absolute locator and returns the current
36 representative. Repeated assignment is idempotent. It accepts retained handles;
37 for Topics it delegates to `add-topic-identifier`. The model checks the absolute
38 scheme shape; full source IRI processing remains the CTM reader's responsibility.
39
40 `topic-map-item-identifiers`, `topic-item-identifiers`,
41 `topic-name-item-identifiers`, `variant-item-identifiers`,
42 `occurrence-item-identifiers`, `association-item-identifiers` and
43 `association-role-item-identifiers` expose the same defensive-copy contract.
44
45 Existing constructors are reused. Assign identifiers through the common API
46 after constructing the item. The existing `add-occurrence :item-identifiers`
47 option remains supported, including validation before construction and copying
48 the supplied list and strings. Two separate public calls are not one transaction.
49
50 Identifier problems have `item-identifier-error` and `item-identifier-error-code`.
51 Codes include `:invalid-item-identifiers`, `:duplicate-item-identifier` and
52 `:invalid-item`. Historical Occurrence/Topic routes also retain compatibility
53 with `occurrence-error` through a shared condition subclass.
54
55 ## Retained boundary for Slice 16B
56
57 The historical Topic-SI / Occurrence-II overlap guard remains explicitly
58 `:unsupported-reification-identity`, in both insertion directions. It is a
59 temporary implementation restriction, not a normative inference of Reification.
60 It is not extended to other item kinds. No `[reifier]`, `[reified]` or CTM `~`
61 support is introduced here. Its treatment requires the separate Slice 16B review.
62
63 ## CXTM and external examples
64
65 [CXTM](https://www.isotopicmaps.org/cxtm/cxtm.html) §§3.4–3.10 determine
66 placement: Map identifiers precede Topics; Topic identifiers precede Names;
67 Name identifiers follow Variants; Variant/Occurrence identifiers follow Scope;
68 Association identifiers follow Scope; Role identifiers follow Type. §3.13
69 defines `itemIdentifiers`, §§3.17–3.20 locator representation, and §§4.3–4.5
70 ordering. Existing information-item sort keys (§§4.6–4.11) are unchanged.
71 Serialization validates global uniqueness and never repairs or mutates the model.
72
73 Seven original `xtm2/in/itemid*.xtm` examples are manually constructed as TMDM
74 objects and compared byte-for-byte against their untouched CXTM baselines:
75 `itemid-tm`, `itemid`, `itemid-name`, `itemid-variant`, `itemid-occurrence`,
76 `itemid-association`, `itemid-role`.
77 These are **manual model/baseline comparisons, not XTM deserialization contracts**.
78 The 273 CTM imported contracts and their statuses are unchanged.
79
80 ## Inspect in a fresh Lisp process
81
82 Run these forms with this checkout as the working directory:
83
84 ```lisp
85 (require :asdf)
86 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
87 (asdf:load-asd (truename "topic-maps.asd"))
88 (asdf:load-system "topic-maps/cxtm")
89 (let* ((map (topic-maps.tmdm:make-topic-map))
90 (owner (topic-maps.tmdm:intern-topic map :subject-identifier "urn:example:owner"))
91 (name (topic-maps.tmdm:add-name owner "Example")))
92 (topic-maps.tmdm:add-item-identifier map "urn:example:map")
93 (topic-maps.tmdm:add-item-identifier name "urn:example:name")
94 (assert (equal '("urn:example:name") (topic-maps.tmdm:item-identifiers name)))
95 (assert (eq owner (topic-maps.tmdm:topic-name-parent name)))
96 (describe name)
97 (describe (topic-maps.tmdm:topic-name-type name))
98 (format t "~A" (topic-maps.cxtm:canonicalize map :base-locator "https://example.invalid/demo.ctm")))
99 ```