]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-datetime-occurrences.md
Support controlled XTM notation in CTM Mergemap with offline regression evidence
[topic-maps.git] / docs / reading-datetime-occurrences.md
1 # Reading DateTime Occurrences
2
3 ## Normative investigation before implementation
4
5 Base `2ad41cd1a945a4ce97824464de40646bb899259e`; clean
6 `codex/ctm-slice-9`; created `codex/ctm-slice-10`. All five original CTM inputs
7 and CXTM baselines were read unchanged before implementation.
8
9 Authorities:
10 - [Published CTM 3.4.1, printed p.5](https://cdn.standards.iteh.ai/samples/43940/6663ee28c1604551ac6adc02e22c6bb6/ISO-IEC-13250-6-2010.pdf#page=11): direct literals must be XSDT-valid; dateTime datatype is the XSD locator. CTM 3.2 removes a leading UTF-8 BOM. The HTML grammar has the previously documented day 01–09 omission; use the published XSDT-validity requirement.
11 - [TMDM 4.3–4.4, 5.6, 6.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/): stored values are Unicode strings, datatypes are separate locators; equality/duplicate removal use stored properties. Parent and Type remain Topics. Canonical handles retain the replacement-object contract.
12 - [CXTM 3.16, 4.9](https://www.isotopicmaps.org/cxtm/cxtm.html): dateTime output uses XSD canonical lexical form; Occurrences sort by stored value, datatype, type, scope, parent. Equal XML does not establish equal TMDM items.
13 - [XSD Part 2 Second Edition 3.2.7.1–3.2.7.3](https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#dateTime): year rules inherited from Date, time component bounds; 24:00:00 denotes next-day midnight; trim fractional trailing zeroes; every timezoned canonical value uses Z, converting the instant to UTC. Zero offsets +00:00/-00:00 both map to Z. No timezone is distinct from UTC.
14
15 ### A — leap seconds: a second baseline problem
16
17 [XSD 1.0 Appendix D.1](https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#isoformats)
18 permits whole seconds 00–60 and arbitrary fractional precision. It explicitly
19 says a leap second used with inappropriate month/day is interpreted in the
20 following minute. Therefore `1976-09-19T12:01:60` is accepted lexical input,
21 but its value interpretation is `1976-09-19T12:02:00`; unchanged `:60` is not
22 justified by the XSD 3.2.7.2 one-to-one canonical mapping. September 19 cannot
23 be a D.1 candidate day even under the permitted timezone range.
24 This is not an actual IERS leap-second-history validation.
25
26 The pinned `occurrence-datetime2.ctm` baseline retains `:60`. Execute the
27 canonical comparison and record the resulting **FAIL / known normative baseline
28 discrepancy**, separately from successful implementation assertions. Do not
29 rewrite the baseline or count it PASS. Genuine candidate-day UTC leap seconds
30 at 23:59:60 retain 60 (fractional trailing zeroes removed). Candidate local
31 leap seconds without a known zone, and candidate-day wrong-time cases, are
32 explicitly unsupported in canonicalization: the implementation does not guess
33 an absent zone or silently introduce a historical leap-second database.
34 XSD 1.1/XPath's exclusion of leap seconds does not replace the selected XSD 1.0.
35
36 ### B — nonzero timezone
37
38 XSD 3.2.7.2–3.2.7.3 and CXTM 3.16 require
39 `2011-01-01T00:00:00+02:00` → `2010-12-31T22:00:00Z`.
40 The unchanged upstream `occurrence-datetime-timezone2.ctm` baseline retains
41 `2011-01-01T00:00:00+02:00`. Preserve this documented discrepancy separately.
42 Validate/store offset-bearing qualified/API strings but do not implement
43 nonzero-offset canonicalization. Bare literals needing that conversion report
44 CTM-UNSUPPORTED; CXTM reports CXTM-UNSUPPORTED. The imported contract is NOT-RUN.
45 No filename-specific parsing/canonicalization rule is introduced.
46
47 ## Representation policy
48
49 Reuse the existing Occurrence class. Bare supported literals use canonical
50 strings, as in Slices 7–9; lexer tokens retain spelling. Qualified quoted strings
51 and direct API strings preserve valid lexical values, including whitespace,
52 fractions and offset spelling. Validation precedes mutation. Datatype is never
53 a synthesized Topic. CXTM is pure: it trims surrounding XML whitespace and
54 fractional trailing zeroes, handles next-day midnight and the supported leap
55 interpretations without changing model strings, references or retained handles.
56 Date validation is reused; no system calendar, timezone or floating point.
57 Year rollover uses character arithmetic, including arbitrary-length years and
58 -0001 → 0001 with no year zero. Slice 9's documented BCE leap interpretation
59 remains unchanged. Date timezone canonicalization is not extended.
60
61 ## Executable inspection
62
63 Run from the repository root in either supported SBCL:
64
65 ```lisp
66 (require :asdf)
67 (asdf:load-asd (truename "topic-maps.asd"))
68 (asdf:load-system "topic-maps/ctm")
69 (asdf:load-system "topic-maps/cxtm")
70 (let* ((map (topic-maps.ctm:deserialize-file
71 #p"vendor/cxtm/ctm/in/occurrence-datetime-fractional.ctm"
72 :document-iri "https://example.invalid/occurrence-datetime-fractional.ctm"))
73 (owner (find-if #'topic-maps.tmdm:topic-occurrences
74 (topic-maps.tmdm:topic-map-topics map)))
75 (item (first (topic-maps.tmdm:topic-occurrences owner))))
76 (describe item)
77 (describe (topic-maps.tmdm:occurrence-type item))
78 (list (eq owner (topic-maps.tmdm:occurrence-parent item))
79 (topic-maps.tmdm:occurrence-value item)
80 (topic-maps.tmdm:occurrence-datatype item)
81 (topic-maps.cxtm:canonicalize map
82 :base-locator "https://example.invalid/occurrence-datetime-fractional.ctm")))
83 ```
84
85 Public helpers in `topic-maps.tmdm`: `datetime-datatype`, `datetime-lexical-p`,
86 `canonical-datetime-lexical-form`. The last returns a canonical string plus
87 `:CANONICAL`, or NIL with a specific invalid/unsupported reason. No DateTime
88 information-item class or alternative equality/merge logic is introduced.
89
90 ## Original documents and observed results
91
92 The deterministic Document IRI / CXTM Base Locator remains
93 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
94 plus the corpus-relative path. Datatype is always the locator
95 `http://www.w3.org/2001/XMLSchema#dateTime`, never a Topic.
96
97 | Original | Stored bare value | Items | Original CXTM comparison |
98 |---|---|---|---|
99 | occurrence-datetime.ctm | `1976-09-19T12:01:01` | 2 Topics, 1 Occurrence | PASS, 370 bytes |
100 | occurrence-datetime2.ctm | `1976-09-19T12:02:00` | 2 Topics, 1 Occurrence | FAIL, known D.1 discrepancy; baseline `12:01:60` |
101 | occurrence-datetime-fractional.ctm | `2011-01-01T00:00:00.001` | 3 Topics, 2 Names, 1 Occurrence | PASS, 677 bytes |
102 | occurrence-datetime-timezone.ctm | `2011-01-01T00:00:00Z` | 3 Topics, 2 Names, 1 Occurrence | PASS, 674 bytes |
103 | occurrence-datetime-timezone2.ctm | No returned bare model; specific CTM-UNSUPPORTED | original contract NOT-RUN | documented required value `2010-12-31T22:00:00Z`; conversion unimplemented |
104
105 The first two owners have local item identifier `DocumentIRI#topic`; Type is
106 `DocumentIRI#occtype`. The named documents use `#some-topic` and `#datetime`
107 and reuse the standard default-name-type Topic. No Association or datatype Topic
108 is introduced. Raw Parent/Type references point to the actual canonical Topics.
109 Qualified/API offset values are valid stored strings, but CXTM refuses conversion.
110 `datetimes.json` separates actual model observations, local semantic assertions,
111 unsupported partial reads and normative discrepancies. `cxtm.json` contains full
112 actual/expected XML with separate imported `contractCounts`. Its passed/failed
113 check counters count assertions, not imported case outcomes.
114
115 Untouched original sources follow. The datetime2 file begins with UTF-8 BOM;
116 readable fences preserve U+FEFF, while the report/source bytes remain authoritative.
117
118 ### occurrence-datetime.ctm
119
120 ```text
121 topic
122 occtype: 1976-09-19T12:01:01 .
123 ```
124
125 ### occurrence-datetime2.ctm
126
127 ```text
128 #
129 # Test for leap seconds,
130 # c.f. <http://projects.topicmapslab.de/issues/2563>
131 #
132 topic
133 occtype: 1976-09-19T12:01:60 .
134 ```
135
136 ### occurrence-datetime-fractional.ctm
137
138 ```text
139 datetime - "datetime" .
140
141 some-topic - "some topic" ;
142 datetime: 2011-01-01T00:00:00.001
143 .
144 ```
145
146 ### occurrence-datetime-timezone.ctm
147
148 ```text
149 datetime - "datetime" .
150
151 some-topic - "some topic" ;
152 datetime: 2011-01-01T00:00:00Z
153 .
154 ```
155
156 ### occurrence-datetime-timezone2.ctm
157
158 ```text
159 datetime - "datetime" .
160
161 some-topic - "some topic" ;
162 datetime: 2011-01-01T00:00:00+02:00
163 .
164 ```