]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-date-occurrences.md
Implement XTM occurrence core and register eleven originals (Slice 22G)
[topic-maps.git] / docs / reading-date-occurrences.md
1 # Reading Date Occurrences
2
3 ## Rules established before implementation
4
5 Base: accepted Slice 8 `195d5f5444d776096b765d04c815c23c3db5f84c`;
6 initial branch `codex/ctm-slice-8`, clean index/tree. The five original inputs,
7 five CXTM baselines and five original invalid inputs were read first.
8 Corpus pin remains `cd165b150176c1d6842b37be9cc9051b40d4996b`.
9
10 - [Published CTM §3.4.1, printed p.5](https://cdn.standards.iteh.ai/samples/43940/6663ee28c1604551ac6adc02e22c6bb6/ISO-IEC-13250-6-2010.pdf)
11 requires directly supported date literals to be XSDT-valid and assigns xsd:date.
12 Recognition remains in the existing numeric/date token path. Bare dates have
13 no timezone; their final dot is CTM punctuation. §3.2 removes a leading UTF-8 BOM.
14 The [HTML mirror](https://www.isotopicmaps.org/ctm/ctm.html) production 35
15 omits days 01–09; the published preview's normative XSDT validity rule and
16 the selected test inputs support them. `occurrence-date2` explicitly tests
17 that draft error. This discrepancy is recorded, not silently copied into the
18 reader or presented as a verified correction of the unavailable Annex grammar.
19 - [TMDM §§4.3–4.4, 5.6, 6.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/):
20 the existing Occurrence stores a Unicode value string and a datatype locator.
21 Parent and Type remain Topic references. Equality/merging compare stored
22 properties, not mathematical equivalence or output XML. Canonical handles and
23 identifier union retain their existing contract.
24 - [CXTM §§3.16, 4.9](https://www.isotopicmaps.org/cxtm/cxtm.html):
25 render the canonical datatype lexical form, without mutation. Order by stored
26 value string, then datatype, Type, Scope and Parent, not chronological order.
27 - [XML Schema Part 2 Second Edition §§3.2.7.1, 3.2.9–3.2.9.2, 4.3.6, D, E.1](https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#date):
28 years have at least four ASCII digits; no plus, no zero year, no leading zero
29 on an extended year. Negative years use this edition's numbering. Month/day
30 have two digits; calendar validity includes month lengths and Gregorian
31 divisibility by 4, 100 and 400. Whitespace collapse affects interpretation,
32 while qualified stored strings remain unchanged. Timezone-free valid dates
33 are canonical once surrounding XML whitespace is removed.
34
35 Bare literal deserialization uses the established canonical-string policy;
36 qualified quoted strings and the model API retain their valid lexical strings.
37 This policy is distinct from TMDM equality. No local timezone/calendar API,
38 floating point, Lisp reader or EVAL is used. Extended years are validated with
39 character processing and a bounded modulo-400 accumulator, not a fixed-width year.
40
41 Valid timezone-qualified explicit xsd:date strings can be represented and
42 validated lexically; CXTM reports them explicitly unsupported. XSD date timezone
43 normalization (§3.2.9.2) needs recoverable-timezone/day adjustment, not simple
44 DateTime-to-UTC truncation. This slice implements neither conversion. Bare CTM
45 dates with timezone suffixes are rejected as outside the date grammar.
46
47 ## Executable inspection
48
49 From the repository root, with the established SBCL runtime:
50
51 ```lisp
52 (require :asdf)
53 (asdf:load-asd (truename "topic-maps.asd"))
54 (asdf:load-system "topic-maps/ctm")
55 (asdf:load-system "topic-maps/cxtm")
56 (let* ((map (topic-maps.ctm:deserialize-file
57 #p"vendor/cxtm/ctm/in/occurrence-date.ctm"
58 :document-iri "https://example.invalid/occurrence-date.ctm"))
59 (owner (find-if #'topic-maps.tmdm:topic-occurrences
60 (topic-maps.tmdm:topic-map-topics map)))
61 (item (first (topic-maps.tmdm:topic-occurrences owner))))
62 (describe item)
63 (describe (topic-maps.tmdm:occurrence-type item))
64 (list (eq owner (topic-maps.tmdm:occurrence-parent item))
65 (topic-maps.tmdm:occurrence-value item)
66 (topic-maps.tmdm:occurrence-datatype item)
67 (topic-maps.cxtm:canonicalize map
68 :base-locator "https://example.invalid/occurrence-date.ctm")))
69 ```
70
71 Public additions in `topic-maps.tmdm`: `date-datatype`, `date-lexical-p`,
72 `canonical-date-lexical-form`. The latter returns a string and `:CANONICAL`
73 for supported valid data, or NIL plus an invalid-date code / `:UNSUPPORTED-TIMEZONE`.
74 Existing deserializer, `add-occurrence`, `canonical-occurrence` and CXTM APIs
75 remain the entry points; no separate Date information-item class is introduced.
76
77 ## BCE calendar qualification
78
79 XML Schema 1.0's year labels omit zero. For BCE leap validation this slice
80 applies the divisibility formula to the signed lexical year, following E.1's
81 `yearValue` arithmetic (thus `-0004-02-29` is accepted, `-0100-02-29` rejected).
82 No astronomical-year shift is silently introduced. This is an explicit 1.0
83 interpretation, not a claim that BCE leap-day semantics were unambiguous:
84 [W3C's later clarification](https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime)
85 acknowledges the ambiguity of XSD 1.0 for BCE leap years. XSD 1.1 is not used to
86 permit year zero or change the selected edition. All five original positive
87 fixtures avoid BCE February 29, so this qualification does not affect their
88 conformance comparisons. Future date arithmetic must revisit this decision.
89
90 ## Original sources and observed information items
91
92 All Dates use the locator `http://www.w3.org/2001/XMLSchema#date`.
93 No datatype Topic is synthesized. Each document creates one Topic Map and
94 one owner Topic with its local Item Identifier `DocumentIRI#topic`; its type
95 Topics have `DocumentIRI#occtype`, or `#o1` through `#o4` for date3. SI/SL,
96 Names, Associations and Occurrence Item Identifiers are empty. Parent/Type
97 are the actual stored canonical Topic objects, not copied labels.
98
99 The deterministic Document IRI is
100 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
101 plus `ctm/in/filename.ctm` (or `ctm/invalid/filename.ctm`). The same absolute
102 IRI is the CXTM Base Locator, preserving the accepted relative-locator policy.
103
104 | Original positive file | Stored value strings | Topics / Occurrences | Exact CXTM bytes | Result |
105 |---|---|---|---:|---|
106 | occurrence-date.ctm | `1976-09-19` | 2 / 1 | 357 | PASS |
107 | occurrence-date2.ctm | `1976-10-09` | 2 / 1 | 357 | PASS |
108 | occurrence-date3.ctm | `0001-12-02`, `0011-12-02`, `0111-12-02`, `1111-12-02` | 5 / 4 | 1066 | PASS |
109 | occurrence-date-negative.ctm | `-1976-09-19` | 2 / 1 | 358 | PASS |
110 | occurrence-date-another-century.ctm | `191976-09-19` | 2 / 1 | 359 | PASS |
111
112 In model construction order the owner has ordinal 1 and its Type Topics have
113 ordinals 2 onward. CXTM's independent numbering places the Type Topic(s) first,
114 owner last, and numbers each owner's Occurrences from 1. `dates.json` records
115 actual properties and references; `cxtm.json` separately records full actual and
116 expected XML. The source records in dates.json round-trip to unchanged input bytes.
117 The following readable code fences omit trailing whitespace; the report retains
118 it exactly, including BOMs.
119 The two BOM-bearing examples retain U+FEFF in the source records; only the
120 reader's byte-to-character deserialization removes the leading BOM.
121
122 ### occurrence-date.ctm
123
124 ```text
125 topic
126 occtype: 1976-09-19.
127 ```
128
129 ### occurrence-date2.ctm — starts with UTF-8 BOM EF BB BF
130
131 ```text
132 #
133 # Tests if implementations did not copy and paste the
134 # error from the CTM draft 2010-03-29
135 # <http://projects.topicmapslab.de/issues/2563>
136 #
137 topic
138 occtype: 1976-10-09.
139 ```
140
141 ### occurrence-date3.ctm — starts with UTF-8 BOM EF BB BF
142
143 ```text
144 #
145 # Different valid dates acc. to <http://www.w3.org/TR/xmlschema-2/#dateTime>
146 #
147 topic
148 o1: 0001-12-02;
149 o2: 0011-12-02;
150 o3: 0111-12-02;
151 o4: 1111-12-02
152 .
153 ```
154
155 ### occurrence-date-negative.ctm
156
157 ```text
158 topic
159 occtype: -1976-09-19.
160 ```
161
162 ### occurrence-date-another-century.ctm
163
164 ```text
165 topic
166 occtype: 191976-09-19.
167 ```
168
169 | Original negative file | Specific rejection | Source position | Result |
170 |---|---|---|---|
171 | date-invalid-day.ctm | `INVALID-DATE-DAY` | line 2, column 14 | PASS |
172 | date-invalid-month.ctm | `INVALID-DATE-MONTH` | line 2, column 14 | PASS |
173 | date-invalid-year.ctm | `INVALID-DATE-YEAR` | line 2, column 14 | PASS |
174 | date-invalid-year2.ctm | `INVALID-DATE-YEAR` | line 6, column 14 | PASS |
175 | date-invalid-year3.ctm | `INVALID-DATE-YEAR` | line 6, column 14 | PASS |
176
177 All five conditions are `CTM-REJECTION`, with character position, source name,
178 line and column; none is `CTM-UNSUPPORTED` or an I/O failure. No successful
179 TMDM result is returned. Exact source strings are in `dates.json`; readable renderings follow below.
180
181 ### date-invalid-day.ctm
182
183 ```text
184 topic
185 occtype: 2000-12-32.
186 ```
187
188 ### date-invalid-month.ctm
189
190 ```text
191 topic
192 occtype: 2000-13-02.
193 ```
194
195 ### date-invalid-year.ctm
196
197 ```text
198 topic
199 occtype: 0000-01-02. # See <http://www.w3.org/TR/xmlschema-2/#dateTime> "[...] '0000' is prohibited [...]"
200 ```
201
202 ### date-invalid-year2.ctm
203
204 ```text
205 #
206 # See <http://www.w3.org/TR/xmlschema-2/#dateTime>
207 # "[...] if more than four digits, leading zeros are prohibited [...]"
208 #
209 topic
210 occtype: 00002000-01-02.
211 ```
212
213 ### date-invalid-year3.ctm
214
215 ```text
216 #
217 # See <http://www.w3.org/TR/xmlschema-2/#dateTime>
218 # "[...] also note that a plus sign is not permitted [...]"
219 #
220 topic
221 occtype: +2000-01-02.
222 ```
223
224 ## Remaining boundaries
225
226 DateTime, DateTime conversion, date recoverable-timezone normalization,
227 Variants, nonempty Scope, Reification, Templates, CTM `*`, cross-document merging
228 and HyperDoc integration remain unsupported. Unselected imported cases remain
229 NOT-RUN even if their syntax is incidentally accepted. Valid explicit date
230 zones are recognized as such, then CXTM signals `CXTM-UNSUPPORTED` with
231 `:DATE-TIMEZONE-CANONICALIZATION`; malformed dates remain specific rejections.
232 Date-like QNames retain QName semantics and do not become literal tokens.
233 See `slice-9-validation.md` for execution evidence and all reproduction commands.