idnits 2.17.1 draft-ietf-tzdist-service-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 23, 2015) is 3201 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-ietf-appsawg-http-problem-00 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) Summary: 12 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft Spherical Cow Group 4 Intended status: Standards Track C. Daboo 5 Expires: January 24, 2016 Apple 6 July 23, 2015 8 Time Zone Data Distribution Service 9 draft-ietf-tzdist-service-11 11 Abstract 13 This document defines a time zone data distribution service that 14 allows reliable, secure and fast delivery of time zone data and leap 15 second rules to client systems such as calendaring and scheduling 16 applications or operating systems. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 24, 2016. 35 Copyright Notice 37 Copyright (c) 2015 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 5 54 2. Architectural Overview . . . . . . . . . . . . . . . . . . . 5 55 3. General Considerations . . . . . . . . . . . . . . . . . . . 6 56 3.1. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 7 57 3.2. Time Zone Data . . . . . . . . . . . . . . . . . . . . . 7 58 3.3. Time Zone Meta-Data . . . . . . . . . . . . . . . . . . . 7 59 3.4. Time Zone Data Server . . . . . . . . . . . . . . . . . . 7 60 3.5. Observance . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.6. Time Zone Identifiers . . . . . . . . . . . . . . . . . . 7 62 3.7. Time Zone Aliases . . . . . . . . . . . . . . . . . . . . 8 63 3.8. Time Zone Localized Names . . . . . . . . . . . . . . . . 8 64 3.9. Truncating Time Zones . . . . . . . . . . . . . . . . . . 8 65 3.10. Time Zone Versions . . . . . . . . . . . . . . . . . . . 10 66 4. Time Zone Data Distribution Service Protocol . . . . . . . . 10 67 4.1. Server Protocol . . . . . . . . . . . . . . . . . . . . . 10 68 4.1.1. Time Zone Queries . . . . . . . . . . . . . . . . . . 11 69 4.1.2. Time Zone Formats . . . . . . . . . . . . . . . . . . 11 70 4.1.3. Time Zone Localization . . . . . . . . . . . . . . . 12 71 4.1.4. Conditional Time Zone Requests . . . . . . . . . . . 12 72 4.1.5. Expanded Time Zone Data . . . . . . . . . . . . . . . 14 73 4.1.6. Server Requirements . . . . . . . . . . . . . . . . . 14 74 4.1.7. Error Responses . . . . . . . . . . . . . . . . . . . 14 75 4.1.8. Extensions . . . . . . . . . . . . . . . . . . . . . 14 76 4.2. Client Guidelines . . . . . . . . . . . . . . . . . . . . 14 77 4.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 14 78 4.2.1.1. Time Zone Data Distribution Service SRV Service 79 Labels . . . . . . . . . . . . . . . . . . . . . 15 80 4.2.1.2. Time Zone Data Distribution Service TXT Records . 15 81 4.2.1.3. Time Zone Data Distribution Service Well-Known 82 URI . . . . . . . . . . . . . . . . . . . . . . . 16 83 4.2.1.3.1. Example: well-known URI redirects to actual 84 context path . . . . . . . . . . . . . . . . 17 85 4.2.2. Synchronization of Time Zones . . . . . . . . . . . . 17 86 4.2.2.1. Initial Synchronization of All Time Zones . . . . 17 87 4.2.2.2. Subsequent Synchronization of All Time Zones . . 17 88 4.2.2.3. Synchronization with Pre-Existing Time Zone Data 18 89 5. Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 90 5.1. "capabilities" Action . . . . . . . . . . . . . . . . . . 18 91 5.1.1. Example: get capabilities . . . . . . . . . . . . . . 19 92 5.2. "list" Action . . . . . . . . . . . . . . . . . . . . . . 21 93 5.2.1. Example: list time zone identifiers . . . . . . . . . 22 94 5.3. "get" Action . . . . . . . . . . . . . . . . . . . . . . 23 95 5.3.1. Example: get time zone data . . . . . . . . . . . . . 24 96 5.3.2. Example: conditional get time zone data . . . . . . . 24 97 5.3.3. Example: get time zone data using a time zone alias . 25 98 5.3.4. Example: get truncated time zone data . . . . . . . . 26 99 5.3.5. Example: request for a non-existent time zone . . . . 27 100 5.4. "expand" Action . . . . . . . . . . . . . . . . . . . . . 28 101 5.4.1. Example: expanded JSON data format . . . . . . . . . 29 102 5.5. "find" Action . . . . . . . . . . . . . . . . . . . . . . 30 103 5.5.1. Example: find action . . . . . . . . . . . . . . . . 32 104 5.6. "leapseconds" Action . . . . . . . . . . . . . . . . . . 34 105 5.6.1. Example: get leapsecond information . . . . . . . . . 34 106 6. JSON Definitions . . . . . . . . . . . . . . . . . . . . . . 35 107 6.1. capabilities Action Response . . . . . . . . . . . . . . 36 108 6.2. list/find Action Response . . . . . . . . . . . . . . . . 39 109 6.3. expand Action Response . . . . . . . . . . . . . . . . . 40 110 6.4. leapseconds Action Response . . . . . . . . . . . . . . . 42 111 7. New iCalendar Properties . . . . . . . . . . . . . . . . . . 42 112 7.1. Time Zone Upper Bound . . . . . . . . . . . . . . . . . . 42 113 7.2. Time Zone Identifier Alias Property . . . . . . . . . . . 43 114 8. Security Considerations . . . . . . . . . . . . . . . . . . . 44 115 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 45 116 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 117 10.1. Service Actions Registration . . . . . . . . . . . . . . 47 118 10.1.1. Service Actions Registration Procedure . . . . . . . 47 119 10.1.2. Registration Template for Actions . . . . . . . . . 48 120 10.1.3. Actions Registry . . . . . . . . . . . . . . . . . . 49 121 10.2. timezone Well-Known URI Registration . . . . . . . . . . 49 122 10.3. Service Name Registrations . . . . . . . . . . . . . . . 49 123 10.3.1. timezone Service Name Registration . . . . . . . . . 50 124 10.3.2. timezones Service Name Registration . . . . . . . . 50 125 10.4. tzdist Identifiers Registry . . . . . . . . . . . . . . 50 126 10.4.1. Registration of invalid-action Error URN . . . . . . 51 127 10.4.2. Registration of invalid-changedsince Error URN . . . 51 128 10.4.3. Registration of tzid-not-found Error URN . . . . . . 52 129 10.4.4. Registration of invalid-format Error URN . . . . . . 52 130 10.4.5. Registration of invalid-start Error URN . . . . . . 52 131 10.4.6. Registration of invalid-end Error URN . . . . . . . 53 132 10.4.7. Registration of invalid-pattern Error URN . . . . . 53 133 10.5. iCalendar Property Registrations . . . . . . . . . . . . 53 134 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 54 135 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 136 12.1. Normative References . . . . . . . . . . . . . . . . . . 54 137 12.2. Informative References . . . . . . . . . . . . . . . . . 56 138 Appendix A. Change History (to be removed prior to publication 139 as an RFC) . . . . . . . . . . . . . . . . . . . . . 56 140 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 142 1. Introduction 144 Time zone data typically combines a coordinated universal time (UTC) 145 offset with daylight saving time (DST) rules. Time zones are 146 typically tied to specific geographic and geopolitical regions. 147 Whilst the UTC offset for particular regions changes infrequently, 148 DST rules can change frequently and sometimes with very little notice 149 (maybe hours before a change comes into effect). 151 Calendaring and scheduling systems, such as those that use iCalendar 152 [RFC5545], as well as operating systems, critically rely on time zone 153 data to determine the correct local time. As such they need to be 154 kept up to date with changes to time zone data. To date there has 155 been no fast and easy way to do that. Time zone data is often 156 supplied in the form of a set of data files that have to be 157 "compiled" into a suitable database format for use by the client 158 application or operating system. In the case of operating systems, 159 often those changes only get propagated to client machines when there 160 is an operating system update, which can be infrequent, resulting in 161 inaccurate time zone data being present for significant amounts of 162 time. In some cases, old versions of operating systems stop being 163 supported, but are still in use and thus require users to manually 164 "patch" their system to keep up to date with time zone changes. 166 Along with time zone data, it is also important to track the use of 167 leap seconds to allow a mapping between International Atomic Time 168 (TAI) and UTC. Leap seconds can be added (or possibly removed) at 169 various times of year in an irregular pattern typically determined by 170 precise astronomical observations. The insertion of leap seconds 171 into UTC is currently the responsibility of the International Earth 172 Rotation Service. 174 This specification defines a time zone data distribution service 175 protocol that allows for fast, reliable and accurate delivery of time 176 zone data and leap second information to client systems. This 177 protocol is based on HTTP [RFC7230] using a simple JSON [RFC7159] 178 based API. 180 This specification does not define the source of the time zone data 181 or leap second information. It is assumed that a reliable and 182 accurate source is available. One such source is the IANA hosted 183 time zone database [RFC6557]. 185 Discussion of this document has taken place on the tzdist working 186 group mailing list . 188 1.1. Conventions 190 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 191 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 192 document are to be interpreted as described in [RFC2119]. 194 Unless otherwise indicated, [RFC3339] UTC date-time values use a "Z" 195 suffix, and not fixed numeric offsets. 197 This specification contains examples of HTTP requests and responses. 198 In some cases, additional line breaks have been introduced into the 199 request or response data to match maximum line length limits of this 200 document. 202 2. Architectural Overview 204 The overall process for the delivery of time zone data can be 205 visualized via the diagram shown below. 207 ==================== ==================== 208 (a) | Contributors | | Contributors | 209 ==================== ==================== 210 | | 211 ==================== ==================== 212 (b) | Publisher A | | Publisher B | 213 ==================== ==================== 214 \ / 215 ==================== 216 (c) | Root Provider | 217 ==================== 218 / | \ 219 / | \ 220 ====================== | ====================== 221 (d) | Secondary Provider | | | Secondary Provider | 222 ====================== | ====================== 223 | | | | 224 | | | | 225 ========== ========== ========== ========== 226 (e) | Client | | Client | | Client | | Client | 227 ========== ========== ========== ========== 229 Figure 1: Time Zone Data Distribution Service Architecture 231 The overall service is made up of several layers: 233 (a) Contributors: Individuals, governments or organizations which 234 provide information about time zones to the publishing process. 236 There can be many contributors. Note this specification does not 237 address how contributions are made. 239 (b) Publishers: Publishers aggregate information from contributors, 240 determine the reliability of the information and, based on that, 241 generate time zone data. There can be many publishers, each 242 getting information from many different contributors. In some 243 cases a publisher may choose to "re-publish" data from another 244 publisher. 246 (c) Root Providers: Servers which obtain and then provide the time 247 zone data from publishers and make that available to other servers 248 or clients. There can be many root providers. Root providers can 249 choose to supply time zone data from one or more publishers. 251 (d) Secondary Providers: Servers which handle the bulk of the 252 requests and reduce the load on root servers. These will 253 typically be simple caches of the root server, located closer to 254 clients. For example a large Internet Service Provider (ISP) may 255 choose to setup their own secondary provider to allow clients 256 within their network to make requests of that server rather than 257 making requests of servers outside their network. Secondary 258 servers will cache and periodically refresh data from the root 259 servers. 261 (e) Clients: Applications, operating systems etc., that make use of 262 time zone data and retrieve that from either root or secondary 263 providers. 265 Some of those layers may be coalesced by implementors. For example, 266 a vendor may choose to implement the entire service as a single 267 monolithic virtual server with the address embedded in distributed 268 systems. Others may choose to provide a service consisting of 269 multiple layers of providers, many secondary servers and a small 270 number of root servers. 272 This specification is concerned only with the protocol used to 273 exchange data between providers and from provider to client. This 274 specification does not define how contributors pass their information 275 to publishers, nor how those publishers vet that information to 276 obtain trustworthy data, nor the format of the data produced by the 277 publishers. 279 3. General Considerations 281 This section defines several terms and explains some key concepts 282 used in this specification. 284 3.1. Time Zone 286 A description of the past and predicted future timekeeping practices 287 of a collection of clocks that are intended to agree. 289 Note that the term "time zone" does not have the common meaning of a 290 region of the world at a specific UTC offset, possibly modified by 291 daylight saving time. For example, the "Central European Time" zone 292 can correspond to several time zones "Europe/Berlin", "Europe/Paris", 293 etc., because subregions have kept time differently in the past. 295 3.2. Time Zone Data 297 Data that defines a single time zone, including an identifier, UTC 298 offset values, DST rules, and other information such as time zone 299 abbreviations. 301 3.3. Time Zone Meta-Data 303 Data that describes additional properties of a time zone that is not 304 itself included in the time zone data. This can include such things 305 as the publisher name, version identifier, aliases, and localized 306 names (see below). 308 3.4. Time Zone Data Server 310 A server implementing the Time Zone Data Distribution Service 311 Protocol defined by this specification. 313 3.5. Observance 315 A time zone with varying rules for the UTC offset will have adjacent 316 periods of time that use different UTC offsets. Each period of time 317 with a constant UTC offset is called an observance. 319 3.6. Time Zone Identifiers 321 Time zone identifiers are unique names associated with each time 322 zone, as defined by publishers. The iCalendar [RFC5545] 323 specification has a "TZID" property and parameter whose value is set 324 to the corresponding time zone identifier, and used to identify time 325 zone data and relate time zones to start and end dates in events, 326 etc. This specification does not define what format of time zone 327 identifiers should be used. It is possible that time zone 328 identifiers from different publishers overlap, and there might be a 329 need for a provider to distinguish those with some form of 330 "namespace" prefix identifying the publisher. However, development 331 of a standard (global) time zone identifier naming scheme is out of 332 scope for this specification. 334 3.7. Time Zone Aliases 336 Time zone aliases map a name onto a time zone identifier. For 337 example "US/Eastern" is usually mapped on to "America/New_York". 338 Time zone aliases are typically used interchangeably with time zone 339 identifiers when presenting information to users. 341 A time zone data distribution service needs to maintain time zone 342 alias mapping information, and expose that data to clients as well as 343 allow clients to query for time zone data using aliases. When 344 returning time zone data to a client, the server returns the data 345 with an identifier matching the query, but it can include one or more 346 additional identifiers in the data to provide a hint to the client 347 that alternative identifiers are available. For example, a query for 348 "US/Eastern" could include additional identifiers for "America/ 349 New_York" or "America/Montreal". 351 The set of aliases may vary depending on whether time zone data is 352 truncated (see Section 3.9). For example, a client located in the US 353 state of Michigan may see "US/Eastern" as an alias for "America/ 354 Detroit" whereas a client in the US state of New Jersey may see it as 355 an alias for "America/New_York", and all three names may be aliases 356 if time zones are truncated to post-2013 data. 358 3.8. Time Zone Localized Names 360 Localized names are names for time zones which can be presented to a 361 user in their own language. Each time zone may have one or more 362 localized names associated with it. Names would typically be unique 363 in their own locale as they might be presented to the user in a list. 364 Localized names are distinct from abbreviations commonly used for UTC 365 offsets within a time zone. For example, the time zone "America/ 366 New_York" may have the localized name "Nueva York" in a Spanish 367 locale, as distinct from the abbreviations "EST" and "EDT" which may 368 or may not have their own localizations. 370 A time zone data distribution service might need to maintain 371 localized name information, for one or more chosen languages, as well 372 as allow clients to query for time zone data using localized names. 374 3.9. Truncating Time Zones 376 Time zone data can contain information about past and future UTC 377 offsets that may not be relevant for a particular server's intended 378 clients. For example, calendaring and scheduling clients are likely 379 most concerned with time zone data that covers a period for one or 380 two years in the past on into the future, as users typically create 381 new events only for the present and future. Similarly, time zone 382 data might contain a large amount of "future" information about 383 transitions occurring many decades into the future. Again, clients 384 might be concerned only with a smaller range into the future, and 385 data past that point might be unnecessary. 387 To avoid having to send unnecessary data, servers can choose to 388 truncate time zone data to a range determined by start and end point 389 date and time values, and provide only offsets and rules between 390 those points. If such truncation is done, the server MUST include 391 the ranges it is using in the "capabilities" action response (see 392 Section 6.1), so that clients can take appropriate action if they 393 need time zone data for times outside of those ranges. 395 The truncation points at the start and end of a range are always a 396 UTC date-time value, with the start point being "inclusive" to the 397 overall range, and the end point being "exclusive" to the overall 398 range (i.e., the end value is just past the end of the last valid 399 value in the range). A server will advertise a truncation range for 400 the truncated data it can supply, or provide an indicator that it can 401 truncate at any start or end point to produce arbitrary ranges. In 402 addition, the server can advertise that it supplies untruncated data 403 - that is data that covers the full range of times available from the 404 source publisher. In the absence of any indication of truncated data 405 available on the server, the server will supply only untruncated 406 data. 408 When truncating the start of a "VTIMEZONE" component, the server MUST 409 include exactly one "STANDARD" or "DAYLIGHT" sub-component with a 410 "DTSTART" property value that matches the start point of the 411 truncation range, and appropriate "TZOFFSETFROM" and "TZOFFSETTO" 412 properties to indicate the correct offset in effect right before and 413 after the truncation range start point. This sub-component, which is 414 the first observance defined by the time zone data, represents the 415 earliest valid date-time covered by the time zone data in the 416 truncated "VTIMEZONE" component. 418 When truncating the end of a "VTIMEZONE" component, the server MUST 419 include a "TZUNTIL" iCalendar property (Section 7.1) in the 420 "VTIMEZONE" component to indicate the end point of the truncation 421 range. 423 3.10. Time Zone Versions 425 Time zone data changes over time and it is important for consumers of 426 that data to stay up to date with the latest versions. As a result 427 it is useful to identify individual time zones with a specific 428 version number or version identifier as supplied by the time zone 429 data publisher. There are two common models which time zone data 430 publishers might use to publish updates to time zone data: 432 a. with the "monolithic" model, the data for all time zones is 433 published in one go, with a single version number or identifier 434 applied to the entire data set. e.g., a publisher producing data 435 several times a year might use version identifiers "2015a", 436 "2015b", etc. 438 b. with the "incremental" model, each time zone has its own version 439 identifier, so that each time zone can be independently updated 440 without impacting any others. e.g., if the initial data has 441 version "A.1" for time zone "A", and "B.1" for time zone "B", and 442 then time zone "B" changes; when the data is next published, time 443 zone "A" will still have version "A.1", but time zone "B" will 444 now have "B.2". 446 A time zone data distribution service needs to ensure that the 447 version identifiers used by the time zone data publisher are 448 available to any client, along with the actual publisher name on a 449 per-time zone basis. This allows clients to compare publisher/ 450 version details on any server, with existing locally cached client 451 data, and only fetch those time zones which have actually changed 452 (see Section 4.2.2 for more details on how clients synchronize data 453 from the server). 455 4. Time Zone Data Distribution Service Protocol 457 4.1. Server Protocol 459 The time zone data distribution service protocol uses HTTP [RFC7230] 460 for query and delivery of time zone data and meta-data, and leap 461 second information. The interactions with the HTTP server can be 462 broken down into a set of "actions" that define the overall function 463 being requested (see Section 5). Each action targets a specific HTTP 464 resource using the GET method, with various request-URI parameters 465 altering the behavior as needed. 467 The HTTP resources used for requests will be identified via URI 468 templates [RFC6570]. The overall time zone data distribution service 469 has a "context path" request-URI template defined as "{/service- 470 prefix}". This "root" prefix is discovered by the client as per 471 Section 4.2.1. Request-URIs that target time zone data directly use 472 the prefix template "{/service-prefix,data-prefix}". The second 473 component of the prefix template can be used to introduce additional 474 path segments in the request-URI to allow for alternative ways to 475 "partition" the time zone data. For example, time zone data might be 476 partitioned by publisher release dates, or version identifiers. This 477 specification does not define any partitions, which is left for 478 future extensions. When the "data-prefix" variable is empty, the 479 server is expected to return the current version of time zone data it 480 has for all publishers it supports. 482 All URI template variable values, and URI request parameters that 483 contain text values, MUST be encoded using the UTF-8 [RFC3629] 484 character set. All responses MUST return data using the UTF-8 485 [RFC3629] character set. It is important to note that any "/" 486 characters, which are frequently found in time zone identifiers, are 487 percent-encoded when used in the value of a path segment expansion 488 variable in a URI template (as per Section 3.2.6 of [RFC6570]). Thus 489 the time zone identifier "America/New_York" would appear as 490 "America%2FNew_York" when used as the value for the "{/tzid}" URI 491 template variable defined later in this specification. 493 The server provides time zone meta-data in the form of a JSON 494 [RFC7159] object. Clients can directly request the time zone meta- 495 data, or issues queries for subsets of meta-data that match specific 496 criteria. 498 Security and privacy considerations for this protocol are discussed 499 in detail in Section 8 and Section 9, respectively. 501 4.1.1. Time Zone Queries 503 Time zone identifiers, aliases or localized names can be used to 504 query for time zone data or meta-data. This will be more explicitly 505 defined below for each action. In general however, if a "tzid" URI 506 template variable is used, then the value may be an identifier or an 507 alias. When the "pattern" URI query parameter is used it may be an 508 identifier, an alias or a localized name. 510 4.1.2. Time Zone Formats 512 The default media type [RFC2046] format for returning time zone data 513 is the iCalendar [RFC5545] data format. In addition, the iCalendar- 514 in-XML [RFC6321], and iCalendar-in-JSON [RFC7265] representations are 515 also available. Clients use the HTTP Accept header field (see 516 Section 5.3.2 of [RFC7231]) to indicate their preference for the 517 returned data format. Servers indicate the available formats that 518 they support via the "capabilities" action response (Section 5.1). 520 4.1.3. Time Zone Localization 522 As per Section 3.8, time zone data can support localized names. 523 Clients use the HTTP Accept-Language header field (see Section 5.3.5 524 of [RFC7231]) to indicate their preference for the language used for 525 localized names in the response data. 527 4.1.4. Conditional Time Zone Requests 529 When time zone data or meta-data changes, it needs to be distributed 530 in a timely manner because changes to local time offsets might occur 531 within a few days of the publication of the time zone data changes. 532 Typically, the number of time zones that change is small, whilst the 533 overall number of time zones can be large. Thus, when a client is 534 using more than a few time zones, it is more efficient for the client 535 to be able to download only those time zones that have changed (an 536 incremental update). 538 Clients initially request a full list of time zones from the server 539 using a "list" action request (see Section 5.2). The response to 540 that request includes two items the client caches for use with 541 subsequent "conditional" (incremental update) requests: 543 1. An opaque synchronization token in the "synctoken" JSON member. 544 This token changes whenever there is a change to any meta-data 545 associated with one or more time zones (where the meta-data is 546 the information reported in the "list" action response for each 547 time zone). 549 2. The HTTP ETag header field value for each time zone returned in 550 the response. The ETag header field value is returned in the 551 "etag" JSON member, and corresponds to the ETag header field 552 value that would be returned when executing a "get" action 553 request (see Section 5.3) against the corresponding time zone 554 data resource. 556 For subsequent updates to cached data, clients can use the following 557 procedure: 559 a. Send a "list" action request with a "changedsince" URI query 560 parameter with its value set to the last opaque synchronization 561 token returned by the server. The server will return time zone 562 meta-data for only those time zones that have changed since the 563 last request. 565 b. The client will cache the new opaque synchronization token 566 returned in the response for the next incremental update, along 567 with the returned time zone meta-data information. 569 c. The client will check each time zone meta-data to see if the 570 "etag" value is different from that of any cached time zone data 571 it has. 573 d. The client will use "get" action request to update any cached 574 time zone data for those time zone's whose ETag header field 575 value has changed. 577 Note that time zone meta-data will always change when the 578 corresponding time zone data changes. However, the converse is not 579 true: it is possible for some piece of the time zone meta-data to 580 change without the corresponding time zone data changing. e.g., for 581 the case of a "monolithic" publisher (see Section 3.10), the version 582 identifier in every time zone meta-data element will change with each 583 new published revision, however, only a small subset of time zone 584 data will actually change. 586 If a client needs data for only one, or a small set of time zones 587 (e.g., a clock in a fixed location), then it can use a conditional 588 HTTP request to determine if the time zone data has changed and 589 retrieve the new data. The full details of HTTP conditional requests 590 are described in [RFC7232], what follows is a brief summary of what a 591 client typically does. 593 a. When the client retrieves the time zone data from the server 594 using a "get" action (see Section 5.3) the server will include an 595 HTTP ETag header field in the response. 597 b. The client will store the value of that header field along with 598 the request-URI used for the request. 600 c. When the client wants to check for an update, it issues another 601 "get" action HTTP request on the original request-URI, but this 602 time it includes an If-None-Match HTTP request header field, with 603 a value set to the ETag header field value from the previous 604 response. If the data for the time zone has not changed, the 605 server will return a 304 (Not Modified) HTTP response. If the 606 data has changed, the server will return a normal HTTP success 607 response which will include the changed data, as well as a new 608 value for the ETag header field. 610 Clients SHOULD poll for changes, using an appropriate conditional 611 request, at least once a day. A server acting as a secondary 612 provider, caching time zone data from another server, SHOULD poll for 613 changes once per hour. See Section 8 on expected client and server 614 behavior regarding high request rates. 616 4.1.5. Expanded Time Zone Data 618 Determining time zone offsets at a particular point in time is often 619 a complicated process, as the rules for daylight saving time can be 620 complex. To help with this, the time zone data distribution service 621 provides an action that allows clients to request the server to 622 expand a time zone into a set of "observances" over a fixed period of 623 time (see Section 5.4). Each of these observances describes a UTC 624 onset time and UTC offsets for the prior time and the observance 625 time. Together, these provide a quick way for "thin" clients to 626 determine an appropriate UTC offset for an arbitrary date without 627 having to do full time zone expansion themselves. 629 4.1.6. Server Requirements 631 To enable a simple client implementation, servers SHOULD ensure that 632 they provide or cache data for all commonly used time zones, from 633 various publishers. That allows client implementations to configure 634 a single server to get all time zone data. In turn, any server can 635 refresh any of the data from any other server - though the root 636 servers may provide the most up-to-date copy of the data. 638 4.1.7. Error Responses 640 When an HTTP error response is returned to the client, the server 641 SHOULD return a JSON "problem detail" object in the response body, as 642 per [I-D.ietf-appsawg-http-problem]. Every JSON "problem detail" 643 object MUST include a "type" member with a uri value matching the 644 applicable error code (defined for each action in Section 5). 646 4.1.8. Extensions 648 This protocol is designed to be extensible through a standards based 649 registration mechanism (see Section 10). It is anticipated that 650 other useful time zone actions will be added in the future (e.g., 651 mapping a geographical location to time zone identifiers, getting 652 change history for time zones), and so, servers MUST return a 653 description of their capabilities. This will allow clients to 654 determine if new features have been installed and, if not, fall back 655 on earlier features or disable some client capabilities. 657 4.2. Client Guidelines 659 4.2.1. Discovery 661 Client implementations need to either know where the time zone data 662 distribution service is located or discover it through some 663 mechanism. To use a time zone data distribution service, a client 664 needs a fully qualified domain name (FQDN), port and HTTP request-URI 665 path. The request-URI path found via discovery is the "context path" 666 for the service itself. The "context path" is used as the value of 667 the "service-prefix" URI template variable when executing actions 668 (see Section 5). 670 The following sub-sections describe two methods of service discovery 671 using DNS SRV records [RFC2782] and an HTTP "well-known" [RFC5785] 672 resource. However, alternative mechanisms could also be used (e.g., 673 a DHCP server option [RFC2131]). 675 4.2.1.1. Time Zone Data Distribution Service SRV Service Labels 677 [RFC2782] defines a DNS-based service discovery protocol that has 678 been widely adopted as a means of locating particular services within 679 a local area network and beyond, using SRV RR records. This can be 680 used to discover a service's FQDN and port. 682 This specification adds two service types for use with SRV records: 684 timezone: Identifies a Time Zone Data Distribution server that uses 685 HTTP without transport layer security ([RFC2818]). 687 timezones: Identifies a Time Zone Data Distribution server that uses 688 HTTP with transport layer security ([RFC2818]). 690 Clients MUST honor "TTL", "Priority" and "Weight" values in the SRV 691 records, as described by [RFC2782]. 693 Example: service record for server without transport layer security. 695 _timezone._tcp SRV 0 1 80 tz.example.com. 697 Example: service record for server with transport layer security. 699 _timezones._tcp SRV 0 1 443 tz.example.com. 701 4.2.1.2. Time Zone Data Distribution Service TXT Records 703 When SRV RRs are used to advertise a time zone data distribution 704 service, it is also convenient to be able to specify a "context path" 705 in the DNS to be retrieved at the same time. To enable that, this 706 specification uses a TXT RR that follows the syntax defined in 707 Section 6 of [RFC6763] and defines a "path" key for use in that 708 record. The value of the key MUST be the actual "context path" to 709 the corresponding service on the server. 711 A site might provide TXT records in addition to SRV records for each 712 service. When present, clients MUST use the "path" value as the 713 "context path" for the service in HTTP requests. When not present, 714 clients use the ".well-known" URI approach described in 715 Section 4.2.1.3. 717 As per Section 8, the server MAY require authentication when a client 718 tries to access the path URI specified by the TXT RR (i.e., the 719 server would return a 401 status response to the unauthenticated 720 request from the client, then return a redirect response after a 721 successful authentication by the client). 723 Example: text record for service with transport layer security. 725 _timezones._tcp TXT path=/timezones 727 4.2.1.3. Time Zone Data Distribution Service Well-Known URI 729 A "well-known" URI [RFC5785] is registered by this specification for 730 the Time Zone Data Distribution service, "timezone" (see Section 10). 731 This URI points to a resource that the client can use as the initial 732 "context path" for the service they are trying to connect to. The 733 server MUST redirect HTTP requests for that resource to the actual 734 "context path" using one of the available mechanisms provided by HTTP 735 (e.g., using an appropriate 3xx status response). Clients MUST 736 handle HTTP redirects on the ".well-known" URI, taking into account 737 security restrictions on redirects described in Section 8. Servers 738 MUST NOT locate the actual time zone data distribution service 739 endpoint at the ".well-known" URI as per Section 1.1 of [RFC5785]. 740 The "well-known" URI MUST be present on the server, even when a TXT 741 RR (Section 4.2.1.2) is used in the DNS to specify a "context path". 743 Servers SHOULD set an appropriate Cache-Control header field value 744 (as per Section 5.2 of [RFC7234]) in the redirect response to ensure 745 caching occurs as needed, or as required by the type of response 746 generated. For example, if it is anticipated that the location of 747 the redirect might change over time, then an appropriate "max-age" 748 value would be used. 750 As per Section 8, the server MAY require authentication when a client 751 tries to access the ".well-known" URI (i.e., the server would return 752 a 401 status response to the unauthenticated request from the client, 753 then return the redirect response after a successful authentication 754 by the client). 756 4.2.1.3.1. Example: well-known URI redirects to actual context path 758 A Time Zone Data Distribution server has a "context path" that is 759 "/servlet/timezone". The client will use "/.well-known/timezone" as 760 the path for the service after it has first found the FQDN and port 761 number via an SRV lookup or via manual entry of information by the 762 user. When the client makes its initial HTTP request against 763 "/.well-known/timezone", the server would issue an HTTP 301 redirect 764 response with a Location response header field using the path 765 "/servlet/timezone". The client would then "follow" this redirect to 766 the new resource and continue making HTTP requests there. The client 767 would also cache the redirect information, subject to any Cache- 768 Control directive, for use in subsequent requests. 770 4.2.2. Synchronization of Time Zones 772 This section discusses possible client synchronization strategies 773 using the various protocol elements provided by the server for that 774 purpose. 776 4.2.2.1. Initial Synchronization of All Time Zones 778 When a secondary service or a client wishing to cache all time zone 779 data first starts, or wishes to do a full refresh, it synchronizes 780 with another server by first issuing a "list" action to retrieve all 781 the time zone meta-data. The client would preserve the returned 782 opaque token for subsequent use (see "synctoken" in Section 5.2.1). 783 The client will store the meta-data for each time zone returned in 784 the response. Time zone data for each corresponding time zone can 785 then be fetched and stored locally. In addition a mapping of aliases 786 to time zones can be built from the meta-data. A typical "list" 787 action response size is about 50-100 KB of "pretty printed" JSON 788 data, for a service using the IANA time zone database [RFC6557], as 789 of the time of publication of this specification. 791 4.2.2.2. Subsequent Synchronization of All Time Zones 793 A secondary service or a client caching all time zones needs to 794 periodically synchronize with a server. To do so it would issue a 795 "list" action with the "changedsince" URI query parameter set to the 796 value of the opaque token returned by the last synchronization. The 797 client would again preserve the returned opaque token for subsequent 798 use. The client will update its stored time zone meta-data using the 799 new values returned in the response, which contains just the time 800 zone meta-data for those time zones changed since the last 801 synchronization. In addition, it will compare the "etag" value in 802 each time zone meta-data to the ETag header field value for the 803 corresponding time zone data resource it has previously cached, and 804 if different, it will fetch the new time zone data. Note that if the 805 client presents the server with a "changedsince" value that the 806 server does not support, all time zone data will be returned, as it 807 would for the case where the request did not include a "changedsince" 808 value. 810 Publishers should take into account the fact that the "outright" 811 deletion of time zone names will cause problems to simple clients and 812 so aliasing a deleted time zone identifier to a suitable alternate 813 one is preferable. 815 4.2.2.3. Synchronization with Pre-Existing Time Zone Data 817 A client might be pre-provisioned with time zone data from a source 818 other than the time zone data distribution service it is configured 819 to use. In such cases, the client might want to minimize the amount 820 of time zone data it synchronizes by doing an initial "list" action 821 to retrieve all the time zone meta-data, but then only fetch time 822 zone data for those time zones that do not match the publisher and 823 version details for the pre-provisioned data. 825 5. Actions 827 Servers MUST support the following actions. The information below 828 shows details about each action: the request-URI the client targets 829 (in the form of a URI template [RFC6570]) a description, the set of 830 allowed query parameters, the nature of the response, and a set of 831 possible error codes for the response (see Section 4.1.7). 833 For any error not covered by the specific error codes defined below, 834 the "urn:ietf:params:tzdist:error:invalid-action" error code is 835 returned to the client in the JSON "problem details" object. 837 The examples in the following subsections presume that the timezone 838 context path has been discovered to be "/servlet/timezone" (as in the 839 example in Section 4.2.1.3.1). 841 5.1. "capabilities" Action 843 Name: capabilities 845 Request-URI Template: 846 {/service-prefix}/capabilities 848 Description: This action returns the capabilities of the server, 849 allowing clients to determine if a specific feature has been 850 deployed and/or enabled. 852 Parameters: None 854 Response A JSON object containing a "version" member, an "info" 855 member, and an "actions" member, see Section 6.1. 857 Possible Error Codes No specific code. 859 5.1.1. Example: get capabilities 861 >> Request << 863 GET /servlet/timezone/capabilities HTTP/1.1 864 Host: tz.example.com 866 >> Response << 868 HTTP/1.1 200 OK 869 Date: Wed, 4 Jun 2008 09:32:12 GMT 870 Content-Type: application/json; charset="utf-8" 871 Content-Length: xxxx 873 { 874 "version": 1, 876 "info": { 877 "primary-source": "Olson:2011m", 878 "formats": [ 879 "text/calendar", 880 "application/calendar+xml", 881 "application/calendar+json" 882 ], 883 "truncated" : { 884 "any": false, 885 "ranges": [ 886 { 887 "start": "1970-01-01T00:00:00Z", 888 "end": "*" 889 }, 890 { 891 "start":"2010-01-01T00:00:00Z", 892 "end":"2020-01-01T00:00:00Z" 893 } 894 ], 895 "untruncated": true 896 }, 897 "provider-details": "http://tz.example.com/about.html", 898 "contacts": ["mailto:tzs@example.org"] 899 }, 900 "actions": [ 901 { 902 "name": "capabilities", 903 "uri-template": "/servlet/timezone/capabilities", 904 "parameters": [] 905 }, 907 { 908 "name": "list", 909 "uri-template": "/servlet/timezone/zones{?changedsince}", 910 "parameters": [ 911 { 912 "name": "changedsince", 913 "required": false, 914 "multi": false 915 } 916 ] 917 }, 919 { 920 "name": "get", 921 "uri-template": "/servlet/timezone/zones{/tzid}{?start,end}", 922 "parameters": [ 923 { 924 "name": "start", 925 "required": false, 926 "multi": false 927 }, 928 { 929 "name": "end", 930 "required": false, 931 "multi": false 932 } 933 ] 934 }, 936 { 937 "name": "expand", 938 "uri-template": 939 "/servlet/timezone/zones{/tzid}/observances{?start,end}", 940 "parameters": [ 941 { 942 "name": "start", 943 "required": true, 944 "multi": false 945 }, 946 { 947 "name": "end", 948 "required": true, 949 "multi": false 950 } 951 ] 952 }, 954 { 955 "name": "find", 956 "uri-template": "/servlet/timezone/zones{?pattern}", 957 "parameters": [ 958 { 959 "name": "pattern", 960 "required": true, 961 "multi": false 962 } 963 ] 964 }, 966 { 967 "name": "leapseconds", 968 "uri-template": "/servlet/timezone/leapseconds", 969 "parameters": [] 970 } 971 ] 972 } 974 5.2. "list" Action 976 Name: list 978 Request-URI Template: 979 {/service-prefix,data-prefix}/zones{?changedsince} 981 Description: This action lists all time zone identifiers in summary 982 format, with publisher, version, aliases and optional localized 983 data. In addition, it returns an opaque synchronization token for 984 the entire response. If the "changedsince" URI query parameter is 985 present, its value MUST correspond to a previously returned 986 synchronization token value. When "changedsince" is used, the 987 server MUST return only those time zones that have changed since 988 the specified synchronization token. If the "changedsince" value 989 is not supported by the server, the server MUST return all time 990 zones, treating the request as if it had no "changedsince". 992 Parameters: 994 changedsince OPTIONAL, and MUST NOT occur more than once. 996 Response: A JSON object containing a "synctoken" member and a 997 "timezones" member, see Section 6.2. 999 Possible Error Codes 1001 urn:ietf:params:tzdist:error:invalid-changedsince The 1002 "changedsince" URI query parameter appears more than once. 1004 5.2.1. Example: list time zone identifiers 1006 In this example the client requests the full set of time zone 1007 identifiers. 1009 >> Request << 1011 GET /servlet/timezone/zones HTTP/1.1 1012 Host: tz.example.com 1014 >> Response << 1016 HTTP/1.1 200 OK 1017 Date: Wed, 4 Jun 2008 09:32:12 GMT 1018 Content-Type: application/json; charset="utf-8" 1019 Content-Length: xxxx 1021 { 1022 "synctoken": "2009-10-11T09:32:11Z", 1023 "timezones": [ 1024 { 1025 "tzid": "America/New_York", 1026 "etag": "123456789-000-111", 1027 "last-modified": "2009-09-17T01:39:34Z", 1028 "publisher": "Example.com", 1029 "version": "2015a", 1030 "aliases":["US/Eastern"], 1031 "local-names": [ 1032 { 1033 "name": "America/New_York", 1034 "lang": "en_US" 1035 } 1036 ] 1037 }, 1038 ...other time zones... 1039 ] 1040 } 1042 5.3. "get" Action 1044 Name: get 1046 Request-URI Template: 1047 {/service-prefix,data-prefix}/zones{/tzid}{?start,end} 1049 The "tzid" variable value is REQUIRED in order to distinguish this 1050 action from the "list" action. 1052 Description: This action returns a time zone. The response MUST 1053 contain an ETag response header field indicating the current value 1054 of the strong entity tag of the time zone resource. 1056 In the absence of any Accept HTTP request header field, the server 1057 MUST return time zone data with the "text/calendar" media type. 1059 If the "tzid" variable value is actually a time zone alias, the 1060 server will return the matching time zone data with the alias as 1061 the identifier in the time zone data. The server MAY include one 1062 or more "TZID-ALIAS-OF" properties (see Section 7.2) in the time 1063 zone data to indicate additional identifiers that have the 1064 matching time zone identifier as an alias. 1066 Parameters: 1068 start= OPTIONAL, and MUST NOT occur more than once. 1069 Specifies the inclusive UTC date-time value at which the 1070 returned time zone data is truncated at its start. 1072 end= OPTIONAL, and MUST NOT occur more than once. 1073 Specifies the exclusive UTC date-time value at which the 1074 returned time zone data is truncated at its end. 1076 Response: A document containing all the requested time zone data in 1077 the format specified. 1079 Possible Error Codes 1081 urn:ietf:params:tzdist:error:tzid-not-found No time zone 1082 associated with the specified "tzid" path segment value was 1083 found. 1085 urn:ietf:params:tzdist:error:invalid-format The Accept request 1086 header field supplied by the client did not contain a media 1087 type for time zone data supported by the server. 1089 urn:ietf:params:tzdist:error:invalid-start The "start" URI query 1090 parameter has an incorrect value, or appears more than once, or 1091 does not match one of the fixed truncation range start values 1092 advertised in the "capabilities" action response. 1094 urn:ietf:params:tzdist:error:invalid-end The "end" URI query 1095 parameter has an incorrect value, or appears more than once, or 1096 has a value less than or equal to the "start" URI query 1097 parameter, or does not match one of the fixed truncation range 1098 end values advertised in the "capabilities" action response. 1100 5.3.1. Example: get time zone data 1102 In this example the client requests the time zone with a specific 1103 time zone identifier to be returned. 1105 >> Request << 1107 GET /servlet/timezone/zones/America%2FNew_York HTTP/1.1 1108 Host: tz.example.com 1109 Accept:text/calendar 1111 >> Response << 1113 HTTP/1.1 200 OK 1114 Date: Wed, 4 Jun 2008 09:32:12 GMT 1115 Content-Type: text/calendar; charset="utf-8" 1116 Content-Length: xxxx 1117 ETag: "123456789-000-111" 1119 BEGIN:VCALENDAR 1120 ... 1121 BEGIN:VTIMEZONE 1122 TZID:America/New_York 1123 ... 1124 END:VTIMEZONE 1125 END:VCALENDAR 1127 5.3.2. Example: conditional get time zone data 1128 In this example the client requests the time zone with a specific 1129 time zone identifier to be returned, but uses an If-None-Match header 1130 field in the request, set to the value of a previously returned ETag 1131 header field, or the value of the "etag" member in a JSON "timezone" 1132 object returned from a "list" action response. In this example, the 1133 data on the server has not changed, so a 304 response is returned. 1135 >> Request << 1137 GET /servlet/timezone/zones/America%2FNew_York HTTP/1.1 1138 Host: tz.example.com 1139 Accept:text/calendar 1140 If-None-Match: "123456789-000-111" 1142 >> Response << 1144 HTTP/1.1 304 Not Modified 1145 Date: Wed, 4 Jun 2008 09:32:12 GMT 1147 5.3.3. Example: get time zone data using a time zone alias 1148 In this example the client requests the time zone with an aliased 1149 time zone identifier to be returned, and the server returns the time 1150 zone data with that identifier, and two aliases. 1152 >> Request << 1154 GET /servlet/timezone/zones/US%2FEastern HTTP/1.1 1155 Host: tz.example.com 1156 Accept:text/calendar 1158 >> Response << 1160 HTTP/1.1 200 OK 1161 Date: Wed, 4 Jun 2008 09:32:12 GMT 1162 Content-Type: text/calendar; charset="utf-8" 1163 Content-Length: xxxx 1164 ETag: "123456789-000-111" 1166 BEGIN:VCALENDAR 1167 ... 1168 BEGIN:VTIMEZONE 1169 TZID:US/Eastern 1170 TZID-ALIAS-OF:America/New_York 1171 TZID-ALIAS-OF:America/Montreal 1172 ... 1173 END:VTIMEZONE 1174 END:VCALENDAR 1176 5.3.4. Example: get truncated time zone data 1178 Assume the server advertises a "truncated" object in its 1179 "capabilities" response that appears as: 1181 "truncated": { 1182 "any": false, 1183 "ranges": [ 1184 {"start": "1970-01-01T00:00:00Z", "end": "*"}, 1185 {"start":"2010-01-01T00:00:00Z", "end":"2020-01-01T00:00:00Z"} 1186 ], 1187 "untruncated": false 1188 } 1189 In this example the client requests the time zone with a specific 1190 time zone identifier truncated at one of the ranges specified by the 1191 server, to be returned. Note the presence of a "STANDARD" component 1192 that matches the start point of the truncation range (converted to 1193 the local time for the UTC offset in effect at the matching UTC 1194 time). Also, note the presence of the "TZUNTIL" (Section 7.1) 1195 iCalendar property in the "VTIMEZONE" component, indicating the upper 1196 bound on the validity of the time zone data. 1198 >> Request << 1200 GET /servlet/timezone/zones/America%2FNew_York 1201 ?start=2010-01-01T00:00:00Z&end=2020-01-01T00:00:00Z HTTP/1.1 1202 Host: tz.example.com 1203 Accept:text/calendar 1205 >> Response << 1207 HTTP/1.1 200 OK 1208 Date: Wed, 4 Jun 2008 09:32:12 GMT 1209 Content-Type: text/calendar; charset="utf-8" 1210 Content-Length: xxxx 1211 ETag: "123456789-000-111" 1213 BEGIN:VCALENDAR 1214 ... 1215 BEGIN:VTIMEZONE 1216 TZID:America/New_York 1217 TZUNTIL:20200101T000000Z 1218 BEGIN:STANDARD 1219 DTSTART:20101231T190000 1220 TZNAME:EST 1221 TZOFFSETFROM:-0500 1222 TZOFFSETTO:-0500 1223 END:STANDARD 1224 ... 1225 END:VTIMEZONE 1226 END:VCALENDAR 1228 5.3.5. Example: request for a non-existent time zone 1229 In this example the client requests the time zone with a specific 1230 time zone identifier to be returned. As it turns out, no time zone 1231 exists with that identifier. 1233 >> Request << 1235 GET /servlet/timezone/zones/America%2FPittsburgh HTTP/1.1 1236 Host: tz.example.com 1237 Accept:application/calendar+json 1239 >> Response << 1241 HTTP/1.1 404 Not Found 1242 Date: Wed, 4 Jun 2008 09:32:12 GMT 1243 Content-Type: application/problem+json; charset="utf-8" 1244 Content-Language: en 1245 Content-Length: xxxx 1247 { 1248 "type": "urn:ietf:params:tzdist:error:tzid-not-found", 1249 "title": "Time zone identifier was not found on this server", 1250 "status": 404 1251 } 1253 5.4. "expand" Action 1255 Name: expand 1257 Request-URI Template: 1258 {/service-prefix,data-prefix}/zones{/tzid}/observances{?start,end} 1260 The "tzid" variable value is REQUIRED. 1262 Description: This action expands the specified time zone into a list 1263 of onset start date/time (in UTC) and UTC offsets. The response 1264 MUST contain an ETag response header field indicating the current 1265 value of the strong entity tag of the time zone being expanded. 1267 Parameters: 1269 start=: REQUIRED, and MUST occur only once. Specifies 1270 the inclusive UTC date-time value for the start of the period 1271 of interest. 1273 end=: REQUIRED, and MUST occur only once. Specifies 1274 the exclusive UTC date-time value for the end of the period of 1275 interest. Note that this is the exclusive end value - i.e., it 1276 represents the date just after the range of interest. e.g., if 1277 a client wants the expanded date just for the year 2014, it 1278 would use a start value of "2014-01-01T00:00:00Z" and an end 1279 value of "2015-01-01T00:00:00Z". An error occurs if the end 1280 value is less than or equal to the start value. 1282 Response: A JSON object containing a "tzid" member, and an 1283 "observances" member, see Section 6.3. If the time zone being 1284 expanded is not fully defined over the requested time range (e.g., 1285 because of truncation), then the server MUST include "start" and/ 1286 or "end" members in the JSON response to indicate the actual start 1287 and end point for the observances being returned. The server MUST 1288 include an expanded observance representing the time zone 1289 information in effect at the start of the returned observance 1290 period. 1292 Possible Error Codes 1294 urn:ietf:params:tzdist:error:tzid-not-found No time zone 1295 associated with the specified "tzid" path segment value was 1296 found. 1298 urn:ietf:params:tzdist:error:invalid-start The "start" URI query 1299 parameter has an incorrect value, or appears more than once, or 1300 is missing, or has a value outside any fixed truncation ranges 1301 advertised in the "capabilities" action response. 1303 urn:ietf:params:tzdist:error:invalid-end The "end" URI query 1304 parameter has an incorrect value, or appears more than once, or 1305 has a value less than or equal to the "start" URI query 1306 parameter, or has a value outside any fixed truncation ranges 1307 advertised in the "capabilities" action response.. 1309 5.4.1. Example: expanded JSON data format 1310 In this example the client requests a time zone in the expanded form. 1312 >> Request << 1314 GET /servlet/timezone/zones/America%2FNew_York/observances 1315 ?start=2008-01-01T00:00:00Z&end=2009-01-01T00:00:00Z HTTP/1.1 1316 Host: tz.example.com 1318 >> Response << 1320 HTTP/1.1 200 OK 1321 Date: Mon, 11 Oct 2009 09:32:12 GMT 1322 Content-Type: application/json; charset="utf-8" 1323 Content-Length: xxxx 1324 ETag: "123456789-000-111" 1326 { 1327 "tzid": "America/New_York", 1328 "observances": [ 1329 { 1330 "name": "Standard", 1331 "onset": "2008-01-01T00:00:00Z", 1332 "utc-offset-from": -18000, 1333 "utc-offset-to": -18000 1334 }, 1335 { 1336 "name": "Daylight", 1337 "onset": "2008-03-09T07:00:00Z", 1338 "utc-offset-from": -18000, 1339 "utc-offset-to": -14400 1340 }, 1341 { 1342 "name": "Standard", 1343 "onset": "2008-11-02T06:00:00Z", 1344 "utc-offset-from": -14400, 1345 "utc-offset-to": -18000 1346 }, 1347 ] 1348 } 1350 5.5. "find" Action 1352 Name: find 1354 Request-URI Template: 1355 {/service-prefix,data-prefix}/zones{?pattern} 1357 Description: This action allows a client to query the time zone data 1358 distribution service for a matching identifier, alias or localized 1359 name, using a simple "glob" style pattern match against the names 1360 known to the server (with an asterisk * as the wildcard 1361 character). Pattern match strings (which have to be %-encoded and 1362 then decoded when used in the URI query parameter) have the 1363 following options: 1365 * not present: An exact text match is done, e.g., "xyz" 1367 * first character only: An ends-with text match is done, e.g., 1368 "*xyz" 1370 * last character only: A starts-with text match is done, e.g., 1371 "xyz*" 1373 * first and last characters only: A sub-string text match is 1374 done, e.g., "*xyz*" 1376 Escaping \ and *: To match 0x2A ("*") and 0x5C ("\") characters 1377 in a time zone identifier, those characters have to be 1378 "escaped" in the pattern by prepending a single 0x5C 1379 ("\")character. e.g., a pattern "\*Test\\Time\*Zone\*" is used 1380 for an exact match against the time zone identifier 1381 "*Test\Time*Zone*". An unescaped "*" character MUST NOT appear 1382 in the middle of the string and MUST result in an error. An 1383 unescaped "\" character MUST NOT appear anywhere in the string 1384 and MUST result in an error. 1386 In addition, when matching: 1388 Underscores: Underscore characters (0x5F) in time zone 1389 identifiers MUST be mapped to a single space character (0x20) 1390 prior to string comparison in both the pattern and time zone 1391 identifiers being matched. This allows time zone identifiers 1392 such as "America/New_York" to match a query for "*New York*". 1394 Case mapping: ASCII characters in the range 0x41 ("A") through 1395 0x5A ("Z") MUST be mapped to their lowercase equivalents in 1396 both the pattern and time zone identifiers being matched. 1398 Parameters: 1400 pattern= REQUIRED, and MUST occur only once. 1402 Response: The response has the same format as the "list" action, 1403 with one result object per successful match, see Section 6.2. 1405 Possible Error Codes 1407 urn:ietf:params:tzdist:error:invalid-pattern The "pattern" URI 1408 query parameter has an incorrect value, or appears more than 1409 once. 1411 5.5.1. Example: find action 1413 In this example the client asks for data about the time zone "US/ 1414 Eastern". 1416 >> Request << 1418 GET /servlet/timezone/zones?pattern=US/Eastern HTTP/1.1 1419 Host: tz.example.com 1421 >> Response << 1423 HTTP/1.1 200 OK 1424 Date: Wed, 4 Jun 2008 09:32:12 GMT 1425 Content-Type: application/json; charset="utf-8" 1426 Content-Length: xxxx 1428 { 1429 "synctoken": "2009-10-11T09:32:11Z", 1430 "timezones": [ 1431 { 1432 "tzid": "America/New_York", 1433 "etag": "123456789-000-111", 1434 "last-modified": "2009-09-17T01:39:34Z", 1435 "publisher": "Example.com", 1436 "version": "2015a", 1437 "aliases":["US/Eastern"], 1438 "local-names": [ 1439 { 1440 "name": "America/New_York", 1441 "lang": "en_US" 1442 } 1443 ] 1444 }, 1445 { 1446 "tzid": "America/Detroit", 1447 "etag": "123456789-999-222", 1448 "last-modified": "2009-09-17T01:39:34Z", 1449 "publisher": "Example.com", 1450 "version": "2015a", 1451 "aliases":["US/Eastern"], 1452 "local-names": [ 1453 { 1454 "name": "America/Detroit", 1455 "lang": "en_US" 1456 } 1457 ] 1458 }, 1459 ... 1460 ] 1461 } 1463 5.6. "leapseconds" Action 1465 Name: leapseconds 1467 Request-URI Template: 1468 {/service-prefix,data-prefix}/leapseconds 1470 Description: This action allows a client to query the time zone data 1471 distribution service to retrieve the current leap second 1472 information available on the server. 1474 Parameters: None 1476 Response: A JSON object containing an "expires" member, a 1477 "publisher" member, a "version" member, and a "leapseconds" 1478 member, see Section 6.4. The "expires" member in the JSON 1479 response indicates the latest date covered by leap second 1480 information. e.g., (from the example below) if the "expires" value 1481 is set to "2014-06-28" and the latest leap second change indicated 1482 was at "2012-07-01", then the data indicates that there are no 1483 leap seconds added (or removed) between those two dates, and 1484 information for leap seconds beyond the "expires" date is not yet 1485 available. 1487 The "leapseconds" member contains a list of JSON objects each of 1488 which contains a "utc-offset" and "onset" member. The "onset" 1489 member specifies the date (with the implied time of 00:00:00 UTC) 1490 at which the corresponding UTC offset from TAI takes effect. In 1491 other words, a leap second is added or removed just prior to time 1492 00:00:00 UTC of the specified onset date. When a leap second is 1493 added, the "utc-offset" value will be incremented by one, when a 1494 leap second is removed, the "utc-offset" value will be decremented 1495 by one. 1497 Possible Error Codes No specific code. 1499 5.6.1. Example: get leapsecond information 1500 In this example the client requests the current leap second 1501 information from the server. 1503 >> Request << 1505 GET /servlet/timezone/leapseconds HTTP/1.1 1506 Host: tz.example.com 1508 >> Response << 1510 HTTP/1.1 200 OK 1511 Date: Wed, 4 Jun 2008 09:32:12 GMT 1512 Content-Type: application/json; charset="utf-8" 1513 Content-Length: xxxx 1515 { 1516 "expires": "2015-12-28", 1517 "publisher": "Example.com", 1518 "version": "2015d", 1519 "leapseconds": [ 1520 { 1521 "utc-offset": 10, 1522 "onset": "1972-01-01", 1523 }, 1524 { 1525 "utc-offset": 11, 1526 "onset": "1972-07-01", 1527 }, 1528 ... 1529 { 1530 "utc-offset": 35, 1531 "onset": "2012-07-01", 1532 }, 1533 { 1534 "utc-offset": 36, 1535 "onset": "2015-07-01", 1536 } 1537 ] 1538 } 1540 6. JSON Definitions 1542 [RFC7159] defines the structure of JSON objects using a set of 1543 primitive elements. Those elements will be used to describe the 1544 structure of JSON objects used by this specification using a set of 1545 "rules". The rules used are: 1547 OBJECT represents a JSON object, defined in Section 4 of [RFC7159]. 1548 "OBJECT" is followed by a parenthesized list of "MEMBER" rule 1549 names. If a member rule name is preceded by a "?" (0x3F) 1550 character, that member is optional, otherwise all members are 1551 required. If two or more member rule names are present, each 1552 separated from the other by a "|" (0x7C) character, then only one 1553 of those members MUST be present in JSON object. JSON object 1554 members are unordered, and thus the order used in the rules is not 1555 significant. 1557 MEMBER represents a member of a JSON object, defined in Section 4 of 1558 [RFC7159]. "MEMBER" is followed by a rule name, then the name of 1559 the member, followed by a ":", and then the value. A value can be 1560 one of "OBJECT", "ARRAY", "NUMBER", "STRING", or "BOOLEAN" rules. 1562 ARRAY represents a JSON array, defined in Section 5 of [RFC7159]. 1563 "ARRAY" is followed by a value (one of "OBJECT", "ARRAY", 1564 "NUMBER", "STRING", or "BOOLEAN"), indicating the type of items 1565 used in the array. 1567 NUMBER represents a JSON number, defined in Section 6 of [RFC7159]. 1569 STRING represents a JSON string, defined in Section 7 of [RFC7159]. 1571 BOOLEAN represents either of the JSON values "true" or "false", 1572 defined in Section 3 of [RFC7159]. 1574 ; a line starting with a ";" (0x3B) character is a comment. 1576 Note, clients MUST ignore any unexpected JSON members in responses 1577 from the server. 1579 6.1. capabilities Action Response 1581 Rules for the JSON document returned for a "capabilities" action 1582 request. 1584 ; root object 1585 OBJECT (version, info, actions) 1587 ; The version number of the protocol supported - MUST be 1 1588 MEMBER version "version" : NUMBER 1590 ; object containing service information 1591 ; Only one of primary_source or secondary_source MUST be present 1592 MEMBER info "info" : OBJECT ( 1593 primary_source | secondary_source, 1594 formats, 1595 ?truncated, 1596 ?provider_details, 1597 ?contacts 1598 ) 1600 ; The source of the time zone data provided by a "primary" server 1601 MEMBER primary_source "primary-source" : STRING 1603 ; The time zone data server from which data is provided by a 1604 ; "secondary" server 1605 MEMBER secondary_source "secondary-source" : STRING 1607 ; Array of one or more media types for the time zone data formats 1608 ; that the server can return 1609 MEMBER formats "formats" : ARRAY STRING 1611 ; Present if the server is providing truncated time zone data. The 1612 ; value is an object providing details of the supported truncation 1613 ; modes. 1614 MEMBER truncated "truncated" : OBJECT: ( 1615 any, 1616 ?ranges, 1617 ?untruncated 1618 ) 1620 ; Indicates whether the server can truncate time zone data at any 1621 ; start or end point. When set to "true" any start or end point is 1622 ; a valid value for use with the "start" and "end" URI query 1623 ; parameters in a "get" action request 1624 MEMBER any "any" : BOOLEAN 1626 ; Indicates which ranges of time the server has truncated data for. 1627 ; A value from this list may be used with the "start" and "end" URI 1628 ; query parameters in a "get" action request. Not present if "any" 1629 ; is set to "true" 1630 MEMBER ranges "ranges" : ARRAY OBJECT (range-start, range-end) 1632 ; [RFC3339] UTC date-time value for inclusive start of the range, 1633 ; or the single character "*" to indicate a value corresponding to 1634 ; the lower bound supplied by the publisher of the time zone data 1635 MEMBER range-start "start" : STRING 1637 ; [RFC3339] UTC date-time value for exclusive end of the range, 1638 ; or the single character "*" to indicate a value corresponding to 1639 ; the upper bound supplied by the publisher of the time zone data 1640 MEMBER range-end "end" : STRING 1642 ; Indicates whether the server can can supply untruncated data. When 1643 ; set to "true" indicates that, in addition to truncated data being 1644 ; available, the server can return untruncated data if a "get" 1645 ; action request is executed without a "start" or "end" URI query 1646 ; parameter 1647 MEMBER untruncated "untruncated" : BOOLEAN 1649 ; A URI where human readable details about the time zone service 1650 ; is available 1651 MEMBER provider_details "provider-details" : STRING 1653 ; Array of URIs providing contact details for the server 1654 ; administrator 1655 MEMBER contacts "contacts" : ARRAY STRING 1657 ; Array of actions supported by the server 1658 MEMBER actions "actions" : ARRAY OBJECT ( 1659 action_name, 1660 action_params 1661 ) 1663 ; Name of the action 1664 MEMBER action_name: "name" : STRING 1666 ; Array of request-URI query parameters supported by the action 1667 MEMBER action_params: "parameters" ARRAY OBJECT ( 1668 param_name, 1669 ?param_required, 1670 ?param_multi, 1671 ?param_values 1672 ) 1674 ; Name of the parameter 1675 MEMBER param_name "name" : STRING 1677 ; If true the parameter has to be present in the request-URI 1678 ; default is false 1679 MEMBER param_required "required" : BOOLEAN 1681 ; If true the parameter can occur more than once in the request-URI 1682 ; default is false 1683 MEMBER param_multi "multi" : BOOLEAN, 1685 ; An array that defines the allowed set of values for the parameter 1686 ; In the absence of this member, any string value is acceptable 1687 MEMBER param_values "values" ARRAY STRING 1689 6.2. list/find Action Response 1691 Rules for the JSON document returned for a "list" or "find" action 1692 request. 1694 ; root object 1695 OBJECT (synctoken, timezones) 1697 ; Server generated opaque token used for synchronizing changes, 1698 MEMBER synctoken "synctoken" : STRING 1700 ; Array of time zone objects 1701 MEMBER timezones "timezones" : ARRAY OBJECT ( 1702 tzid, 1703 etag, 1704 last_modified, 1705 publisher, 1706 version, 1707 ?aliases, 1708 ?local_names, 1709 ) 1711 ; Time zone identifier 1712 MEMBER tzid "tzid" : STRING 1714 ; Current ETag for the corresponding time zone data resource 1715 MEMBER etag "etag" : STRING 1717 ; Date/time when the time zone data was last modified 1718 ; [RFC3339] UTC date-time value 1719 MEMBER last_modified "last-modified" : STRING 1721 ; Time zone data publisher 1722 MEMBER publisher "publisher" : STRING 1724 ; Current version of the time zone data as defined by the 1725 ; publisher 1726 MEMBER version "version" : STRING 1728 ; An array that lists the set of time zone aliases available 1729 ; for the corresponding time zone 1730 MEMBER aliases "aliases" : ARRAY STRING 1732 ; An array that lists the set of localized names available 1733 ; for the corresponding time zone 1734 MEMBER local_names "local-names" : ARRAY OBJECT ( 1735 lname, lang, ?pref 1736 ) 1737 ; Language tag for the language of the associated name 1738 MEMBER: lang "lang" : STRING 1740 ; Localized name 1741 MEMBER lname "name" : STRING 1743 ; Indicates whether this is the preferred name for the associated 1744 ; language default: false 1745 MEMBER pref "pref" : BOOLEAN 1747 6.3. expand Action Response 1748 Rules for the JSON document returned for a "expand" action request. 1750 ; root object 1751 OBJECT ( 1752 tzid, 1753 ?start, 1754 ?end, 1755 observances 1756 ) 1758 ; Time zone identifier 1759 MEMBER tzid "tzid" : STRING 1761 ; The actual inclusive start point for the returned observances 1762 ; if different from the value of the "start" URI query parameter 1763 MEMBER start "start" : STRING 1765 ; The actual exclusive end point for the returned observances 1766 ; if different from the value of the "end" URI query parameter 1767 MEMBER end "end" : STRING 1769 ; Array of time zone objects 1770 MEMBER observances "observances" : ARRAY OBJECT ( 1771 oname, 1772 ?olocal_names, 1773 onset, 1774 utc_offset_from, 1775 utc_offset_to 1776 ) 1778 ; Observance name 1779 MEMBER oname "name" : STRING 1781 ; Array of localized observance names 1782 MEMBER olocal_names "local-names" : ARRAY STRING 1784 ; [RFC3339] UTC date-time value at which the observance takes effect 1785 MEMBER onset "onset" : STRING 1787 ; The UTC offset in seconds before the start of this observance 1788 MEMBER utc_offset_from "utc-offset-from" : NUMBER 1790 ; The UTC offset in seconds at and after the start of this observance 1791 MEMBER utc_offset_to "utc-offset-to" : NUMBER 1793 6.4. leapseconds Action Response 1795 Rules for the JSON document returned for a "leapseconds" action 1796 request. 1798 ; root object 1799 OBJECT ( 1800 expires, 1801 publisher, 1802 version, 1803 leapseconds 1804 ) 1806 ; Last valid date covered by the data in this response 1807 ; [RFC3339] full-date value 1808 MEMBER expires "expires" : STRING 1810 ; Leap second information publisher 1811 MEMBER publisher "publisher" : STRING 1813 ; Current version of the leap second information as defined by the 1814 ; publisher 1815 MEMBER version "version" : STRING 1817 ; Array of leap second objects 1818 MEMBER leapseconds "leapseconds" : ARRAY OBJECT ( 1819 utc_offset, 1820 onset 1821 ) 1823 ; The UTC offset from TAI in seconds in effect at and after the 1824 ; specified date 1825 MEMBER utc_offset "utc-offset" : NUMBER 1827 ; [RFC3339] full-date value at which the new UTC offset takes effect, 1828 ; at T00:00:00Z 1829 MEMBER onset "onset" : STRING 1831 7. New iCalendar Properties 1833 7.1. Time Zone Upper Bound 1835 Property Name: TZUNTIL 1837 Purpose: This property specifies an upper bound for the validity of 1838 data within a "VTIMEZONE" component. 1840 Value Type: DATE-TIME 1841 Property Parameters: IANA and non-standard property parameters can 1842 be specified on this property. 1844 Conformance: This property can be specified zero or one time within 1845 "VTIMEZONE" calendar components. 1847 Description: The value MUST be specified in the UTC time format. 1849 Time zone data in a "VTIMEZONE" component might cover only a fixed 1850 period of time. The start of such a period is clearly indicated 1851 by the earliest observance defined by the "STANDARD" and 1852 "DAYLIGHT" sub-components. However, [RFC5545] does not define a 1853 way to indicate an upper bound on the validity of the time zone 1854 data, which cannot be simply derived from the observance with the 1855 latest onset time. This specification introduces the "TZUNTIL" 1856 property for that purpose. It specifies an "exclusive" UTC date- 1857 time value that indicates the last time at which the time zone 1858 data is to be considered valid. 1860 This property is also used by time zone data distribution servers 1861 to indicate the truncation range end point of time zone data (as 1862 described in Section 3.9). 1864 Format Definition: This property is defined by the following 1865 notation: 1867 tzuntil = "TZUNTIL" tzuntilparam ":" date-time CRLF 1869 tzuntilparam = *(";" other-param) 1871 Example: Suppose a time zone based on astronomical observations has 1872 well-defined onset times through the year 2025, but the first 1873 onset in 2026 is currently known only approximately. In that 1874 case, the "TZUNTIL" property could be specified as follows: 1876 TZUNTIL:20260101T000000Z 1878 7.2. Time Zone Identifier Alias Property 1880 Property Name: TZID-ALIAS-OF 1882 Purpose: This property specifies a time zone identifier that the 1883 main time zone identifier is an alias of. 1885 Value Type: TEXT 1887 Property Parameters: IANA and non-standard property parameters can 1888 be specified on this property. 1890 Conformance: This property can be specified zero or more times 1891 within "VTIMEZONE" calendar components. 1893 Description: When the "VTIMEZONE" component uses a time zone 1894 identifier alias for the "TZID" property value, the "TZID-ALIAS- 1895 OF" property is used to indicate the time zone identifier of the 1896 other time zone (see Section 3.7). 1898 Format Definition: This property is defined by the following 1899 notation: 1901 tzid-alias-of = "TZID-ALIAS-OF" tzidaliasofparam ":" 1902 [tzidprefix] text CRLF 1904 tzidaliasofparam = *(";" other-param) 1906 ;tzidprefix defined in [RFC5545]. 1908 Example: The following is an example of this property: 1910 TZID-ALIAS-OF:America/New_York 1912 8. Security Considerations 1914 Time zone data is critical in determining local or UTC time for 1915 devices and in calendaring and scheduling operations. As such, it is 1916 vital that a reliable source of time zone data is used. Servers 1917 providing a time zone data distribution service MUST support HTTP 1918 over Transport Layer Security (TLS) (as defined by [RFC2818] and 1919 [RFC5246], with best practices described in [RFC7525]). Servers MAY 1920 support a time zone data distribution service over HTTP without TLS. 1921 However, secondary servers MUST use TLS to fetch data from a primary 1922 server. 1924 Clients SHOULD use transport layer security as defined by [RFC2818], 1925 unless they are specifically configured otherwise. Clients that have 1926 been configured to use the TLS-based service, MUST NOT fall back to 1927 using the non-TLS service if the TLS-based service is not available. 1928 In additional, clients MUST NOT follow HTTP redirect requests from a 1929 TLS service to a non-TLS service. When using TLS, clients MUST 1930 verify the identity of the server, using a standard, secure mechanism 1931 such as the certificate verification process specified in [RFC6125] 1932 or DANE [RFC6698]. 1934 A malicious attacker with access to the DNS server data, or able to 1935 get spoofed answers cached in a recursive resolver, can potentially 1936 cause clients to connect to any server chosen by the attacker. In 1937 the absence of a secure DNS option, clients SHOULD check that the 1938 target FQDN returned in the SRV record is the same as the original 1939 service domain that was queried, or is a sub-domain of the original 1940 service domain. In many cases the client configuration is likely to 1941 be handled automatically without any user input and as such, any 1942 mismatch between the original service domain and the target FQDN is 1943 treated as a failure and the client MUST NOT attempt to connect to 1944 the target server. In addition, when transport layer security is 1945 being used, the transport layer security certificate SHOULD include 1946 an SRV-ID field as per [RFC4985] matching the expected DNS SRV 1947 queries clients will use for service discovery. If an SRV-ID field 1948 is present in a certificate, clients MUST match the SRV-ID value with 1949 the service type and domain that matches the DNS SRV request made by 1950 the client to discover the service. 1952 Time zone data servers SHOULD protect themselves against poorly 1953 implemented or malicious clients by throttling high request rates or 1954 frequent requests for large amounts of data. Clients can avoid being 1955 throttled by using the polling capabilities outlined in 1956 Section 4.1.4. Servers MAY require some form of authentication or 1957 authorization of clients (including secondary servers), as per 1958 [RFC7235], to restrict which clients are allowed to access their 1959 service, or provide better identification of problematic clients. 1961 9. Privacy Considerations 1963 The type and pattern of requests that a client makes can be used to 1964 "fingerprint" specific clients or devices and thus potentially used 1965 to track information about what the users of the clients might be 1966 doing. In particular, a client that only downloads time zone data on 1967 an as needed basis, will leak the fact that a user's device has moved 1968 from one time zone to another or that the user is receiving 1969 scheduling messages from another user in a different time zone. 1971 Clients need to be aware of the potential ways in which an untrusted 1972 server or a network observer might be able to track them and take 1973 precautions such as the following: 1975 1. Always use TLS to connect to the server. 1977 2. Avoid use of TLS session resumption. 1979 3. Always fetch and synchronize the entire set of time zone data to 1980 avoid leaking information about which time zones are actually in 1981 use by the client. 1983 4. Randomize the order in which individual time zones are fetched 1984 using the "get" action, when retrieving a set of time zones based 1985 on a "list" action response. 1987 5. Avoid use of conditional HTTP requests [RFC7232] with the "get" 1988 action to prevent tracking of clients by servers generating 1989 client-specific ETag header field values. 1991 6. Avoid use of cookies in HTTP requests [RFC6265]. 1993 7. Avoid use of authenticated HTTP requests. 1995 8. When doing periodic polling to check for updates, apply a random 1996 (positive or negative) offset to the next poll time to avoid 1997 servers being able to identify the client by the specific 1998 periodicity of its polling behavior. 2000 9. A server trying to "fingerprint" clients might insert a "fake" 2001 time zone into the time zone data, using a unique identifier for 2002 each client making a request. The server can then watch for 2003 client requests that refer to that "fake" time zone and thus 2004 track the activity of each client. It is hard for clients to 2005 identify a "fake" time zone given that new time zones are added 2006 from time to time. One option to mitigate this would be for the 2007 client to make use of two time zone data distribution servers 2008 from two independent providers, that provide time zone data from 2009 the same publisher. The client can then compare the list of time 2010 zones from each server (assuming they both have the same version 2011 of time zone data from the common publisher) and detect ones that 2012 appear to be added on one server and not the other. 2013 Alternatively, the client can check the publisher data directly 2014 to verify that time zones match the set the publisher has. 2016 Note that some of the above recommendations will result in less 2017 efficient use of the protocol due to fetching data that might not be 2018 relevant to the client. 2020 An organization can setup a secondary server within their own domain, 2021 and configure their clients to use that server, to protect the 2022 organization's users from the possibility of being tracked by an 2023 untrusted time zone data distribution server. Clients can then use 2024 more efficient protocol interactions, free from the concerns above, 2025 on the basis that their organization's server is trusted. When doing 2026 this, the secondary server would follow the recommendations for 2027 clients (listed in the previous paragraph) so that the untrusted 2028 server is not able to gain information about the organization as a 2029 whole. Note, however, that if client requests to the secondary 2030 server are subject to tracking by a network observer so clients ought 2031 to apply some of the randomization techniques from the list above. 2033 Servers that want to avoid accidentally storing information that 2034 could be used to identify clients can take the following precautions: 2036 1. Avoid logging client request activity, or anonymize information 2037 in any logs (e.g., client IP address, client user-agent details, 2038 authentication credentials, etc). 2040 2. Add an unused HTTP response header to each response with a random 2041 amount of data in it (e.g., to pad the overall request size to 2042 the nearest power-of-2 or 128-byte boundary) to avoid exposing 2043 which time zones are being fetched when TLS is being used, via 2044 network traffic analysis. 2046 10. IANA Considerations 2048 This specification defines a new registry of "actions" for the time 2049 zone data distribution service protocol, defines a "well-known" URI 2050 using the registration procedure and template from Section 5.1 of 2051 [RFC5785], creates two new SRV service label aliases, and defines one 2052 new iCalendar property parameter as per the registration procedure in 2053 [RFC5545]. It also adds a new "tzdist Identifiers Registry" to the 2054 IETF parameters URN sub-namespace as per [RFC3553] for use with 2055 protocol related error codes. 2057 10.1. Service Actions Registration 2059 IANA is asked to create a new top-level category called "Time Zone 2060 Data Distribution Service (TZDIST) Parameters", and to put all the 2061 registries created herein into that category. 2063 IANA is asked to create a new registry called "TZDIST Service 2064 Actions", as defined below. 2066 10.1.1. Service Actions Registration Procedure 2068 This registry uses the "Specification Required" policy defined in 2069 [RFC5226], which makes use of a designated expert to review potential 2070 registrations. 2072 The IETF will create a mailing list, tzdist-service@ietf.org, which 2073 can be used for public discussion of time zone data distribution 2074 service actions proposals prior to registration. The IESG will 2075 appoint a designated expert who will monitor the tzdist- 2076 service@ietf.org mailing list and review registrations. 2078 A Standards Track RFC is REQUIRED for changes to actions previously 2079 documented in a Standards Track RFC, otherwise any public 2080 specification that satisfies the requirements of [RFC5226] is 2081 acceptable. 2083 The registration procedure begins when a completed registration 2084 template, as defined below, is sent to tzdist-service@ietf.org and 2085 iana@iana.org. The designated expert is expected to tell IANA and 2086 the submitter of the registration whether the registration is 2087 approved, approved with minor changes, or rejected with cause, within 2088 two weeks. When a registration is rejected with cause, it can be re- 2089 submitted if the concerns listed in the cause are addressed. 2090 Decisions made by the designated expert can be appealed as per 2091 Section 7 of [RFC5226]. 2093 The designated expert MUST take the following requirements into 2094 account when reviewing the registration: 2096 1. A valid registration template MUST be provided by the submitter, 2097 with a clear description of what the action does. 2099 2. A proposed new action name MUST NOT conflict with any existing 2100 registered action name. A conflict includes a name that 2101 duplicates an existing one, or that appears to be very similar to 2102 an existing one and could be a potential source of confusion. 2104 3. A proposed new action MUST NOT exactly duplicate the 2105 functionality of any existing actions. In cases where the new 2106 action functionality is very close to an existing action, the 2107 designated expert SHOULD clarify whether the submitter is aware 2108 of the existing action, and has an adequate reason for creating a 2109 new action with slight differences from an existing one. 2111 4. If a proposed action is an extension to an existing action, the 2112 changes MUST NOT conflict with the intent of the existing action, 2113 or in a way that could cause interoperability problems for 2114 existing deployments of the protocol. 2116 The IANA registry will contain the name of the action ("Action Name") 2117 and a reference to the section of the specification where the action 2118 registration template is defined ("Reference"). 2120 10.1.2. Registration Template for Actions 2122 An action is defined by completing the following template. 2124 Name: The name of the action. 2126 Request-URI Template: The URI template used in HTTP requests for the 2127 action. 2129 Description: A general description of the action, its purpose, etc. 2131 Parameters: A list of allowed request URI query parameters, 2132 indicating whether they are "REQUIRED" or "OPTIONAL" and whether 2133 they can occur only once or multiple times, together with the 2134 expected format of the parameter values. 2136 Response The nature of the response to the HTTP request, e.g., what 2137 format the response data is in. 2139 Possible Error Codes Possible error codes reported in a JSON 2140 "problem details" object if an HTTP request fails. 2142 10.1.3. Actions Registry 2144 The following table is to be used to initialize the actions registry. 2146 +---------------+-----------------------+ 2147 | Action Name | Reference | 2148 +---------------+-----------------------+ 2149 | capabilities | RFCXXXX, Section 5.1 | 2150 | list | RFCXXXX, Section 5.2 | 2151 | get | RFCXXXX, Section 5.3 | 2152 | expand | RFCXXXX, Section 5.4 | 2153 | find | RFCXXXX, Section 5.5 | 2154 | leapseconds | RFCXXXX, Section 5.6 | 2155 +---------------+-----------------------+ 2157 10.2. timezone Well-Known URI Registration 2159 IANA is asked to make the following registration in the "Well-Known 2160 URIs" [RFC5785] registry: 2162 URI suffix: timezone 2164 Change controller: IESG. 2166 Specification document(s): RFCXXXX 2168 Related information: None. 2170 10.3. Service Name Registrations 2172 IANA is asked to add two new service names to the "Service Name and 2173 Transport Protocol Port Number Registry" [RFC6335], as defined below. 2175 10.3.1. timezone Service Name Registration 2177 Service Name: timezone 2179 Transport Protocol(s): TCP 2181 Assignee: IESG 2183 Contact: IETF Chair 2185 Description: Time Zone Data Distribution Service - non-TLS 2187 Reference: RFCXXXX 2189 Assignment Note: This is an extension of the http service. Defined 2190 TXT keys: path= (as per Section 6 of [RFC6763]). 2192 10.3.2. timezones Service Name Registration 2194 Service Name: timezones 2196 Transport Protocol(s): TCP 2198 Assignee: IESG 2200 Contact: IETF Chair 2202 Description: Time Zone Data Distribution Service - over TLS 2204 Reference: RFCXXXX 2206 Assignment Note: This is an extension of the https service. Defined 2207 TXT keys: path= (as per Section 6 of [RFC6763]). 2209 10.4. tzdist Identifiers Registry 2211 IANA is requested to register a new URN sub-namespace within the IETF 2212 URN Sub-namespace for Registered Protocol Parameter Identifiers 2213 defined in [RFC3553]. 2215 Registrations in this registry follow the "IETF Review" [RFC5226] 2216 policy. 2218 Registry name: tzdist Identifiers 2220 URN prefix: urn:ietf:params:tzdist 2222 Specification: RFCXXXX 2223 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2225 Index value:: Values in this registry are URNs or URN prefixes that 2226 start with the prefix "urn:ietf:params:tzdist:". Each is 2227 registered independently. The prefix 2228 "urn:ietf:params:tzdist:error:" is used to represent specific 2229 error codes within the protocol as defined in the list of actions 2230 in Section 5 and used in problem reports (Section 4.1.7). 2232 Each registration in the "tzdist Identifiers" registry requires the 2233 following information: 2235 URN: The complete URN that is used or the prefix for that URN. 2237 Description: A summary description for the URN or URN prefix. 2239 Specification: A reference to a specification describing the URN or 2240 URN prefix. 2242 Contact: Email for the person or groups making the registration. 2244 Index Value: As described in [RFC3553], URN prefixes that are 2245 registered include a description of how the URN is constructed. 2246 This is not applicable for specific URNs. 2248 The "tzdist Identifiers" registry has the initial registrations 2249 included in the following sections. 2251 10.4.1. Registration of invalid-action Error URN 2253 This section registers the "urn:ietf:params:tzdist:error:invalid- 2254 action" URN in the "tzdist Identifiers" registry. 2256 URN: urn:ietf:params:tzdist:error:invalid-action 2258 Specification: RFCXXXX, Section 5 2260 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2262 Contact: IESG 2264 Index value:: N/A. 2266 10.4.2. Registration of invalid-changedsince Error URN 2268 This section registers the "urn:ietf:params:tzdist:error:invalid- 2269 changedsince" URN in the "tzdist Identifiers" registry. 2271 URN: urn:ietf:params:tzdist:error:invalid-changedsince 2273 Specification: RFCXXXX, Section 5.2 2275 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2277 Contact: IESG 2279 Index value:: N/A. 2281 10.4.3. Registration of tzid-not-found Error URN 2283 This section registers the "urn:ietf:params:tzdist:error:tzid-not- 2284 found" URN in the "tzdist Identifiers" registry. 2286 URN: urn:ietf:params:tzdist:error:tzid-not-found 2288 Specification: RFCXXXX, Section 5.3 & Section 5.4 2290 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2292 Contact: IESG 2294 Index value:: N/A. 2296 10.4.4. Registration of invalid-format Error URN 2298 This section registers the "urn:ietf:params:tzdist:error:invalid- 2299 format" URN in the "tzdist Identifiers" registry. 2301 URN: urn:ietf:params:tzdist:error:invalid-format 2303 Specification: RFCXXXX, Section 5.3 2305 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2307 Contact: IESG 2309 Index value:: N/A. 2311 10.4.5. Registration of invalid-start Error URN 2313 This section registers the "urn:ietf:params:tzdist:error:invalid- 2314 start" URN in the "tzdist Identifiers" registry. 2316 URN: urn:ietf:params:tzdist:error:invalid-start 2318 Specification: RFCXXXX, Section 5.3 & Section 5.4 2319 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2321 Contact: IESG 2323 Index value:: N/A. 2325 10.4.6. Registration of invalid-end Error URN 2327 This section registers the "urn:ietf:params:tzdist:error:invalid-end" 2328 URN in the "tzdist Identifiers" registry. 2330 URN: urn:ietf:params:tzdist:error:invalid-end 2332 Specification: RFCXXXX, Section 5.3 & Section 5.4 2334 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2336 Contact: IESG 2338 Index value:: N/A. 2340 10.4.7. Registration of invalid-pattern Error URN 2342 This section registers the "urn:ietf:params:tzdist:error:invalid- 2343 pattern" URN in the "tzdist Identifiers" registry. 2345 URN: urn:ietf:params:tzdist:error:invalid-pattern 2347 Specification: RFCXXXX, Section 5.5 2349 Repository: http://www.iana.org/assignments/tzdist-identifiers. 2351 Contact: IESG 2353 Index value:: N/A. 2355 10.5. iCalendar Property Registrations 2357 This document defines the following new iCalendar properties to be 2358 added to the "Properties" registry under "iCalendar Element 2359 Registries" [RFC5545]: 2361 +----------------+----------+-----------------------+ 2362 | Property | Status | Reference | 2363 +----------------+----------+-----------------------+ 2364 | TZUNTIL | Current | RFCXXXX, Section 7.1 | 2365 | TZID-ALIAS-OF | Current | RFCXXXX, Section 7.2 | 2366 +----------------+----------+-----------------------+ 2368 11. Acknowledgements 2370 The authors would like to thank the members of the Calendaring and 2371 Scheduling Consortium's Time Zone Technical Committee, and the 2372 participants and chairs of the IETF tzdist working group. In 2373 particular, the following individuals have made important 2374 contributions to this work: Steve Allen, Lester Caine, Stephen 2375 Colebourne, Tobias Conradi, Steve Crocker, Daniel Kahn Gillmor, Paul 2376 Eggert, John Haug, Ciny Joy, Bryan Keller, Barry Leiba, Andrew 2377 McMillan, Ken Murchison, Tim Parenti, Arnaud Quillaud, Jose Edvaldo 2378 Saraiva, and Dave Thewlis. 2380 This specification originated from work at the Calendaring and 2381 Scheduling Consortium, which has supported the development and 2382 testing of implementations of the specification. 2384 12. References 2386 12.1. Normative References 2388 [I-D.ietf-appsawg-http-problem] 2389 Nottingham, M. and E. Wilde, "Problem Details for HTTP 2390 APIs", draft-ietf-appsawg-http-problem-00 (work in 2391 progress), September 2014. 2393 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2394 Extensions (MIME) Part Two: Media Types", RFC 2046, 2395 November 1996. 2397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2398 Requirement Levels", BCP 14, RFC 2119, March 1997. 2400 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 2401 specifying the location of services (DNS SRV)", RFC 2782, 2402 February 2000. 2404 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2406 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 2407 Internet: Timestamps", RFC 3339, July 2002. 2409 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 2410 IETF URN Sub-namespace for Registered Protocol 2411 Parameters", BCP 73, RFC 3553, June 2003. 2413 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2414 10646", STD 63, RFC 3629, November 2003. 2416 [RFC4985] Santesson, S., "Internet X.509 Public Key Infrastructure 2417 Subject Alternative Name for Expression of Service Name", 2418 RFC 4985, August 2007. 2420 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2421 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2422 DOI 10.17487/RFC5226, May 2008, 2423 . 2425 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2426 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2428 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 2429 Core Object Specification (iCalendar)", RFC 5545, 2430 September 2009. 2432 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 2433 Uniform Resource Identifiers (URIs)", RFC 5785, April 2434 2010. 2436 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2437 Verification of Domain-Based Application Service Identity 2438 within Internet Public Key Infrastructure Using X.509 2439 (PKIX) Certificates in the Context of Transport Layer 2440 Security (TLS)", RFC 6125, March 2011. 2442 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2443 April 2011. 2445 [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML 2446 Format for iCalendar", RFC 6321, August 2011. 2448 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2449 Cheshire, "Internet Assigned Numbers Authority (IANA) 2450 Procedures for the Management of the Service Name and 2451 Transport Protocol Port Number Registry", BCP 165, RFC 2452 6335, August 2011. 2454 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 2455 Time Zone Database", BCP 175, RFC 6557, February 2012. 2457 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2458 and D. Orchard, "URI Template", RFC 6570, March 2012. 2460 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2461 of Named Entities (DANE) Transport Layer Security (TLS) 2462 Protocol: TLSA", RFC 6698, August 2012. 2464 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2465 Discovery", RFC 6763, February 2013. 2467 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2468 Interchange Format", RFC 7159, March 2014. 2470 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2471 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2472 2014. 2474 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2475 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2477 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2478 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 2480 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 2481 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 2482 2014. 2484 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2485 (HTTP/1.1): Authentication", RFC 7235, June 2014. 2487 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 2488 Format for iCalendar", RFC 7265, May 2014. 2490 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2491 "Recommendations for Secure Use of Transport Layer 2492 Security (TLS) and Datagram Transport Layer Security 2493 (DTLS)", BCP 195, RFC 7525, May 2015. 2495 12.2. Informative References 2497 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2498 2131, March 1997. 2500 Appendix A. Change History (to be removed prior to publication as an 2501 RFC) 2503 Changes for -10 2505 1. AD: switch 5226bis back to 5226. 2507 Changes for -10 2509 1. OPSDIR: minor editorial tweaks. 2511 2. OPSDIR: Add RFC6763 reference into IANA registration templates. 2513 3. IESG: add reference to security section for well-known redirects. 2515 4. IESG: Add sentence describing current size of an initial JSON 2516 response for IANA data. 2518 5. IESG: don't mention per-user context paths - just refer to 2519 generic HTTP auth. 2521 6. IANA: tzdist registry policy added. 2523 7. Make sure "data" appears between "time zone" and "distribution" 2525 Changes for -09 2527 1. Added June 30th 2015 leap second data into example. 2529 2. GENART: clarify how "utc-offset" changes as leap seconds are 2530 added or removed. 2532 3. GENART: ".well-known" MUST be present. 2534 4. GENART: switch RFC5226 reference to 5226bis. 2536 5. GENART: reference section 10 of 5226bis for appeals process. 2538 6. GENART: change controller: IETF -> IESG. 2540 7. GENART: Section 10.2 add "None" for related information. 2542 8. GENART: Section 4.1.4 editorial. 2544 9. GENART: Section 4.2.1.2 editorial. 2546 10. GENART: Use RFCXXXX in all parts of IANA section. 2548 11. Removed list of HTTP response codes from error section. 2550 12. Removed Status column from actions registry. 2552 13. Reworked URN prefix registry. 2554 Changes for -08 2556 1. AD review: various nits: Sections 3.3, 3.5, 3.9, 4.2.1.3.1, 2557 4.2.2.1, 5.x. 2559 2. AD review: Section 4.1 now refers to security/privacy sections. 2561 3. AD review: Section 4.1.4 re-written for clarity. 2563 4. AD review: Section 4.2.1.3 now uses "max-age" not "no-cache". 2565 5. AD review: Section 4.2.1.2 now includes text about per-user 2566 redirect. 2568 6. AD review: Section 4.2.1.3 clarifies well-know is present even 2569 when TXT RR exists. 2571 7. AD review: added /servlet/timezone as URI prefix in examples 2573 8. AD review: Section 5.5 make use of "*" in the middle of a 2574 pattern an error. 2576 9. AD review: Section 5.5 underscore and case mapping now a MUST. 2578 10. AD review: Section 5.5 additional text about %-encoding the 2579 pattern. 2581 11. AD review: Section 8 re-worded client TLS requirements and added 2582 reference to DANE. 2584 12. AD review: Section 10 various clarifications for IANA 2585 instructions. 2587 13. AD review: Changed to "Specification Required" policy for new 2588 registry and added guidelines for designated expert. 2590 Changes for -07 2592 1. Added comment to check publisher data to see if fake time zone 2593 has been used. 2595 2. Tweaked non-DNSSEC SRV text to indicate a service->target match 2596 is based on sub-domain and that any mismatch is always a failure. 2598 3. SECDIR: Now recommend that TLS certs include an SRV-ID field. 2600 4. SECDIR: Additional privacy text tweaks. 2602 Changes for -06 2604 1. WGLC: Added addition text about problems with operating system 2605 only updates. 2607 2. WGLC: Use "Root" and "Secondary" as prefix for "Providers" in 2608 Figure 1. 2610 3. WGLC: various editorial tweaks and example fixes. 2612 4. WGLC: "invalid-changedsince" error description fixed. 2614 5. WGLC: use "full-date" to describe RFC3339 date only values. 2616 6. WGLC: changed security considerations to prevent clients from 2617 falling back to non-TLS. 2619 7. SECDIR: added Privacy Considerations with a bunch of 2620 recommendations for clients. 2622 8. SECDIR: require TLS for server-to-server requests. 2624 9. SECDIR: require clients to stick with TLS once they start using 2625 it (don't downgrade, redirect etc). 2627 10. SECDIR: added reference to TLS BCP document. 2629 Changes for -05 2631 1. Now uses its own rules for defining JSON objects. 2633 2. Added new section on time zone versions. 2635 3. Added publisher/version to the list action response meta-data. 2637 4. Changed conditional request and synchronization sections to 2638 better describe how meta-data and data are updated. 2640 5. Added the ability to retrieve leap second information from the 2641 server. 2643 6. Added text to require servers to return all data if a 2644 "changedsince" value is not supported. 2646 7. Switched TZUNTIL to be exclusive rather than inclusive, so that 2647 it now matches the definition of the truncation end point (also 2648 exclusive). 2650 Changes for -04 2652 1. Tweaked invalid-start/end for action expand to indicate outside 2653 truncation range. 2655 2. Added text on use of Accept-Language. 2657 3. Added text on requirement to percent-encode {/tzid}. 2659 4. Moved /observances under /zones{/tzid}. 2661 5. Observances response now includes start/end of actual range 2662 returned if different from what was requested. 2664 6. Truncation end and &end= for get action are now exclusive. 2666 7. Added capabilities action in capabilities example response. 2668 8. Added uri-template items to capabilities action definitions. 2670 9. Added start/end items to the observances response. 2672 10. Error codes are now URNs (with an IANA registration for a tzdist 2673 sub-namespace) and the URNs are used as the type value in JSON 2674 problem reports. 2676 11. Removed "changedsince" from expand action - ETag can be used 2677 instead. 2679 Changes for -03 2681 1. Reworked conditional list section 2682 (https://tools.ietf.org/wg/tzdist/trac/ticket/22 & 2683 https://tools.ietf.org/wg/tzdist/trac/ticket/33). 2685 2. Moved definitions into General Considerations section. 2687 3. Now makes use of ietf-appsawg-http-problem for error responses. 2689 4. Switched to using a more RESTful design with resources used to 2690 identify endpoints for actions 2691 (https://tools.ietf.org/wg/tzdist/trac/ticket/29). 2693 5. Tweaked TZUNTIL text to further address 2694 (https://tools.ietf.org/wg/tzdist/trac/ticket/15). 2696 6. Tweaked "outright" deletion text to match latest on mailing list 2697 (https://tools.ietf.org/wg/tzdist/trac/ticket/18). 2699 7. Added additional text suggesting other discovery mechanisms could 2700 be used (https://tools.ietf.org/wg/tzdist/trac/ticket/30). 2702 8. Now require "end" parameter on expand to avoid issues with 2703 truncated data upper bounds 2704 (https://tools.ietf.org/wg/tzdist/trac/ticket/10). 2706 Changes for -02 2707 1. "time zone server" -> "time zone data server". 2709 2. Re-worded some text containing reference to "historical" time 2710 zone data, and truncation behavior. 2712 3. Removed "REST". 2714 4. Use "TZID-ALIAS-OF" in place of "EQUIVALENT-TZID". 2716 5. Added \-escape mechanism for find action. 2718 6. Revised Section 4.2.3 to address 2719 (https://tools.ietf.org/wg/tzdist/trac/ticket/18). 2721 Changes for -01 2723 1. Query attribute: "name" -> "pattern" 2724 (https://tools.ietf.org/wg/tzdist/trac/ticket/4). 2726 2. UTF-8 used for time zone ids and in all responses. 2728 3. Added glossary term and note for "time zone" 2729 (https://tools.ietf.org/wg/tzdist/trac/ticket/12). 2731 4. Glossary term change and alias text from 2732 (https://tools.ietf.org/wg/tzdist/trac/ticket/13). 2734 5. "Local Provider" -> "Secondary Provider". 2736 6. Additional security text for 2737 (https://tools.ietf.org/wg/tzdist/trac/ticket/25). 2739 7. Added additional text to better describe localized names. 2741 8. Added "tzid" member to expand response. 2743 9. Added optional "provider-details" member to capabilities 2744 response, and also made "contacts" optional. 2746 10. Definition of "invalid-action" moved to Section 6, and clarified 2747 text related to error responses in Sections 4.1.6 and 6 2748 (https://tools.ietf.org/wg/tzdist/trac/ticket/17). 2750 11. Added "Observance" to glossary. 2752 12. Added "TZUNTIL" iCalendar property (part of 2753 https://tools.ietf.org/wg/tzdist/trac/ticket/15). 2755 13. Revamped truncation to always use UTC date-time values and 2756 support end points (https://tools.ietf.org/wg/tzdist/trac/ 2757 ticket/21, and https://tools.ietf.org/wg/tzdist/trac/ticket/10). 2759 14. Expand always uses UTC date-time values for query parameters, 2760 and always returns UTC date-time onset values 2761 (https://tools.ietf.org/wg/tzdist/trac/ticket/21). 2763 Changes for -00 2765 1. Initial WG draft derived from draft-douglass-timezone-service-11, 2766 with some terminology changes to match WG name. 2768 2. Updated references. 2770 3. "timezone" -> "time zone" (https://tools.ietf.org/wg/tzdist/trac/ 2771 ticket/6). 2773 4. Glossary tweak (first part of 2774 https://tools.ietf.org/wg/tzdist/trac/ticket/13). 2776 5. Fix iCalendar property names: UTC-OFFSET-* -> TZOFFSET*. 2778 6. Fix invalid-truncate error code description. 2780 Authors' Addresses 2782 Michael Douglass 2783 Spherical Cow Group 2784 226 3rd Street 2785 Troy , NY 12180 2786 USA 2788 Email: mdouglass@sphericalcowgroup.com 2789 URI: http://sphericalcowgroup.com 2791 Cyrus Daboo 2792 Apple Inc. 2793 1 Infinite Loop 2794 Cupertino , CA 95014 2795 USA 2797 Email: cyrus@daboo.name 2798 URI: http://www.apple.com/