]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-datetime-timezones.md
Document Topic Maps conformance closure plan for Slice 22A
[topic-maps.git] / docs / reading-datetime-timezones.md
1 # Reading DateTime Timezone Canonicalization
2
3 ## Normative decisions before implementation
4
5 Slice 11 starts at `8741d155d948c7317945eee423a977940cad995e`.
6 The original timezone2 source and baseline were read unchanged. Reuse the
7 existing Date/DateTime validators, Occurrence model and canonicalizer.
8
9 - [CXTM 3.16](https://www.isotopicmaps.org/cxtm/cxtm.html):
10 serialize dateTime using the XML Schema canonical lexical representation.
11 CXTM 4.3/4.9 compare the stored string properties in their specified order;
12 this is not dateTime instant ordering or sorting the rendered XML values.
13 - [XML Schema Part 2, Second Edition 3.2.7.1–3.2.7.4](https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#dateTime):
14 validate lexical syntax and calendar first; offsets have magnitude at most
15 14:00, with minute 00 at hour 14. Subtract the signed offset to obtain UTC,
16 with calendar carry, then write Z. +00:00 and -00:00 both become Z.
17 An absent zone stays absent. Normalize 24:00:00 to next-day midnight;
18 remove trailing fractional zeroes without losing other digits. XSD instant
19 comparison in 3.2.7.4 does not redefine TMDM string equality.
20 - [TMDM 4.3–4.4, 5.6, 6.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/):
21 Value is a Unicode string; Datatype is a separate locator; Parent and Type
22 are Topic references. Equal stored properties trigger duplicate removal,
23 preserving the existing replacement-object/canonical-occurrence contract.
24 Equal canonical XML alone does not establish equal Occurrence items.
25
26 Keep the established deserialization policy: bare literals store their derived
27 canonical string. Datatype-qualified quoted strings and direct API values
28 retain their valid lexical spelling, including offset and XML whitespace.
29 CXTM computes a separate representation without model or handle mutation.
30
31 ## Deliberate calendar limits
32
33 Reuse the accepted Slice 9/10 calendar interpretation; do not silently import
34 XSD 1.1 astronomical year zero. Newly supported nonzero-offset conversions
35 requiring a day change in/into BCE are explicitly unsupported: the pre-existing
36 XSD 1.0 BCE leap-calendar qualification is not resolved here. BCE conversions
37 within one day need no calendar assumption. Existing zero/absent-zone behavior,
38 including its documented year rollover, is retained.
39
40 Nonzero-offset second-60 conversion is explicitly unsupported, without guessing
41 a UTC leap-second context. Existing absent/zero-zone leap handling is unchanged,
42 including the published D.1 qualification and original datetime2 FAIL.
43 Date timezone canonicalization is outside this slice.
44
45 ## Original timezone2 contract
46
47 Input: `2011-01-01T00:00:00+02:00`.
48 Required UTC value: `2010-12-31T22:00:00Z`.
49 The pinned upstream baseline retains the input offset. Run the complete
50 CTM → TMDM → CXTM contract and record its actual mismatch as FAIL; never alter
51 the baseline or use a filename-specific canonicalization rule.
52
53 ## Executable inspection
54
55 Run from the repository root in a fresh SBCL:
56
57 ```lisp
58 (require :asdf)
59 (asdf:load-asd (truename "topic-maps.asd"))
60 (asdf:load-system "topic-maps/ctm")
61 (asdf:load-system "topic-maps/cxtm")
62 (let* ((map (topic-maps.ctm:deserialize-string
63 "a t: \"2011-01-01T00:00:00+02:00\"^^<http://www.w3.org/2001/XMLSchema#dateTime>."
64 :document-iri "https://example.invalid/timezone.ctm"))
65 (owner (find-if #'topic-maps.tmdm:topic-occurrences
66 (topic-maps.tmdm:topic-map-topics map)))
67 (item (first (topic-maps.tmdm:topic-occurrences owner))))
68 (describe item)
69 (describe (topic-maps.tmdm:occurrence-type item))
70 (format t "~&Stored: ~A~%Datatype: ~A~%~A"
71 (topic-maps.tmdm:occurrence-value item)
72 (topic-maps.tmdm:occurrence-datatype item)
73 (topic-maps.cxtm:canonicalize map
74 :base-locator "https://example.invalid/timezone.ctm")))
75 ```
76
77 The stored string remains `2011-01-01T00:00:00+02:00`; CXTM emits
78 `<value>2010-12-31T22:00:00Z</value>`. Replacing the quoted qualified value
79 with the bare literal stores the canonical UTC string, retaining Slice 10's
80 deserialization policy. Both examples have two Topics and one Occurrence;
81 the datatype locator does not create another Topic.