]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-variants.md
Support XTM topic name reification (Slice 21M)
[topic-maps.git] / docs / reading-variants.md
1 # Reading Variants — Slice 14
2
3 Base: `aeb017e4f4846f2e6a701e581d20eef84a8b83d9`. The independent model now
4 supports unreified Variant information items under Topic Names. HyperDoc is not
5 a dependency and no HyperDoc image is loaded by these tests.
6
7 ## Normative requirements and local policy
8
9 [TMDM §5.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/) specifies
10 Value, Datatype, Scope, Reifier, Item Identifiers and Parent Name. Scope is a
11 nonempty Topic set properly containing the Parent Name's Scope. A Variant has
12 no Type Topic. Equality uses Value, Datatype, Scope and Parent. §§6.1/6.4 remove
13 equal Variants; §6.3 unions Variants when Names merge; §6.2 replaces Theme references.
14 Reifier is null and Item Identifiers empty in this bounded implementation.
15
16 [CTM §§3.4.1, 3.11–3.12](https://www.isotopicmaps.org/ctm/ctm.html) specify
17 `'(' literal scope reifier? ')'` after a Name.
18 The shared literal reader supplies the same values/datatypes as for Occurrences.
19 The reader unions explicitly supplied themes E with current Parent Name Scope P.
20 Actual TMDM Scope V is P union E, and P must be a proper subset of V. Explicit
21 source Scope E is syntax, not another TMDM property. `@p` under Parent Scope
22 `{p}` is invalid even though the written Scope is nonempty.
23
24 [CXTM §§3.6–3.7, 3.12–3.21, 4.2–4.8](https://www.isotopicmaps.org/cxtm/cxtm.html)
25 nest Variants under their Names, numbered from 1 within that Name's sorted set.
26 Children are Value, Datatype, full Scope and, if any, Item Identifiers. Scope
27 references canonical Topic numbers. Variant keys are Value, Datatype, Scope,
28 Parent; sets sort by size then sorted members. String values precede locator
29 values. Value normalization reuses the existing datatype-specific CXTM code;
30 Datatype locators are not base-normalized. Serialization never mutates the model.
31
32 Local value policy is unchanged: bare supported CTM numeric/date literals use
33 their established value representation; qualified strings retain their lexical
34 values. The model does not infer equality from equal canonical XML values.
35 For example, quoted `"01"^^xsd:integer` and `"1"^^xsd:integer` remain distinct
36 stored strings, while CXTM renders both as `1`.
37
38 **Merge policy:** if a Theme merge would collapse Variant Scope to Parent Scope,
39 the API signals `variant-error` / `:variant-scope-collapse` before any mutation.
40 This is a local atomic failure contract preserving TMDM §5.5, not an error
41 recovery algorithm prescribed by the standard. The preflight computes the full
42 prospective identity closure, including automatic identifier-triggered merges.
43 It never deletes a Variant, manufactures a Theme, or changes a value to hide
44 the constraint violation. Valid reductions such as `{a,b,x}` to `{c,x}` with
45 Parent `{a,b}` to `{c}` remain supported.
46
47 ## Unchanged corpus sources and baseline expectations
48
49 Pin: `cd165b150176c1d6842b37be9cc9051b40d4996b`; draft qualification 2010-03-31.
50 Each Document IRI is `https://ctm-tests.example.invalid/` + pin + `/` + case ID.
51 The same absolute IRI is used as CXTM Base Locator. Stored local item identifiers
52 are absolute; `#theme` in a baseline is the CXTM relative locator representation.
53
54 `ctm/in/variant.ctm`:
55 ```text
56 topic - "Name" ("name" @theme).
57 ```
58 Three Topics: owner, theme and default Name Type. One Name, Parent EQ owner,
59 Type EQ the Topic with SI `http://psi.topicmaps.org/iso13250/model/topic-name`.
60 One Variant, Value `name`, Datatype `http://www.w3.org/2001/XMLSchema#string`,
61 Parent EQ Name, Scope containing the actual theme Topic. Baseline Theme ref 1.
62
63 `ctm/in/variants.ctm`:
64 ```text
65 topic - "Name" ("name" @theme)("nome" @theme2).
66 ```
67 Four Topics, one Name, two Variants; Values `name` and `nome`, string Datatype,
68 Scopes containing theme and theme2 respectively. Baseline refs 1 and 2.
69
70 `ctm/in/variant-duplicate.ctm`:
71 ```text
72 topic - "Name" ("name" @theme)("name" @theme).
73 ```
74 Three Topics, one Name, one Variant after duplicate removal. No datatype Topic
75 or independent Variant Type is introduced.
76
77 `ctm/invalid/variant-no-scope.ctm` (including its initial blank line):
78 ```text
79
80 topic
81 - "name" ("variant").
82 ```
83 Specific `ctm-rejection`, `:expected-variant-scope`, zero-based character 28,
84 line 3, column 22. An unsupported feature or unrelated exception is not a PASS.
85
86 The three positive outputs are compared to original baselines as raw UTF-8 bytes.
87 Direct EQ assertions and the independent JSON/XML checker additionally compare
88 actual information items and relationships. Report ordinals identify objects
89 within that observation only; they are not permanent Subject Identifiers.
90
91 `variant-reifier.ctm` additionally needs Reification; `variant-scope-embedded`
92 and `embedded2` need Embedded Topics; `embedded3` and `embedded4` also need
93 Templates. Their imported contracts remain NOT-RUN. Diagnostic probes verify
94 UNSUPPORTED without recording success. There is no selected Variant baseline
95 conflict; the two existing DateTime baseline FAILs remain visible.
96
97 ## Public API and executable inspection
98
99 `add-variant name value :datatype locator :scope actual-themes` accepts an actual
100 Scope, not just the extra CTM themes. Datatype defaults to xsd:string. The Parent
101 Name and themes are resolved through existing canonical handles. All arguments
102 are checked before mutation. Public set readers return copies. Replaced objects
103 remain reachable through `canonical-variant` and `canonical-topic-name`; old EQ
104 identity does not change. Names retain their own independent Type Topics.
105
106 Run from the repository root in a fresh SBCL process:
107
108 ```lisp
109 (require :asdf)
110 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
111 (asdf:load-asd (truename "topic-maps.asd"))
112 (asdf:load-system "topic-maps/ctm")
113 (asdf:load-system "topic-maps/cxtm")
114 (defparameter *map*
115 (topic-maps.ctm:deserialize-string
116 "topic - kind:\"Name\" @parent-theme (\"variant\" @extra-theme)."
117 :document-iri "https://example.invalid/variants.ctm"))
118 (defparameter *name*
119 (first (loop for topic in (topic-maps.tmdm:topic-map-topics *map*)
120 append (topic-maps.tmdm:topic-names topic))))
121 (defparameter *variant* (first (topic-maps.tmdm:topic-name-variants *name*)))
122 (assert (eq *name* (topic-maps.tmdm:variant-parent *variant*)))
123 (assert (= 1 (length (topic-maps.tmdm:topic-name-scope *name*))))
124 (assert (= 2 (length (topic-maps.tmdm:variant-scope *variant*))))
125 (describe *variant*)
126 (describe (topic-maps.tmdm:variant-parent *variant*))
127 (mapc #'describe (topic-maps.tmdm:variant-scope *variant*))
128 (write-string (topic-maps.cxtm:canonicalize *map*
129 :base-locator "https://example.invalid/variants.ctm"))
130 ```
131
132 No Source spans, persistent Inspector URLs or additional HyperDoc Views are
133 created. The independent model remains ordinary inspectable Lisp structures.