]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/tmdm-coverage-matrix.md
docs(tmdm): coverage matrix, relationship readers, default name types; run report
[topic-maps.git] / docs / tmdm-coverage-matrix.md
1 # TMDM coverage matrix
2
3 Clause-by-clause coverage of the Topic Maps Data Model by `topic-maps/tmdm`,
4 established by reading the source at commit
5 `88994c1b9e1edbf13e665e984a5c9c3b2cdf7575` and extended by the readers for
6 TMDM 7.2 and 7.3 described below.
7
8 The matrix keeps two questions apart:
9
10 - **Norm coverage**: is the structure or rule of the clause represented and
11 enforced by the model?
12 - **API**: does the library offer a function to read or state it?
13
14 A missing reader is a functional gap of the Common Lisp library. By itself it
15 is not evidence of a conformance defect.
16
17 ## Sources
18
19 The texts consulted are the public HTML texts, not the editions sold by ISO.
20 Every clause number below refers to them.
21
22 | Document | URL | Dated | SHA-256 of the retrieved octets |
23 |---|---|---|---|
24 | TMDM (ISO/IEC 13250-2) | https://www.isotopicmaps.org/sam/sam-model/2006-06-18/ | 2006-06-18 | `7f2fd03605d93c4c4c7759da1bcd1024fb0204dd34b522eff59a2ebdfb2a133b` |
25 | TMDM, later text | https://www.isotopicmaps.org/sam/sam-model/ | 2008-06-03 | begins `82d492565d9cef8e` |
26 | TMDM errata | https://www.isotopicmaps.org/sam/errata.html | 2008-06-03 | `cb7705d6abf8fdd0351d3b9c2c9c2ec795a36ca08cc151c15b29c277f15631d2` |
27
28 The two TMDM texts differ in clause 7.5 (the default name type identifier) and
29 in the wording of clause 6.3, point 5. The clauses 7.2 and 7.3 are the same in
30 both. CTM and CXTM coverage is tracked case by case in
31 [the conformance matrix](slice-22a-conformance-matrix.md) and
32 [the normative decisions](slice-22c-normative-decisions.md).
33
34 ## Matrix
35
36 "Tests" names the suites in `tests/` that exercise the row. File references are
37 to `src/tmdm/` unless a directory is given.
38
39 | Clause | Subject | Source | Tests | Norm coverage | API |
40 |---|---|---|---|---|---|
41 | 4.2–4.3 | Locators, strings, sets, null; equality by exact character sequence | `items.lisp`, `merging.lisp` | identity, merging | covered | — |
42 | 4.4 | Datatypes: any absolute datatype locator; string, IRI (absolute), integer, decimal, date and dateTime values validated | `occurrences.lisp`, `variants.lisp` | occurrence, integer, decimal, date, dateTime suites | covered; `anyType` values only through the XTM/XML path | readers and constructors |
43 | 5.1 | Item Identifiers on all seven item kinds; duplicate Item Identifiers on different items are an error | `item-identifiers.lisp` | `item-identifiers.lisp` | covered | `item-identifiers`, `add-item-identifier` |
44 | 5.2 | Topic Map item: topics, associations, reifier, item identifiers | `items.lisp` | reification, import | covered | readers |
45 | 5.3.2 | Subject Identifiers and Subject Locators as separate properties | `merging.lisp` | merging | covered | readers, `add-topic-identifier` |
46 | 5.3.3 | Scope as a set of Topics of the same map; the empty set is the unconstrained scope | `merging.lisp` | `ctm-scopes.lisp` | covered; how a scope defines a context is left open by the clause | scope readers |
47 | 5.3.4 | Reification within one map; a Topic cannot be reified | `reification.lisp` | `reification.lisp` | covered | `item-reifier`, `set-item-reifier`, `topic-reified` |
48 | 5.3.5 | Topic properties; computed roles played, reified and parent; the equality rule | `merging.lisp`, `items.lisp` | `merge-graphs.lisp`, `normalization-index.lisp` | covered | readers, `merge-topics` |
49 | 5.3.5 | Constraint "Topic identifier required" | `intern-topic` is the only constructor and always supplies a locator | not searched for a dedicated negative test | enforced by construction | `intern-topic` |
50 | 5.4 | Topic Name items and their equality | `merging.lisp` | `ctm-typed-names.lisp` | covered | `add-name`, readers |
51 | 5.5 | Variant items; scope a true superset of the Name's scope | `variants.lisp` | `ctm-variants.lisp` | covered | `add-variant`, readers |
52 | 5.6 | Occurrence items and their equality | `occurrences.lisp` | `ctm-occurrences.lisp` | covered | `add-occurrence`, readers |
53 | 5.7–5.8 | Association items (non-empty Role set) and Role items; equality | `associations.lisp` | `association-graphs.lisp`, `association-index.lisp`, arity | covered | `make-association`, readers |
54 | 6.1–6.7 | Merging of every item kind, including merging of Reifiers | `merging.lisp`, `associations.lisp`, `occurrences.lisp`, `variants.lisp`, `reification.lisp` | merging, reification | covered | `merge-topics`, `normalize-topic-map` |
55 | 6 | Taking over the content of another map | `import.lisp` | `map-import.lisp` | covered; the source map's own identifiers and reifier are not imported | `import-map-content` |
56 | 7.1 | Core Subjects cannot be merged with one another | `core-subjects.lisp` | `ctm-type-relationships.lisp` | covered for the eight identifiers of the 2006-06-18 text | `core-subject-identifiers` |
57 | 7.2 | The type-instance relationship | written by `ctm/reader.lisp` (`isa`) and `xtm/reader.lisp` (`instanceOf`) | 13 original inputs; `core-relationships.lisp` | covered: the Association is created and stored as the clause states | readers added: `type-instance-relationship`, `topic-type-associations`, `topic-instance-associations` |
58 | 7.3 | The supertype-subtype relationship | written by `ctm/reader.lisp` (`ako`) | as above | covered as stated; inferred relationships are not materialized, which the clause does not require | readers added: `supertype-subtype-relationship`, `topic-supertype-associations`, `topic-subtype-associations` |
59 | 7.4 | Sort names | the locator constant only | — | a sort Variant can be stored like any Variant | no reader; deferred |
60 | 7.5 | The default name type | implicit: `items.lisp`, `merging.lisp`; explicit: `ctm/reader.lisp`, `xtm/reader.lisp` | `ctm-typed-names.lisp`, `default-name-types.lisp` | both documented identifiers are handled as ordinary, different Subject Identifiers | `default-name-type-identifier` returns `.../topic-name` |
61
62 The XTM suites need SBCL 2.5.4 and the patched CXML sources. Where those are
63 absent they are not run; rows that depend on the XTM path say so.
64
65 ## Findings
66
67 **N1 — two default name type identifiers.** The 2006-06-18 text names
68 `.../model/name-type` in clause 7.5; the 2008-06-03 text names
69 `.../model/topic-name`. Both are supported as different identifiers and are
70 never equated automatically. Which text is authoritative is not decided here.
71 See [Two documented default name type identifiers](reading-type-relationships.md#two-documented-default-name-type-identifiers).
72
73 **N2 — edition boundary.** The editions published by ISO were not consulted.
74
75 **N3 — relationship recognition belongs in the library.** Before the readers
76 existed, a client had to recognize type-instance Associations itself. A reading
77 that compares only a Topic's first Subject Identifier, or that does not require
78 exactly two Roles, departs from clause 7.2. The readers apply the clause as
79 written.
80
81 **N4 — clients that label default name types.** A client that recognizes the
82 default name type only by `default-name-type-identifier` does not recognize a
83 Name Type carrying `.../name-type`. The library offers no function listing both
84 identifiers; none was added.
85
86 ## Not covered by this matrix
87
88 Inference over supertype-subtype relationships, evaluation of Scope as a
89 context, sort order of sort names, and any change to the Core Subject set.