idnits 2.17.1 draft-douglass-timezone-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 15, 2014) is 3694 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) -- Looks like a reference, but probably isn't: '1970' on line 1046 -- Looks like a reference, but probably isn't: '2000' on line 1046 -- Looks like a reference, but probably isn't: '2010' on line 759 == Outdated reference: A later version (-10) exists of draft-ietf-jcardcal-jcal-09 == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-01 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** 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) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft RPI 4 Intended status: Standards Track C. Daboo 5 Expires: September 16, 2014 Apple 6 March 15, 2014 8 Timezone Service Protocol 9 draft-douglass-timezone-service-11 11 Abstract 13 This document defines a timezone service protocol that allows 14 reliable, secure and fast delivery of timezone data to client systems 15 such as calendaring and scheduling applications or operating systems. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 16, 2014. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.2. Glossary of terms . . . . . . . . . . . . . . . . . . . . 4 54 2. Architectural Overview . . . . . . . . . . . . . . . . . . . . 5 55 3. General Considerations . . . . . . . . . . . . . . . . . . . . 6 56 3.1. Timezone Identifiers . . . . . . . . . . . . . . . . . . . 6 57 3.2. Timezone Aliases . . . . . . . . . . . . . . . . . . . . . 7 58 3.3. Timezone Localized Names . . . . . . . . . . . . . . . . . 7 59 3.4. Truncated Timezones . . . . . . . . . . . . . . . . . . . 7 60 4. Timezones Service Protocol . . . . . . . . . . . . . . . . . . 8 61 4.1. Server Protocol . . . . . . . . . . . . . . . . . . . . . 8 62 4.1.1. Timezone Queries . . . . . . . . . . . . . . . . . . . 8 63 4.1.2. Timezone Formats . . . . . . . . . . . . . . . . . . . 9 64 4.1.3. Conditional Timezone Requests . . . . . . . . . . . . 9 65 4.1.4. Expanded Timezone Data . . . . . . . . . . . . . . . . 9 66 4.1.5. Server Requirements . . . . . . . . . . . . . . . . . 10 67 4.1.6. Error Responses . . . . . . . . . . . . . . . . . . . 10 68 4.1.7. Extensions . . . . . . . . . . . . . . . . . . . . . . 10 69 4.2. Client Guidelines . . . . . . . . . . . . . . . . . . . . 10 70 4.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 10 71 4.2.1.1. Timezone Service SRV Service Labels . . . . . . . 11 72 4.2.1.2. Timezone Service TXT records . . . . . . . . . . . 11 73 4.2.1.3. Timezone Service Well-Known URI . . . . . . . . . 12 74 4.2.1.3.1. Example: well-known URI redirects to 75 actual context path . . . . . . . . . . . . . 12 76 4.2.2. Initial Synchronization of All Timezones . . . . . . . 12 77 4.2.3. Subsequent Synchronization of All Timezones . . . . . 13 78 5. Request Parameters . . . . . . . . . . . . . . . . . . . . . . 13 79 5.1. "action" Parameter . . . . . . . . . . . . . . . . . . . . 13 80 5.2. "format" Parameter . . . . . . . . . . . . . . . . . . . . 13 81 5.3. "changedsince" Parameter . . . . . . . . . . . . . . . . . 14 82 5.4. "start" Parameter . . . . . . . . . . . . . . . . . . . . 14 83 5.5. "end" Parameter . . . . . . . . . . . . . . . . . . . . . 14 84 5.6. "lang" Parameter . . . . . . . . . . . . . . . . . . . . . 14 85 5.7. "tzid" Parameter . . . . . . . . . . . . . . . . . . . . . 15 86 5.8. "name" Parameter . . . . . . . . . . . . . . . . . . . . . 15 87 5.9. "truncate" Parameter . . . . . . . . . . . . . . . . . . . 15 88 6. Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 89 6.1. "capabilities" Action . . . . . . . . . . . . . . . . . . 16 90 6.1.1. Example: Get Capabilities . . . . . . . . . . . . . . 17 91 6.2. "list" Action . . . . . . . . . . . . . . . . . . . . . . 19 92 6.2.1. Example: List timezone identifiers . . . . . . . . . . 21 93 6.3. "get" Action . . . . . . . . . . . . . . . . . . . . . . . 21 94 6.3.1. Example: Get timezone . . . . . . . . . . . . . . . . 23 95 6.3.2. Example: Get timezone alias . . . . . . . . . . . . . 24 96 6.3.3. Example: Get truncated timezone . . . . . . . . . . . 24 98 6.4. "expand" Action . . . . . . . . . . . . . . . . . . . . . 25 99 6.4.1. Example: Expanded JSON Data Format . . . . . . . . . . 27 100 6.5. "find" Action . . . . . . . . . . . . . . . . . . . . . . 27 101 6.5.1. Example: Find action . . . . . . . . . . . . . . . . . 29 102 7. JSON Definitions . . . . . . . . . . . . . . . . . . . . . . . 30 103 7.1. capabilities action response . . . . . . . . . . . . . . . 30 104 7.2. list action response . . . . . . . . . . . . . . . . . . . 32 105 7.3. expand action response . . . . . . . . . . . . . . . . . . 34 106 7.4. error response . . . . . . . . . . . . . . . . . . . . . . 35 107 8. Equivalent Timezone Identifier Property . . . . . . . . . . . 35 108 9. Security Considerations . . . . . . . . . . . . . . . . . . . 36 109 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 110 10.1. Service Actions Registration . . . . . . . . . . . . . . . 37 111 10.1.1. Service Actions Registration Procedure . . . . . . . . 37 112 10.1.2. Registration Template for Actions . . . . . . . . . . 37 113 10.1.3. Registration Template for Action Parameters . . . . . 38 114 10.2. Initial Timezone Service Registries . . . . . . . . . . . 38 115 10.2.1. Actions Registry . . . . . . . . . . . . . . . . . . . 38 116 10.2.2. Action Parameters Registry . . . . . . . . . . . . . . 38 117 10.3. timezone Well-Known URI Registration . . . . . . . . . . . 39 118 10.4. Service Name Registrations . . . . . . . . . . . . . . . . 39 119 10.4.1. timezone Service Name Registration . . . . . . . . . . 39 120 10.4.2. timezones Service Name Registration . . . . . . . . . 40 121 10.5. iCalendar Property Registration . . . . . . . . . . . . . 40 122 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 40 123 12. Normative References . . . . . . . . . . . . . . . . . . . . . 40 124 Appendix A. Change History (to be removed prior to 125 publication as an RFC) . . . . . . . . . . . . . . . 42 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 128 1. Introduction 130 Timezone data typically combines a coordinated universal time (UTC) 131 offset with daylight saving time (DST) rules. Timezones are 132 typically tied to specific geographic and geopolitical regions. 133 Whilst the UTC offset for particular regions changes infrequently, 134 DST rules can change frequently and sometimes with very little notice 135 (sometimes hours before a change comes into effect). 137 Calendaring and scheduling systems, such as those that use iCalendar 138 [RFC5545], as well as operating systems, critically rely on timezone 139 data to determine the correct local time. As such they need to be 140 kept up to date with changes to timezone data. To date there has 141 been no fast and easy way to do that. Timezone data is often 142 supplied in the form of a set of data files that have to be 143 "compiled" into a suitable database format for use by the client 144 application or operating system. In the case of operating systems, 145 often those changes only get propagated to client machines when there 146 is an operating system update, which can be infrequent, resulting in 147 inaccurate timezone data being present for significant amounts of 148 time. 150 This specification defines a timezone service protocol that allows 151 for fast, reliable and accurate delivery of timezone data to client 152 systems. This protocol is based on HTTP [RFC2616] using a REST style 153 API, with JSON [RFC7159] responses. 155 This specification does not define the source of the timezone data. 156 It is assumed that a reliable and accurate source is available. One 157 such source is the IANA hosted timezone database [RFC6557]. 159 Discussion of this document should take place on the calsify mailing 160 list calsify@ietf.org 162 1.1. Conventions 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in [RFC2119]. 168 1.2. Glossary of terms 170 The following terms with the given meanings are used throughout this 171 document. 173 Timezone Data: Data that defines a single timezone, including an 174 identifier, UTC offset values, and DST rules; 176 Timezone Server: A server implementing the Timezone Service Protocol 177 defined by this specification; 179 Timezone Identifier: A globally unique name which identifies 180 timezone data. 182 2. Architectural Overview 184 The overall process for the delivery of timezone data can be 185 visualized via the diagram shown below. 187 ==================== ==================== 188 (a) | Contributors | | Contributors | 189 ==================== ==================== 190 | | 191 ==================== ==================== 192 (b) | Publisher A | | Publisher B | 193 ==================== ==================== 194 | 195 ==================== 196 (c) | Provider | 197 ==================== 198 / | \ 199 / | \ 200 ==================== | ==================== 201 (d) | Provider | | | Provider | 202 ==================== | ==================== 203 | | | | 204 | | | | 205 ========== ========== ========== ========== 206 (e) | Client | | Client | | Client | | Client | 207 ========== ========== ========== ========== 209 Figure 1: Timezone Service Architecture 211 The overall service is made up of several layers: 213 (a) Contributors: Individuals, governments or organizations which 214 provide information about timezones to the publishing process. 215 There can be many contributors. 217 (b) Publishers: Publishers aggregate information from contributors, 218 determine the reliability of the information and, based on that, 219 generate timezone data. There can be many publishers, each 220 getting information from many different contributors. In some 221 cases a publisher may choose to "re-publish" data from another 222 publisher. 224 (c) Root Providers: Servers which obtain and then provide the 225 timezone data from publishers and make that available to other 226 servers or clients. There can be many root providers. Root 227 providers can choose to supply timezone data from one or more 228 publishers. 230 (d) Local Providers: Servers which handle the bulk of the requests 231 and reduce the load on root servers. These will typically be 232 simple caches of the root server, located closer to clients. For 233 example a large Internet Service Provider (ISP) may choose to 234 setup their own local provider to allow clients within their 235 network to make requests of that server rather than making 236 requests of servers outside their network. Local servers will 237 cache and periodically refresh data from the root servers. 239 (e) Clients: Applications, operating systems etc., that make use of 240 timezone data and retrieve that from either root or local 241 providers. 243 Some of those layers may be coalesced by implementors. For example, 244 a vendor may choose to implement the entire service as a single 245 monolithic virtual server with the address embedded in distributed 246 systems. Others may choose to provide a service consisting of 247 multiple layers of providers, many local servers and a small number 248 of root servers. 250 This specification is only concerned with the protocol used to 251 exchange data between providers and from provider to client. This 252 specification does not define how contributors pass their information 253 to publishers, nor how those publishers vet that information to 254 obtain trustworthy data, nor the format of the data produced by the 255 publishers. 257 3. General Considerations 259 3.1. Timezone Identifiers 261 Timezone identifiers are unique names associated with each timezone, 262 as defined by publishers. The iCalendar [RFC5545] specification has 263 a "TZID" property and parameter whose value is set to the 264 corresponding timezone identifier, and used to identify timezone data 265 and relate timezones to start and end dates in events, etc. This 266 specification does not define what format of timezone identifiers 267 should be used. It is possible that timezone identifiers from 268 different publishers overlap, and there might be a need for a 269 provider to distinguish those with some form of "namespace" prefix 270 identifying the publisher. However, development of a standard 271 (global) timezone identifier naming scheme is out of scope for this 272 specification. 274 3.2. Timezone Aliases 276 Timezone aliases map a name onto a timezone identifier. For example 277 "US/Eastern" is usually mapped on to "America/New_York". Timezone 278 aliases are typically used interchangeably with timezone identifiers 279 when presenting information to users. 281 A timezone service needs to maintain timezone alias mapping 282 information, and expose that data to clients as well as allow clients 283 to query for timezone data using aliases. When returning timezone 284 data to a client, the server returns the data with an identifier 285 matching the query, but it can include one or more equivalent 286 identifiers in the data to provide a hint to the client that 287 alternative identifiers are available. For example, a query for "US/ 288 Eastern" could include equivalent identifiers for "America/New_York" 289 or "America/Montreal". 291 3.3. Timezone Localized Names 293 Localized names are names for timezones which can be presented to a 294 user in their own language. Each timezone may have one or more 295 localized names associated with it. Names would typically be unique 296 in their own locale as they might be presented to the user in a list. 298 A timezone service might need to maintain localized name information, 299 for one or more chosen languages, as well as allow clients to query 300 for timezone data using localized names. 302 3.4. Truncated Timezones 304 Timezones and daylight saving times rules have been in use for over a 305 century. Timezone data can thus contain a large amount of 306 "historical" information that may not be relevant for a particular 307 server's intended clients. For example, calendaring and scheduling 308 clients are likely most concerned with timezone data that covers a 309 period for one or two years in the past on into the future, as users 310 typically only create new events for the present and future. To 311 avoid having to send unnecessary data, servers are allowed to 312 truncate timezone data at some appropriate date in the past, and only 313 provide accurate offsets and rules from that point on. The server 314 will need to advertise the cut-off dates it is using so that clients 315 that need timezone data for earlier dates can take appropriate 316 action. To simplify the set of data a server needs to support, 317 truncation always occurs at the start of a year, i.e., midnight on 318 1st January for the timezone's local time. A server will advertise a 319 set of years for truncated data it can supply, or provide an 320 indicator that it can truncate at any past year. In addition, the 321 server will advertise that it can supply untruncated data. In the 322 absence of any indication of truncated data available on the server, 323 the server will only supply untruncated data. 325 When truncating a "VTIMEZONE" component, the server MUST include 326 either a "STANDARD" or "DAYLIGHT" sub-component with a "DTSTART" 327 property value that matches the date-time where the truncation 328 occurred, and appropriate "UTC-OFFSET-FROM" and "UTC-OFFSET-TO" 329 properties to indicate the correct offset in effect right after the 330 point of truncation. This sub-component thus represents the earliest 331 valid date-time covered by the timezone data in the truncated 332 "VTIMEZONE" component. 334 4. Timezones Service Protocol 336 4.1. Server Protocol 338 The timezone service protocol uses HTTP [RFC2616] for query and 339 delivery of data. Queries are made on a single HTTP resource using 340 the GET method, with specific client request attributes passed in 341 request-URI parameters. 343 The "action" request-URI parameter defines the overall function being 344 requested, with other request parameters acting as arguments to that 345 function. 347 Most security considerations are already handled adequately by HTTP. 348 However, given the nature of the data being transferred and the 349 requirement it be correct, all interactions between client and server 350 SHOULD use an HTTP connection protected with TLS [RFC5246] as defined 351 in [RFC2818]. 353 4.1.1. Timezone Queries 355 Timezone identifiers, aliases or localized names can be used to query 356 for timezone data. This will be more explicitly defined below for 357 each action. In general however, if a "tzid" request parameter is 358 used then the value may be an identifier or an alias. When the 359 "name" parameter is used it may be an identifier, an alias or a 360 localized name. 362 4.1.2. Timezone Formats 364 The default format for returning timezone definitions is the 365 iCalendar [RFC5545] data format. In addition, the iCalendar-in-XML 366 [RFC6321], and iCalendar-in-JSON [I-D.ietf-jcardcal-jcal] 367 representations are also available. The "format" request-URI 368 parameter can be used to select which data format is returned. 370 4.1.3. Conditional Timezone Requests 372 Timezone data is generally slow moving, with the set of timezones 373 that change from even year-to-year being relatively small. However, 374 any changes that do occur, need to be distributed in a timely manner. 375 Typically it is more efficient to just provide the set of changes to 376 timezone data, so a client can do updates to any locally cached data. 378 When listing timezones, a timestamp is returned by the server, and 379 that can be used later by clients to determine if any "substantive" 380 change has occurred in the timezone data. Clients can use a 381 conditional "list" action (see Section 6.2), supplying a previous 382 timestamp value, to limit the results to timezones which have changed 383 in a "substantive" manner since that previous timestamp. This allows 384 clients to cache the last timestamp and to periodically poll the 385 server for possible changes. 387 A "substantive" change is one which affects the calculated onsets for 388 a timezone. Changes to properties such as a description are not 389 treated as a "substantive" change. 391 Clients SHOULD poll for such changes at least once a day. A server 392 acting as a local provider, caching timezone data from another 393 server, SHOULD poll for changes once per hour. See Section 9 on 394 expected client and server behavior regarding high request rates. 396 4.1.4. Expanded Timezone Data 398 Determining timezone offsets at a particular point in time is often a 399 complicated process, as the rules for daylight saving time can be 400 complex. To help with this, the timezone service provides an action 401 that allows clients to request the server to expand a timezone 402 definition into a set of "observances" over a fixed period of time 403 (see Section 6.4). Each of these observances describes a local onset 404 time and UTC offsets for the prior time and the observance time. 405 Together, these provide a quick way for "thin" clients to determine 406 an appropriate UTC offset for an arbitrary date without having to do 407 full timezone expansion themselves. 409 4.1.5. Server Requirements 411 To enable a simple client implementation, servers SHOULD ensure that 412 they provide or cache data for all commonly used timezones, from 413 various publishers. That allows client implementations to configure 414 a single server to get all timezone data. In turn, any server can 415 refresh any of the data from any other server - though the root 416 servers may provide the most up-to-date copy of the data. 418 4.1.6. Error Responses 420 The following are examples of response codes one would expect to be 421 used by the server. Note, however, that unless explicitly prohibited 422 any 2/3/4/5xx series response code may be used in a response. 424 200 (OK) - The command succeeded. 426 400 (Bad Request) - The Sender has provided an invalid request 427 parameter. 429 404 (Not Found) - The timezone was not found. 431 When an error status is set the server SHOULD respond with some 432 descriptive text in an error object as per Section 7.4. In the case 433 of an invalid "action" query parameter, the following error code can 434 be used: 436 invalid-action The "action" query parameter has an incorrect value. 438 4.1.7. Extensions 440 This protocol is designed to be extensible through a standards based 441 registration mechanism (see Section 10). It is anticipated that 442 other useful timezone actions will be added in the future (e.g., 443 mapping a geographical location to timezone identifiers, getting 444 change history for timezones), and so, servers MUST return a 445 description of their capabilities. This will allow clients to 446 determine if new features have been installed and, if not, fall back 447 on earlier features or disable some client capabilities. 449 4.2. Client Guidelines 451 4.2.1. Discovery 453 Client implementations need to either know where the timezone service 454 is located or discover it through some mechanism. To use a timezone 455 service, a client needs a fully qualified domain name (FQDN), port 456 and HTTP request-URI path. 458 4.2.1.1. Timezone Service SRV Service Labels 460 [RFC2782] defines a DNS-based service discovery protocol that has 461 been widely adopted as a means of locating particular services within 462 a local area network and beyond, using SRV RR records. This can be 463 used to discover a service's FQDN and port. 465 This specification adds two service types for use with SRV records: 467 timezone: Identifies a Timezone server that uses HTTP without 468 transport layer security ([RFC2818]). 470 timezones: Identifies a Timezone server that uses HTTP with 471 transport layer security ([RFC2818]). 473 Clients MUST honor "TTL", "Priority" and "Weight" values in the SRV 474 records, as described by [RFC2782]. 476 Example: service record for server without transport layer security 478 _timezone._tcp SRV 0 1 80 tz.example.com. 480 Example: service record for server with transport layer security 482 _timezones._tcp SRV 0 1 443 tz.example.com. 484 4.2.1.2. Timezone Service TXT records 486 When SRV RRs are used to advertise a timezone service, it is also 487 convenient to be able to specify a "context path" in the DNS to be 488 retrieved at the same time. To enable that, this specification uses 489 a TXT RR that follows the syntax defined in Section 6 of [RFC6763] 490 and defines a "path" key for use in that record. The value of the 491 key MUST be the actual "context path" to the corresponding service on 492 the server. 494 A site might provide TXT records in addition to SRV records for each 495 service. When present, clients MUST use the "path" value as the 496 "context path" for the service in HTTP requests. When not present, 497 clients use the ".well-known" URI approach described next. 499 Example: text record for service with transport layer security 501 _timezones._tcp TXT path=/timezones 503 4.2.1.3. Timezone Service Well-Known URI 505 A "well-known" URI [RFC5785] is registered by this specification for 506 the Timezone service, "timezone" (see Section 10). This URI points 507 to a resource that the client can use as the initial "context path" 508 for the service they are trying to connect to. The server MUST 509 redirect HTTP requests for that resource to the actual "context path" 510 using one of the available mechanisms provided by HTTP (e.g., using 511 an appropriate 3xx status response). Clients MUST handle HTTP 512 redirects on the ".well-known" URI. Servers MUST NOT locate the 513 actual timezone service endpoint at the ".well-known" URI as per 514 Section 1.1 of [RFC5785]. 516 Servers SHOULD set an appropriate Cache-Control header value (as per 517 Section 14.9 of [RFC2616]) in the redirect response to ensure caching 518 occurs as needed, or as required by the type of response generated. 519 For example, if it is anticipated that the location of the redirect 520 might change over time, then a "no-cache" value would be used. 522 To facilitate "context path's" that might differ from user to user, 523 the server MAY require authentication when a client tries to access 524 the ".well-known" URI (i.e., the server would return a 401 status 525 response to the unauthenticated request from the client, then return 526 the redirect response only after a successful authentication by the 527 client). 529 4.2.1.3.1. Example: well-known URI redirects to actual context path 531 A Timezone server has a "context path" that is "/servlet/timezone". 532 The client will use "/.well-known/timezone" as the path for the 533 service after it has first found the FQDN and port number via an SRV 534 lookup or via manual entry of information by the user. When the 535 client makes its initial HTTP request against "/.well-known/ 536 timezone", the server would issue an HTTP 301 redirect response with 537 a Location response header using the path "/servlet/timezone". The 538 client would then "follow" this redirect to the new resource and 539 continue making HTTP requests there. 541 4.2.2. Initial Synchronization of All Timezones 543 When a secondary service or a client wishing to cache all timezone 544 data first starts, or wishes to do a full refresh, it synchronizes 545 with another server by first issuing a "list" action. The client 546 would preserve the returned datestamp for subsequent use. Each 547 timezone in the returned list can then be fetched and stored locally. 548 In addition a mapping of aliases to timezones can be built. 550 4.2.3. Subsequent Synchronization of All Timezones 552 A secondary service or a client caching all timezone data needs to 553 periodically synchronize with a server. To do so it would issue a 554 "list" action with the "changedsince" parameter set to the value of 555 the datestamp returned by the last synchronization. The client would 556 again preserve the returned datestamp for subsequent use. Each 557 timezone in the returned list can then be fetched and stored locally. 559 Note, this process makes no provision for handling deleted timezones. 560 In general it is bad practice to delete timezones as they might still 561 be in use by consumers of timezone data. 563 5. Request Parameters 565 The "action" request-URI parameter MUST be included in all requests 566 to define what action is required of the server. 568 The following request-URI parameters are used with the various 569 actions. 571 5.1. "action" Parameter 573 Name: action 575 Description: Specify the action to be carried out. 577 Value: Any IANA registered action name (see Section 10.2.1). 579 5.2. "format" Parameter 581 Name: format 583 Description: Specify the format of the timezone data returned by the 584 server as a standard MIME [RFC2046] media-type. If absent, the 585 iCalendar [RFC5545] format will be returned with the timezones 586 contained within a "VCALENDAR" object (i.e., a default media-type 587 of "text/calendar"). 589 Value: A MIME [RFC2046] media-type. The following values MAY be 590 used, with servers advertising the values they do support via the 591 "capabilities" action response (see Section 6.1): 593 text/calendar: Return data as "VTIMEZONE" components embedded in 594 a "VCALENDAR" object as per [RFC5545]. 596 application/calendar+xml: Return data using the XML 597 representation of iCalendar data as per iCalendar-in-XML 598 [RFC6321]. 600 application/calendar+json: Return data using the JSON 601 representation of iCalendar data as per iCalendar-in-JSON. 603 5.3. "changedsince" Parameter 605 Name: changedsince 607 Description: Specify the timestamp for a conditional "list" (see 608 Section 6.2) or "expand" (see Section 6.4) action in order to 609 restrict the results to only changes since the given timestamp. 611 Value: An [RFC3339] UTC date-time value, typically a value returned 612 by a previous request. 614 5.4. "start" Parameter 616 Name: start 618 Description: Specify the inclusive start of a period. 620 Value: An integer representing a year.. 622 5.5. "end" Parameter 624 Name: end 626 Description: Specify the exclusive end of a period. 628 Value: An integer representing a year. 630 5.6. "lang" Parameter 632 Name: lang 634 Description: Specify the language in which locale specific values 635 are to be returned. e.g., if a language is specified, only 636 localized names for that language would be returned. 638 Value: The value follows the specifications in [RFC5646]. 640 5.7. "tzid" Parameter 642 Name: tzid 644 Description: Specify a timezone to be targeted by an action. 646 Value: A timezone identifier or alias. 648 5.8. "name" Parameter 650 Name: name 652 Description: Specify a name for queries. 654 Value: A timezone identifier, alias or localized name. This 655 parameter is used when searching for matching timezones (see 656 Section 6.5). 658 5.9. "truncate" Parameter 660 Name: truncate 662 Description: Specify a year for timezone data truncation. 664 Value: An integer representing a year in the past. The use of this 665 depends on the "truncated" object returned in the server's 666 "capabilities" response: 668 If "truncated" object is not present in the "capabilities" 669 response, then the "truncated" parameter MUST NOT be used - the 670 server will always return untruncated timezone data. 672 If "any" is set to "true" in the "truncated" object, then any 673 past year is valid for truncation (though typically data prior 674 to 1880 is unlikely to be present). 676 If "any" is "false" and "years" is present with at least one 677 value, then any of the values in the "years" array can be used. 679 If "untruncated" is set to "true", then omitting the 680 "truncated" parameter will result in untruncated data being 681 returned. 683 If "untruncated" is set to "false", and "years" contains only 684 one value, and the "truncated" query parameter is omitted, then 685 the server will return timezone data truncated at the one value 686 specified in "years". 688 Example: a server that can only return one set of truncated data - 689 client can omit the "truncate" query parameter: 691 truncated: { 692 "any": false, 693 "years": [1970], 694 "untruncated": false 695 } 697 Example: a server that can return truncated data for any past year 698 as well as untruncated data if client omits the "truncate" query 699 parameter: 701 truncated: { 702 "any": true, 703 "untruncated": true 704 } 706 Example: a server that can return only untruncated data - the 707 "truncate" query parameter would always be omitted: 709 truncated: { 710 "any": false, 711 "untruncated": true 712 } 714 6. Actions 716 Servers MUST support the following actions. 718 6.1. "capabilities" Action 720 Name: capabilities 722 Description: This action returns the capabilities of the server, 723 allowing clients to determine if a specific feature has been 724 deployed and/or enabled. Note that each request always includes 725 an "action" query parameter set to the name of the action, even 726 though that parameter is not listed in the "capabilities" response 727 for each action. 729 Parameters: 731 action REQUIRED with value "capabilities" 733 Response A JSON object containing a "version" member, an "info" 734 member, and an "actions" member, see Section 7.1. 736 Possible Error Codes No specific code. 738 6.1.1. Example: Get Capabilities 740 >> Request << 742 GET /?action=capabilities HTTP/1.1 743 Host: tz.example.com 745 >> Response << 747 HTTP/1.1 200 OK 748 Date: Wed, 4 Jun 2008 09:32:12 GMT 749 Content-Type: application/json; charset="utf-8" 750 Content-Length: xxxx 752 { 753 "version": 1, 755 "info": { 756 "primary-source": "Olson:2011m", 757 "truncate" : { 758 "any": false, 759 "years": [1970, 2000, 2010], 760 "untruncated": true 761 }, 762 "contacts": ["mailto:tzs@example.org"] 763 }, 765 "actions": [ 766 { 767 "name": "list", 768 "parameters": [ 769 { 770 "name": "lang", 771 "required": false, 772 "multi": true 773 }, 774 { 775 "name": "changedsince", 776 "required": false, 777 "multi": false 778 } 779 ] 780 }, 781 { 782 "name": "get", 783 "parameters": [ 784 { 785 "name": "format", 786 "required": false, 787 "multi": false, 788 "values": [ 789 "text/calendar", 790 "application/calendar+xml", 791 "application/calendar+json" 792 ] 793 }, 794 { 795 "name": "lang", 796 "required": false, 797 "multi": true 798 }, 799 { 800 "name": "tzid", 801 "required": true, 802 "multi": false 803 }, 804 { 805 "name": "truncate", 806 "required": false, 807 "multi": false 808 } 809 ] 810 }, 812 { 813 "name": "expand", 814 "parameters": [ 815 { 816 "name": "tzid", 817 "required": true, 818 "multi": false 819 }, 820 { 821 "name": "start", 822 "required": false, 823 "multi": false 824 }, 825 { 826 "name": "end", 827 "required": false, 828 "multi": false 830 } 831 ] 832 }, 834 { 835 "name": "find", 836 "parameters": [ 837 { 838 "name": "name", 839 "required": true, 840 "multi": false 841 }, 842 { 843 "name": "lang", 844 "required": false, 845 "multi": true 846 } 847 ] 848 }, 850 { 851 "name":"capabilities", 852 "parameters": [] 853 } 854 ] 855 } 857 6.2. "list" Action 859 Name: list 861 Description: This action lists all timezone identifiers or the 862 requested timezone identifiers, in summary format, with aliases 863 and optional localized data. In addition, it returns a timestamp 864 which is the current server last modification value. If the 865 "changedsince" query parameter is present its value MUST 866 correspond to a previously returned timestamp value. When 867 "changedsince" timestamp is used, the server MUST return only 868 those timezones that have changed since the specified timestamp. 869 If the "tzid" parameter is present one or more times, then the 870 server MUST only return information for the specified timezone 871 identifiers. 873 Parameters: 875 action REQUIRED with value "list" 877 lang= OPTIONAL, but MAY occur multiple times. 879 changedsince OPTIONAL, but MUST occur only once. MUST NOT be 880 present if the "tzid" parameter is present. 882 tzid= OPTIONAL, and MAY occur multiple times. MUST 883 NOT be present if the "changedsince" parameter is present. The 884 value of the "dtstamp" member in the response applies to the 885 entire set of data, rather than the subset requested with the 886 "tzid" query parameter, and allows the client to determine if 887 it needs to refresh its full set of timezone data. 889 Response: A JSON object containing a "dtstamp" member and a 890 "timezones" member, see Section 7.2. 892 Possible Error Codes 894 invalid-changedsince The "changedsince" query parameter has an 895 incorrect value, or appears more than once. 897 invalid-tzid The "tzid" query parameter is present along with the 898 "changedsince", or has an incorrect value. 900 6.2.1. Example: List timezone identifiers 902 In this example the client requests the timezone identifiers and in 903 addition requests that the US-English local names be returned. 905 >> Request << 907 GET /?action=list&lang=en_US HTTP/1.1 908 Host: tz.example.com 910 >> Response << 912 HTTP/1.1 200 OK 913 Date: Wed, 4 Jun 2008 09:32:12 GMT 914 Content-Type: application/json; charset="utf-8" 915 Content-Length: xxxx 917 { 918 "dtstamp": "2009-10-11T09:32:11Z", 919 "timezones": [ 920 { 921 "tzid": "America/New_York", 922 "last-modified": "2009-09-17T01:39:34Z", 923 "aliases":["US/Eastern"], 924 "local-names": [ 925 { 926 "name": "America/New_York", 927 "lang": "en_US" 928 } 929 ] 930 }, 931 ... 932 ] 933 } 935 6.3. "get" Action 937 Name: get 939 Description: This action returns a timezone. If a single timezone 940 is specified, the response MUST contain an ETag response header 941 field indicating the current value of the strong entity tag of the 942 timezone resource. 944 If the identifier is actually a timezone alias, the server will 945 return the matching timezone data with the alias as the identifier 946 in the timezone data. The server MAY include one or more 947 "EQUIVALENT-TZID" properties (see Section 8) in the timezone data 948 to indicate equivalent identifiers for the alias. 950 Parameters: 952 action REQUIRED with value "get" 954 format= OPTIONAL, but MUST occur only once. 956 lang= OPTIONAL, but MAY occur multiple times. 958 tzid= REQUIRED, and MUST occur only once. 960 truncate= OPTIONAL, and MUST occur only once. See 961 Section 5.9 for details. 963 Response: A document containing all the requested timezone data in 964 the format specified. 966 Possible Error Codes 968 invalid-tzid The "tzid" query parameter is not present, or 969 appears more than once. 971 tzid-not-found No timezone associated with the specified "tzid" 972 query parameter value was found. 974 invalid-format The "format" query parameter appears more than 975 once, or has an invalid value. 977 invalid-truncate The "truncate" query parameter is not present, 978 or appears more than once, or has an invalid year specified as 979 its value. 981 6.3.1. Example: Get timezone 983 In this example the client requests the timezone with a specific 984 timezone identifier to be returned 986 >> Request << 988 GET /?action=get&tzid=America/New_York 989 &format=text/calendar HTTP/1.1 990 Host: tz.example.com 992 >> Response << 994 HTTP/1.1 200 OK 995 Date: Wed, 4 Jun 2008 09:32:12 GMT 996 Content-Type: text/calendar; charset="utf-8" 997 Content-Length: xxxx 998 ETag: "123456789-000-111" 1000 BEGIN:VCALENDAR 1001 ... 1002 BEGIN:VTIMEZONE 1003 TZID:America/New_York 1004 ... 1005 END:VTIMEZONE 1006 END:VCALENDAR 1008 6.3.2. Example: Get timezone alias 1010 In this example the client requests the timezone with an aliased 1011 timezone identifier to be returned, and the server returns the 1012 timezone data with that identifier, and two equivalents 1014 >> Request << 1016 GET /?action=get&tzid=US/Eastern 1017 &format=text/calendar 1018 &truncate=2000 HTTP/1.1 1019 Host: tz.example.com 1021 >> Response << 1023 HTTP/1.1 200 OK 1024 Date: Wed, 4 Jun 2008 09:32:12 GMT 1025 Content-Type: text/calendar; charset="utf-8" 1026 Content-Length: xxxx 1027 ETag: "123456789-000-111" 1029 BEGIN:VCALENDAR 1030 ... 1031 BEGIN:VTIMEZONE 1032 TZID:US/Eastern 1033 EQUIVALENT-TZID:America/New_York 1034 EQUIVALENT-TZID:America/Montreal 1035 ... 1036 END:VTIMEZONE 1037 END:VCALENDAR 1039 6.3.3. Example: Get truncated timezone 1041 Assume the server advertises a "truncated" object in its 1042 "capabilities" response that appears as: 1044 truncated: { 1045 "any": false, 1046 "years": [1970, 2000], 1047 "untruncated": false 1048 } 1049 In this example the client requests the timezone with a specific 1050 timezone identifier truncated at one of the years specified as 1051 available by the server, to be returned 1053 >> Request << 1055 GET /?action=get&tzid=America/New_York 1056 &format=text/calendar 1057 &truncate=2000 HTTP/1.1 1058 Host: tz.example.com 1060 >> Response << 1062 HTTP/1.1 200 OK 1063 Date: Wed, 4 Jun 2008 09:32:12 GMT 1064 Content-Type: text/calendar; charset="utf-8" 1065 Content-Length: xxxx 1066 ETag: "123456789-000-111" 1068 BEGIN:VCALENDAR 1069 ... 1070 BEGIN:VTIMEZONE 1071 TZID:America/New_York 1072 ... 1073 END:VTIMEZONE 1074 END:VCALENDAR 1076 6.4. "expand" Action 1078 Name: expand 1080 Description: This action expands the specified timezone into a list 1081 of local time onset start date/time and UTC offsets. The response 1082 MUST contain an ETag response header field indicating the current 1083 value of the strong entity tag for the expanded data. 1085 Parameters: 1087 action REQUIRED with value "expand" 1089 tzid= REQUIRED, but MUST only occur once. 1091 lang= OPTIONAL, but MAY occur multiple times. 1093 start=year: OPTIONAL, but MUST occur only once. If present, 1094 specifies the start of the period of interest. The value is an 1095 integer representing the starting year, with the start date 1096 assumed to be January 1st of that year. If "start" is omitted, 1097 the value is assumed to be the current year. 1099 end=year: OPTIONAL, but MUST occur only once. If present, 1100 specifies the ending year of the period of interest. The value 1101 is an integer representing the ending year, with the end date 1102 assumed to be January 1st of that year. If "end" is omitted, 1103 the value is the start year + 10. Note that this is the 1104 exclusive end value - i.e., it represents the date just after 1105 the range of interest. e.g., if a client wants the expanded 1106 date just for the year 2014, it would use a start value of 1107 "2014" and an end value of "2015". An error occurs if the end 1108 year is less than or equal to the start year. 1110 changedsince OPTIONAL, but MUST occur only once. If present, its 1111 value MUST be taken from the "dtstamp" result of a previous 1112 expand result. If the targeted timezone has not changed over 1113 the expansion range queried in the request, then the server 1114 MUST return a 304 HTTP status response. 1116 Response: A JSON object containing a "dtstamp" member and an 1117 "observances" member, see Section 7.3. The server MUST include an 1118 expanded observance representing the timezone information in 1119 effect at the start of the period (midnight local time, January 1120 1st of the start year). 1122 Possible Error Codes 1124 invalid-tzid The "tzid" query parameter is not present, or 1125 appears more than once. 1127 tzid-not-found No timezone associated with the specified "tzid" 1128 query parameter value was found. 1130 invalid-start The "start" query parameter has an incorrect value, 1131 or appears more than once. 1133 invalid-end The "end" query parameter has an incorrect value, or 1134 appears more than once, or is missing, or has a value less than 1135 or equal to the "start" query parameter. 1137 invalid-changedsince The "changedsince" query parameter has an 1138 incorrect value, or appears more than once. 1140 6.4.1. Example: Expanded JSON Data Format 1142 In this example the client requests a timezone in the expanded form. 1144 >> Request << 1146 GET /?action=expand&tzid=America/New_York&start=2008&end=2009 HTTP/1.1 1147 Host: tz.example.com 1149 >> Response << 1151 HTTP/1.1 200 OK 1152 Date: Mon, 11 Oct 2009 09:32:12 GMT 1153 Content-Type: application/json; charset="utf-8" 1154 Content-Length: xxxx 1155 ETag: "123456789-000-111" 1157 { 1158 "dtstamp": "2009-10-11T09:32:11Z", 1159 "observances": [ 1160 { 1161 "name": "Standard", 1162 "onset": "2008-01-01T00:00:00", 1163 "utc-offset-from": -18000, 1164 "utc-offset-to": -18000 1165 }, 1166 { 1167 "name": "Daylight", 1168 "onset": "2008-03-09T02:00:00", 1169 "utc-offset-from": -18000, 1170 "utc-offset-to": -14400 1171 }, 1172 { 1173 "name": "Standard", 1174 "onset": "2008-11-02T02:00:00", 1175 "utc-offset-from": -14400, 1176 "utc-offset-to": -18000 1177 }, 1178 ] 1179 } 1181 6.5. "find" Action 1183 Name: find 1184 Description: This action allows a client to query the timezone 1185 service for a matching identifier, alias or localized name, using 1186 a simple "glob" style match against the names known to the server 1187 (with an asterisk * as the wildcard character). Match strings 1188 have the following options: 1190 * not present An exact text match is done, e.g., "xyz" 1192 * first character only An ends-with text match is done, e.g., 1193 "*xyz" 1195 * last character only An starts-with text match is done, e.g., 1196 "xyz*" 1198 * first and last characters only A sub-string text match is done, 1199 e.g., "*xyz*" 1201 In addition, when matching, underscore characters (0x5F) SHOULD be 1202 mapped to a single space character (0x20) prior to string 1203 comparison. This allows timezone identifiers such as "America/ 1204 New_York" to match a query for "*New York*". ASCII characters in 1205 the range 0x41 ("A") through 0x5A ("Z") SHOULD be mapped to their 1206 lowercase equivalents. 1208 Parameters: 1210 action REQUIRED with value "find" 1212 name= REQUIRED, but MUST only occur once. 1214 lang= OPTIONAL, but MAY occur multiple times. 1216 Response: The response has the same format as the "list" action, 1217 with one result object per successful match, see Section 7.2. 1219 Possible Error Codes 1221 invalid-name The "name" query parameter is not present, or 1222 appears more than once. 1224 6.5.1. Example: Find action 1226 In this example the client asks for data about the timezone "US/ 1227 Eastern". 1229 >> Request << 1231 GET /?action=find&name=US/Eastern HTTP/1.1 1232 Host: tz.example.com 1234 >> Response << 1236 HTTP/1.1 200 OK 1237 Date: Wed, 4 Jun 2008 09:32:12 GMT 1238 Content-Type: application/json; charset="utf-8" 1239 Content-Length: xxxx 1241 { 1242 "dtstamp": "2009-10-11T09:32:11Z", 1243 "timezones": [ 1244 { 1245 "tzid": "America/New_York", 1246 "last-modified": "2009-09-17T01:39:34Z", 1247 "aliases":["US/Eastern"], 1248 "local-names": [ 1249 { 1250 "name": "America/New_York", 1251 "lang": "en_US" 1252 } 1253 ] 1254 }, 1255 { 1256 "tzid": "America/Detroit", 1257 "last-modified": "2009-09-17T01:39:34Z", 1258 "aliases":["US/Eastern"], 1259 "local-names": [ 1260 { 1261 "name": "America/Detroit", 1262 "lang": "en_US" 1263 } 1264 ] 1265 }, 1266 ... 1267 ] 1268 } 1270 7. JSON Definitions 1272 JSON members used by this specification are defined here using the 1273 syntax in [I-D.newton-json-content-rules]. Clients MUST ignore any 1274 JSON members they do not expect. 1276 7.1. capabilities action response 1278 JSON Content Rules for the JSON document returned for a 1279 "capabilities" action request. 1281 ; root object 1283 root { 1284 version, 1285 info, 1286 actions 1287 } 1289 ; The version number of the protocol supported - MUST be 1 1290 version "version" : integer 1..1 1292 ; object containing service information 1293 info "info" { 1294 primary_source / secondary_source, 1295 ?truncated, 1296 contacts 1297 } 1299 ; The source of the timezone data provided by a "primary" server 1300 primary_source "primary-source" : string 1302 ; The timezone server from which data is provided by a "secondary" 1303 ; server 1304 secondary_source "secondary-source" : uri 1306 ; Present if the server is providing truncated timezone data. The 1307 ; value is the truncation date-time. Timezone data will not be 1308 ; valid for dates prior to this value. 1309 ; [RFC3339] UTC value 1310 truncated "truncated" : { 1311 any, 1312 ?years, 1313 ?untruncated 1314 } 1316 ; Indicates whether the server can truncate timezone data at any year 1317 ; boundary in the past. When set to "true" any past year is a valid 1318 ; value for use with the "truncated" query parameter in an action 1319 ; "get" request 1320 any "any" : boolean 1322 ; Indicates which year boundaries the server has truncated data for. 1323 ; A value from this list may be used with the "truncated" query 1324 ; parameter in an action "get" request. Not present if "any" is set 1325 ; to "true" 1326 years "years" : [ * : integer ] 1328 ; Indicates whether the server can can supply untruncated data. When 1329 ; set to "true" indicates that, in addition to truncated data being 1330 ; available, the server can return untruncated data if an action "get" 1331 ; request is executed without a "truncated" query parameter 1332 untruncated "untruncated" : boolean 1334 ; Array of URIs providing contact details for the server 1335 ; administrator 1336 contacts "contacts" [ * : uri ] 1338 ; Array of actions supported by the server 1339 actions "actions" [ * action ] 1341 ; An action supported by the server 1342 action { 1343 action_name, 1344 action_params 1345 } 1347 ; Name of the action 1348 action_name "name" : string 1350 ; Array of request-URI query parameters supported by the action 1351 action_params "parameters" [ * parameter ] 1353 ; Object defining an action parameter 1354 parameter { 1355 param_name, 1356 ?param_required, 1357 ?param_multi, 1358 ?param_values 1359 } 1361 ; Name of the parameter 1362 param_name "name" : string 1364 ; If true the parameter has to be present in the request-URI 1365 ; default is false 1366 param_required "required" : boolean 1368 ; If true the parameter can occur more than once in the request-URI 1369 ; default is false 1370 param_multi "multi" : boolean, 1372 ; An array that defines the allowed set of values for the parameter 1373 ; In the absence of this member, any string value is acceptable 1374 param_values "values" [ * : string ] 1376 7.2. list action response 1378 JSON Content Rules for the JSON document returned for a "list" action 1379 request. 1381 ; root object 1383 root { 1384 dtstamp, 1385 timezones 1386 } 1388 ; Server generated timestamp used for synchronizing changes, 1389 ; [RFC3339] UTC value 1390 dtstamp "dtstamp" : date-time 1392 ; Array of timezone objects 1393 timezones "timezones" [ * timezone ] 1395 ; Information about a timezone available on the server 1396 timezone { 1397 tzid, 1398 last_modified, 1399 ?aliases, 1400 ?local_names, 1401 } 1403 ; Timezone identifier 1404 tzid "tzid" : string 1406 ; Date/time when the timezone data was last modified 1407 ; [RFC3339] UTC value 1408 last_modified "last-modified" : date-time 1410 ; An array that lists the set of timezone aliases available 1411 ; for the corresponding timezone 1412 aliases "aliases" [ * : string ] 1414 ; An array that lists the set of localized names available 1415 ; for the corresponding timezone 1416 local_names "local-names" [ * local_name ] 1418 local_name [lang, lname, ?pref] 1420 ; Language tag for the language of the associated name 1421 lang : string 1423 ; Localized name 1424 lname : string 1426 ; Indicates whether this is the preferred name for the associated 1427 ; language default: false 1428 pref : boolean 1430 7.3. expand action response 1432 JSON Content Rules for the JSON document returned for a "expand" 1433 action request. 1435 ; root object 1437 root { 1438 dtstamp, 1439 observances 1440 } 1442 ; Server generated timestamp used for synchronizing changes 1443 ; [RFC3339] UTC value 1444 dtstamp "dtstamp" : date-time 1446 ; Array of timezone objects 1447 observances "observances" [ * observance ] 1449 ; Information about a timezone available on the server 1450 observance { 1451 oname, 1452 ?olocal_names, 1453 onset, 1454 utc_offset_from, 1455 utc_offset_to 1456 } 1458 ; Observance name 1459 oname "name" : string 1461 ; Array of localized observance names 1462 olocal_names "local-names" [ * : string] 1464 ; The local time at which the observance takes effect 1465 ; [RFC3339] value modified to exclude "time-offset" part 1466 onset "onset" : date-time 1468 ; The UTC offset in seconds before the start of this observance 1469 utc_offset_from "utc-offset-from" : integer 1471 ; The UTC offset in seconds at and after the start of this observance 1472 utc_offset_to "utc-offset-to" : integer 1474 7.4. error response 1476 JSON Content Rules for the JSON document returned when an error 1477 occurs. 1479 ; root object 1481 root { 1482 error, 1483 ?description 1484 } 1486 ; Error code 1487 error "error" : string 1489 ; Description of the error 1490 description "description" : string 1492 8. Equivalent Timezone Identifier Property 1494 Property Name: EQUIVALENT-TZID 1496 Purpose: This property specifies an equivalent timezone identifier 1497 representing the same timezone data as the aliased "VTIMEZONE" 1498 component. 1500 Value Type: TEXT 1502 Property Parameters: IANA and non-standard property parameters can 1503 be specified on this property. 1505 Conformance: This property can be specified zero or more times 1506 within "VTIMEZONE" calendar components. 1508 Description: This property specifies an equivalent timezone 1509 identifier for a "VTIMEZONE" component when the "TZID" property of 1510 the timezone is an alias identifier. 1512 Format Definition: This property is defined by the following 1513 notation: 1515 equivalent-tzid = "EQUIVALENT-TZID" etzidpropparam ":" 1516 [tzidprefix] text CRLF 1518 etzidpropparam = *(";" other-param) 1520 ;tzidprefix defined in [RFC5545]. 1522 Example: The following is an example of this property: 1524 EQUIVALENT-TZID:US/Eastern 1526 9. Security Considerations 1528 Timezone data is critical in determining local or UTC time for 1529 devices and in calendaring and scheduling operations. As such, it is 1530 vital that a reliable source of timezone data is used. Servers 1531 providing a timezone service MUST support HTTP over Transport Layer 1532 Security (TLS) (as defined by [RFC2818]) with a valid certificate. 1533 Clients and servers making use of a timezone service SHOULD use HTTP 1534 over TLS and verify the authenticity of the service being used before 1535 accepting and using any timezone data from that source. 1537 Clients that support transport layer security as defined by [RFC2818] 1538 SHOULD try the "_timezones" service first before trying the 1539 "_timezone" service. Clients MUST follow the certificate 1540 verification process specified in [RFC6125]. 1542 A malicious attacker with access to the DNS server data, or able to 1543 get spoofed answers cached in a recursive resolver, can potentially 1544 cause clients to connect to any server chosen by the attacker. In 1545 the absence of a secure DNS option, clients SHOULD check that the 1546 target FQDN returned in the SRV record matches the original service 1547 domain that was queried. If the target FQDN is not in the queried 1548 domain, clients SHOULD verify with the user that the SRV target FQDN 1549 is suitable for use before executing any connections to the host. 1551 Timezone servers SHOULD protect themselves against errant or 1552 malicious clients by throttling high request rates or frequent 1553 requests for large amounts of data. Clients can avoid being 1554 throttled by using the polling capabilities outlined in Section 4.1.3 1556 10. IANA Considerations 1558 This specification defines a new registry of "actions" for the 1559 timezone service protocol, defines a "well-known" URI using the 1560 registration procedure and template from Section 5.1 of [RFC5785], 1561 creates two new SRV service label aliases, and defines one new 1562 iCalendar property parameter as per the registration procedure in 1563 [RFC5545]. 1565 10.1. Service Actions Registration 1567 This section defines the process to register new or modified timezone 1568 service actions with IANA. 1570 10.1.1. Service Actions Registration Procedure 1572 The IETF will create a mailing list, timezone-service@ietf.org, which 1573 can be used for public discussion of timezone service actions 1574 proposals prior to registration. Use of the mailing list is strongly 1575 encouraged. The IESG will appoint a designated expert who will 1576 monitor the timezone-service@ietf.org mailing list and review 1577 registrations. 1579 Registration of new timezone service actions MUST be reviewed by the 1580 designated expert and published in an RFC. A Standard Tracks RFC is 1581 REQUIRED for the registration of new timezone service actions. A 1582 Standard Tracks RFC is also REQUIRED for changes to actions 1583 previously documented in a Standard Tracks RFC. 1585 The registration procedure begins when a completed registration 1586 template, defined in the sections below, is sent to 1587 timezone-service@ietf.org and iana@iana.org. The designated expert 1588 is expected to tell IANA and the submitter of the registration within 1589 two weeks whether the registration is approved, approved with minor 1590 changes, or rejected with cause. When a registration is rejected 1591 with cause, it can be re-submitted if the concerns listed in the 1592 cause are addressed. Decisions made by the designated expert can be 1593 appealed to the IESG Applications Area Director, then to the IESG. 1594 They follow the normal appeals procedure for IESG decisions. 1596 10.1.2. Registration Template for Actions 1598 An action is defined by completing the following template. 1600 Name: The name of the action. This is also the value of the 1601 "action" parameter used in timezone service requests. 1603 Description: A general description of the action, its purpose, etc. 1605 Parameters: A list of allowed request parameters, indicating whether 1606 they are "REQUIRED" or "OPTIONAL" and whether they can occur only 1607 once or multiple times. 1609 Response The nature of the response to the HTTP request, e.g., what 1610 format the response data is in. 1612 10.1.3. Registration Template for Action Parameters 1614 An action parameter is defined by completing the following template. 1616 Name: The name of the parameter. 1618 Description: A general description of the parameter, its purpose, 1619 etc. 1621 Value: The format of the parameter value, or an indication that the 1622 parameter has no value. 1624 10.2. Initial Timezone Service Registries 1626 The IANA is requested to create and maintain the following registries 1627 for timezone service actions with pointers to appropriate reference 1628 documents. 1630 10.2.1. Actions Registry 1632 The following table is to be used to initialize the actions registry. 1634 +--------------+---------+----------------------+ 1635 | Action Name | Status | Reference | 1636 +--------------+---------+----------------------+ 1637 | capabilities | Current | RFCXXXX, Section 6.1 | 1638 | list | Current | RFCXXXX, Section 6.2 | 1639 | get | Current | RFCXXXX, Section 6.3 | 1640 | expand | Current | RFCXXXX, Section 6.4 | 1641 | find | Current | RFCXXXX, Section 6.5 | 1642 +--------------+---------+----------------------+ 1644 10.2.2. Action Parameters Registry 1646 The following table is to be used to initialize the parameters 1647 registry. 1649 +--------------+---------+----------------------+ 1650 | Parameter | Status | Reference | 1651 +--------------+---------+----------------------+ 1652 | action | Current | RFCXXXX, Section 5.1 | 1653 | changedsince | Current | RFCXXXX, Section 5.3 | 1654 | end | Current | RFCXXXX, Section 5.5 | 1655 | format | Current | RFCXXXX, Section 5.2 | 1656 | lang | Current | RFCXXXX, Section 5.6 | 1657 | name | Current | RFCXXXX, Section 5.8 | 1658 | start | Current | RFCXXXX, Section 5.4 | 1659 | truncate | Current | RFCXXXX, Section 5.9 | 1660 | tzid | Current | RFCXXXX, Section 5.7 | 1661 +--------------+---------+----------------------+ 1663 10.3. timezone Well-Known URI Registration 1665 URI suffix: timezone 1667 Change controller: IETF. 1669 Specification document(s): This RFC. 1671 Related information: 1673 10.4. Service Name Registrations 1675 This document registers two new service names as per [RFC6335]. Both 1676 are defined within this document. 1678 10.4.1. timezone Service Name Registration 1680 Service Name: timezone 1682 Transport Protocol(s): TCP 1684 Assignee: IESG 1686 Contact: IETF Chair 1688 Description: Timezone Service Protocol - non-TLS 1690 Reference: [draft-douglass-timezone-service] 1692 Assignment Note: This is an extension of the http service. Defined 1693 TXT keys: path= 1695 10.4.2. timezones Service Name Registration 1697 Service Name: timezones 1699 Transport Protocol(s): TCP 1701 Assignee: IESG 1703 Contact: IETF Chair 1705 Description: Timezone Service Protocol - over TLS 1707 Reference: [draft-douglass-timezone-service] 1709 Assignment Note: This is an extension of the https service. Defined 1710 TXT keys: path= 1712 10.5. iCalendar Property Registration 1714 This document defines the following new iCalendar property to be 1715 added to the registry defined in Section 8.2.3 of [RFC5545]: 1717 +-----------------+---------+--------------------+ 1718 | Property | Status | Reference | 1719 +-----------------+---------+--------------------+ 1720 | EQUIVALENT-TZID | Current | RFCXXXX, Section 8 | 1721 +-----------------+---------+--------------------+ 1723 11. Acknowledgements 1725 The authors would like to thank the members of the Calendaring and 1726 Scheduling Consortium's Timezone Technical Committee and the 1727 following individuals for contributing their ideas and support: Steve 1728 Allen, Steve Crocker, John Haug, Ciny Joy, Bryan Keller, Andrew 1729 McMillan, Ken Murchison, Arnaud Quillaud, and Jose Edvaldo Saraiva. 1731 The authors would also like to thank the Calendaring and Scheduling 1732 Consortium for advice with this specification. 1734 12. Normative References 1736 [I-D.ietf-jcardcal-jcal] 1737 Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 1738 format for iCalendar", draft-ietf-jcardcal-jcal-09 (work 1739 in progress), February 2014. 1741 [I-D.newton-json-content-rules] 1742 Newton, A., "A Language for Rules Describing JSON 1743 Content", draft-newton-json-content-rules-01 (work in 1744 progress), January 2013. 1746 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1747 Extensions (MIME) Part Two: Media Types", RFC 2046, 1748 November 1996. 1750 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1751 Requirement Levels", BCP 14, RFC 2119, March 1997. 1753 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1754 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1755 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1757 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1758 specifying the location of services (DNS SRV)", RFC 2782, 1759 February 2000. 1761 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1763 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1764 Internet: Timestamps", RFC 3339, July 2002. 1766 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1767 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1769 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 1770 Core Object Specification (iCalendar)", RFC 5545, 1771 September 2009. 1773 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1774 Languages", BCP 47, RFC 5646, September 2009. 1776 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1777 Uniform Resource Identifiers (URIs)", RFC 5785, 1778 April 2010. 1780 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1781 Verification of Domain-Based Application Service Identity 1782 within Internet Public Key Infrastructure Using X.509 1783 (PKIX) Certificates in the Context of Transport Layer 1784 Security (TLS)", RFC 6125, March 2011. 1786 [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML 1787 Format for iCalendar", RFC 6321, August 2011. 1789 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1790 Cheshire, "Internet Assigned Numbers Authority (IANA) 1791 Procedures for the Management of the Service Name and 1792 Transport Protocol Port Number Registry", BCP 165, 1793 RFC 6335, August 2011. 1795 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 1796 Time Zone Database", BCP 175, RFC 6557, February 2012. 1798 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1799 Discovery", RFC 6763, February 2013. 1801 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1802 Interchange Format", RFC 7159, March 2014. 1804 Appendix A. Change History (to be removed prior to publication as an 1805 RFC) 1807 Changes for -11 1809 1. start/end query parameter values are now just year numbers, no 1810 dates. 1812 Changes for -10 1814 1. Expand start/end query parameter values are now years rather than 1815 a date/date-time. 1817 2. Added tzid-not-found error code for get and expand actions. 1819 Changes for -09 1821 1. Servers are allowed to truncate timezone data but need to 1822 advertise when they do so. Clients can select from server- 1823 specified truncations. 1825 2. Explicitly list suggested polling intervals. 1827 3. Removed used of * for tzid value. 1829 4. Removed substitute alias. 1831 5. Added EQUIVALENT-TZID property. 1833 6. Added more details on truncation. 1835 7. Various editorial issues and clarifications. 1837 Changes for -08 1839 1. Editorial changes. 1841 2. Fixed JSON content rule syntax. 1843 3. Added a "version" to capabilities. 1845 4. Changed "error" member to a string. 1847 5. Added error codes. 1849 6. Updated reference. 1851 7. Removed inactive timezone feature and returnall parameter. 1853 Changes for -07 1855 1. Switched to JSON instead of XML and clean-ed up schema a little 1856 bit. 1858 2. Added changedsince to expand action. 1860 3. Added find into registry table. 1862 4. Re-organized some sections. 1864 Changes for -06 1866 1. Refresh prior to last call 1868 Changes for -05 1870 1. Replaced reference to draft RFC with RFC6557 and RFC6125. 1872 2. New XML namespace contact. 1874 3. Templates for service name. 1876 4. Various typos fixed. 1878 5. More acknowledgements. 1880 Changes for -04 1881 1. Replaced reference to RFC4646 with reference to RFC5646 1883 2. New wording on polling. 1885 Changes for -03 1887 1. Replaced erroneous reference to ISO3036 with reference to RFC4646 1889 2. Update reference to iCalendar in XML (RFC6321) 1891 3. More description of ids/aliases/names 1893 4. Add substitute-alias parameter for action=get 1895 5. Allow tzid on list 1897 6. Added name request parameter 1899 7. Added find action 1901 Changes for -02 1903 1. Missed definitions of the inactive element 1905 2. Restrict UtcOffsetFromType, UtcOffsetToType to a pattern - allow 1906 seconds. 1908 3. Use restricted XML dateTime as base for onset 1910 4. Use restricted XML dateTime for lastmodified and dtstamp 1912 5. Note that 0 and 1 are valid values for an XML boolean. 1914 6. Set pref to a default value of false 1916 7. Server will now set tzid of aliased timezones to the alias name 1918 8. Remove returnaliases option 1920 9. Aliases should not have lang attribute - removed 1922 10. Add text on status codes and an error element 1924 11. Added capabilities info element containing source | primary- 1925 source and contacts. 1927 Authors' Addresses 1929 Michael Douglass 1930 Rensselaer Polytechnic Institute 1931 110 8th Street 1932 Troy, NY 12180 1933 USA 1935 Email: douglm@rpi.edu 1936 URI: http://www.rpi.edu/ 1938 Cyrus Daboo 1939 Apple Inc. 1940 1 Infinite Loop 1941 Cupertino, CA 95014 1942 USA 1944 Email: cyrus@daboo.name 1945 URI: http://www.apple.com/