RFC 7808
Time Zone Data Distribution Service
Pages: 56
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 18 to 41
5. Actions
Servers MUST support the following actions. The information below shows details about each action: the request-URI the client targets (in the form of a URI template [RFC6570]), a description, the set of allowed query parameters, the nature of the response, and a set of possible error codes for the response (see Section 4.1.7). For any error not covered by the specific error codes defined below, the "urn:ietf:params:tzdist:error:invalid-action" error code is returned to the client in the JSON "problem details" object. The examples in the following subsections presume that the timezone context path has been discovered to be "/servlet/timezone" (as in the example in Section 4.2.1.3.1).5.1. "capabilities" Action
Name: capabilities Request-URI Template: {/service-prefix}/capabilities Description: This action returns the capabilities of the server, allowing clients to determine if a specific feature has been deployed and/or enabled. Parameters: None
Response: A JSON object containing a "version" member, an "info"
member, and an "actions" member; see Section 6.1.
Possible Error Codes: No specific code.
5.1.1. Example: get capabilities
>> Request <<
GET /servlet/timezone/capabilities HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"version": 1,
"info": {
"primary-source": "Olson:2011m",
"formats": [
"text/calendar",
"application/calendar+xml",
"application/calendar+json"
],
"truncated" : {
"any": false,
"ranges": [
{
"start": "1970-01-01T00:00:00Z",
"end": "*"
},
{
"start":"2010-01-01T00:00:00Z",
"end":"2020-01-01T00:00:00Z"
}
],
"untruncated": true
},
"provider-details": "http://tz.example.com/about.html",
"contacts": ["mailto:tzs@example.org"]
},
"actions": [
{
"name": "capabilities",
"uri-template": "/servlet/timezone/capabilities",
"parameters": []
},
{
"name": "list",
"uri-template": "/servlet/timezone/zones{?changedsince}",
"parameters": [
{
"name": "changedsince",
"required": false,
"multi": false
}
]
},
{
"name": "get",
"uri-template": "/servlet/timezone/zones{/tzid}{?start,end}",
"parameters": [
{
"name": "start",
"required": false,
"multi": false
},
{
"name": "end",
"required": false,
"multi": false
}
]
},
{
"name": "expand",
"uri-template":
"/servlet/timezone/zones{/tzid}/observances{?start,end}",
"parameters": [
{
"name": "start",
"required": true,
"multi": false
},
{
"name": "end",
"required": true,
"multi": false
}
]
},
{
"name": "find",
"uri-template": "/servlet/timezone/zones{?pattern}",
"parameters": [
{
"name": "pattern",
"required": true,
"multi": false
}
]
},
{
"name": "leapseconds",
"uri-template": "/servlet/timezone/leapseconds",
"parameters": []
}
]
}
5.2. "list" Action
Name: list
Request-URI Template:
{/service-prefix,data-prefix}/zones{?changedsince}
Description: This action lists all time zone identifiers in summary
format, with publisher, version, aliases, and optional localized
data. In addition, it returns an opaque synchronization token for
the entire response. If the "changedsince" URI query parameter is
present, its value MUST correspond to a previously returned
synchronization token value. When "changedsince" is used, the
server MUST return only those time zones that have changed since
the specified synchronization token. If the "changedsince" value
is not supported by the server, the server MUST return all time
zones, treating the request as if it had no "changedsince".
Parameters:
changedsince
OPTIONAL, and MUST NOT occur more than once.
Response: A JSON object containing a "synctoken" member and a
"timezones" member; see Section 6.2.
Possible Error Codes:
urn:ietf:params:tzdist:error:invalid-changedsince
The "changedsince" URI query parameter appears more than once.
5.2.1. Example: List Time Zone Identifiers
In this example the client requests the full set of time zone
identifiers.
>> Request <<
GET /servlet/timezone/zones HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"synctoken": "2009-10-11T09:32:11Z",
"timezones": [
{
"tzid": "America/New_York",
"etag": "123456789-000-111",
"last-modified": "2009-09-17T01:39:34Z",
"publisher": "Example.com",
"version": "2015a",
"aliases":["US/Eastern"],
"local-names": [
{
"name": "America/New_York",
"lang": "en_US"
}
]
},
...other time zones...
]
}
5.3. "get" Action
Name: get Request-URI Template: {/service-prefix,data-prefix}/zones{/tzid}{?start,end} The "tzid" variable value is REQUIRED in order to distinguish this action from the "list" action. Description: This action returns a time zone. The response MUST contain an ETag response header field indicating the current value of the strong entity tag of the time zone resource. In the absence of any Accept HTTP request header field, the server MUST return time zone data with the "text/calendar" media type. If the "tzid" variable value is actually a time zone alias, the server will return the matching time zone data with the alias as the identifier in the time zone data. The server MAY include one or more "TZID-ALIAS-OF" properties (see Section 7.2) in the time zone data to indicate additional identifiers that have the matching time zone identifier as an alias. Parameters: start=<date-time> OPTIONAL, and MUST NOT occur more than once. Specifies the inclusive UTC date-time value at which the returned time zone data is truncated at its start. end=<date-time> OPTIONAL, and MUST NOT occur more than once. Specifies the exclusive UTC date-time value at which the returned time zone data is truncated at its end. Response: A document containing all the requested time zone data in the format specified. Possible Error Codes: urn:ietf:params:tzdist:error:tzid-not-found No time zone associated with the specified "tzid" path segment value was found.
urn:ietf:params:tzdist:error:invalid-format
The Accept request header field supplied by the client did not
contain a media type for time zone data supported by the
server.
urn:ietf:params:tzdist:error:invalid-start
The "start" URI query parameter has an incorrect value, or
appears more than once, or does not match one of the fixed
truncation range start values advertised in the "capabilities"
action response.
urn:ietf:params:tzdist:error:invalid-end
The "end" URI query parameter has an incorrect value, or
appears more than once, or has a value less than or equal to
the "start" URI query parameter, or does not match one of the
fixed truncation range end values advertised in the
"capabilities" action response.
5.3.1. Example: Get Time Zone Data
In this example, the client requests that the time zone with a
specific time zone identifier be returned.
>> Request <<
GET /servlet/timezone/zones/America%2FNew_York HTTP/1.1
Host: tz.example.com
Accept:text/calendar
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: text/calendar; charset="utf-8"
Content-Length: xxxx
ETag: "123456789-000-111"
BEGIN:VCALENDAR
...
BEGIN:VTIMEZONE
TZID:America/New_York
...
END:VTIMEZONE
END:VCALENDAR
5.3.2. Example: Conditional Get Time Zone Data
In this example the client requests that the time zone with a specific time zone identifier be returned, but uses an If-None-Match header field in the request, set to the value of a previously returned ETag header field, or the value of the "etag" member in a JSON "timezone" object returned from a "list" action response. In this example, the data on the server has not changed, so a 304 response is returned. >> Request << GET /servlet/timezone/zones/America%2FNew_York HTTP/1.1 Host: tz.example.com Accept:text/calendar If-None-Match: "123456789-000-111" >> Response << HTTP/1.1 304 Not Modified Date: Wed, 4 Jun 2008 09:32:12 GMT5.3.3. Example: Get Time Zone Data Using a Time Zone Alias
In this example, the client requests that the time zone with an aliased time zone identifier be returned, and the server returns the time zone data with that identifier and two aliases. >> Request << GET /servlet/timezone/zones/US%2FEastern HTTP/1.1 Host: tz.example.com Accept:text/calendar >> Response << HTTP/1.1 200 OK Date: Wed, 4 Jun 2008 09:32:12 GMT Content-Type: text/calendar; charset="utf-8" Content-Length: xxxx ETag: "123456789-000-111" BEGIN:VCALENDAR ... BEGIN:VTIMEZONE TZID:US/Eastern TZID-ALIAS-OF:America/New_York TZID-ALIAS-OF:America/Montreal
... END:VTIMEZONE END:VCALENDAR5.3.4. Example: Get Truncated Time Zone Data
Assume the server advertises a "truncated" object in its "capabilities" response that appears as: "truncated": { "any": false, "ranges": [ {"start": "1970-01-01T00:00:00Z", "end": "*"}, {"start":"2010-01-01T00:00:00Z", "end":"2020-01-01T00:00:00Z"} ], "untruncated": false } In this example, the client requests that the time zone with a specific time zone identifier truncated at one of the ranges specified by the server be returned. Note the presence of a "STANDARD" component that matches the start point of the truncation range (converted to the local time for the UTC offset in effect at the matching UTC time). Also, note the presence of the "TZUNTIL" (Section 7.1) iCalendar property in the "VTIMEZONE" component, indicating the upper bound on the validity period of the time zone data. >> Request << GET /servlet/timezone/zones/America%2FNew_York ?start=2010-01-01T00:00:00Z&end=2020-01-01T00:00:00Z HTTP/1.1 Host: tz.example.com Accept:text/calendar >> Response << HTTP/1.1 200 OK Date: Wed, 4 Jun 2008 09:32:12 GMT Content-Type: text/calendar; charset="utf-8" Content-Length: xxxx ETag: "123456789-000-111" BEGIN:VCALENDAR ... BEGIN:VTIMEZONE TZID:America/New_York TZUNTIL:20200101T000000Z
BEGIN:STANDARD DTSTART:20101231T190000 TZNAME:EST TZOFFSETFROM:-0500 TZOFFSETTO:-0500 END:STANDARD ... END:VTIMEZONE END:VCALENDAR5.3.5. Example: Request for a Nonexistent Time Zone
In this example, the client requests that the time zone with a specific time zone identifier be returned. As it turns out, no time zone exists with that identifier. >> Request << GET /servlet/timezone/zones/America%2FPittsburgh HTTP/1.1 Host: tz.example.com Accept:application/calendar+json >> Response << HTTP/1.1 404 Not Found Date: Wed, 4 Jun 2008 09:32:12 GMT Content-Type: application/problem+json; charset="utf-8" Content-Language: en Content-Length: xxxx { "type": "urn:ietf:params:tzdist:error:tzid-not-found", "title": "Time zone identifier was not found on this server", "status": 404 }5.4. "expand" Action
Name: expand Request-URI Template: {/service-prefix,data-prefix}/zones{/tzid}/observances{?start,end} The "tzid" variable value is REQUIRED.
Description: This action expands the specified time zone into a list
of onset start date/time values (in UTC) and UTC offsets. The
response MUST contain an ETag response header field indicating the
current value of the strong entity tag of the time zone being
expanded.
Parameters:
start=<date-time>: REQUIRED, and MUST occur only once. Specifies
the inclusive UTC date-time value for the start of the period
of interest.
end=<date-time>: REQUIRED, and MUST occur only once. Specifies
the exclusive UTC date-time value for the end of the period of
interest. Note that this is the exclusive end value, i.e., it
represents the date just after the range of interest. For if a
client wants the expanded date just for the year 2014, it would
use a start value of "2014-01-01T00:00:00Z" and an end value of
"2015-01-01T00:00:00Z". An error occurs if the end value is
less than or equal to the start value.
Response: A JSON object containing a "tzid" member and an
"observances" member; see Section 6.3. If the time zone being
expanded is not fully defined over the requested time range (e.g.,
because of truncation), then the server MUST include "start" and/
or "end" members in the JSON response to indicate the actual start
and end points for the observances being returned. The server
MUST include an expanded observance representing the time zone
information in effect at the start of the returned observance
period.
Possible Error Codes
urn:ietf:params:tzdist:error:tzid-not-found
No time zone associated with the specified "tzid" path segment
value was found.
urn:ietf:params:tzdist:error:invalid-start
The "start" URI query parameter has an incorrect value, or
appears more than once, or is missing, or has a value outside
any fixed truncation ranges advertised in the "capabilities"
action response.
urn:ietf:params:tzdist:error:invalid-end
The "end" URI query parameter has an incorrect value, or
appears more than once, or has a value less than or equal to
the "start" URI query parameter, or has a value outside any
fixed truncation ranges advertised in the "capabilities" action
response.
5.4.1. Example: Expanded JSON Data Format
In this example, the client requests a time zone in the expanded
form.
>> Request <<
GET /servlet/timezone/zones/America%2FNew_York/observances
?start=2008-01-01T00:00:00Z&end=2009-01-01T00:00:00Z HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Mon, 11 Oct 2009 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
ETag: "123456789-000-111"
{
"tzid": "America/New_York",
"observances": [
{
"name": "Standard",
"onset": "2008-01-01T00:00:00Z",
"utc-offset-from": -18000,
"utc-offset-to": -18000
},
{
"name": "Daylight",
"onset": "2008-03-09T07:00:00Z",
"utc-offset-from": -18000,
"utc-offset-to": -14400
},
{
"name": "Standard",
"onset": "2008-11-02T06:00:00Z",
"utc-offset-from": -14400,
"utc-offset-to": -18000
},
]
}
5.5. "find" Action
Name: find Request-URI Template: {/service-prefix,data-prefix}/zones{?pattern} Description: This action allows a client to query the time zone data distribution service for a matching identifier, alias, or localized name, using a simple "glob" style patter match against the names known to the server (with an asterisk (*) as the wildcard character). Pattern-match strings (which have to be percent-encoded and then decoded when used in the URI query parameter) have the following options: * not present: An exact text match is done, e.g., "xyz" * first character only: An ends-with text match is done, e.g., "*xyz" * last character only: A starts-with text match is done, e.g., "xyz*" * first and last characters only: A substring text match is done, e.g., "*xyz*" Escaping \ and *: To match 0x2A ("*") and 0x5C ("\") characters in a time zone identifier, those characters have to be "escaped" in the pattern by prepending a single 0x5C ("\") character. For example, a pattern "\*Test\\Time\*Zone\*" is used for an exact match against the time zone identifier "*Test\Time*Zone*". An unescaped "*" character MUST NOT appear in the middle of the string and MUST result in an error. An unescaped "\" character MUST NOT appear anywhere in the string and MUST result in an error. In addition, when matching: Underscores: Underscore characters (0x5F) in time zone identifiers MUST be mapped to a single space character (0x20) prior to string comparison in both the pattern and time zone identifiers being matched. This allows time zone identifiers such as "America/New_York" to match a query for "*New York*". Case mapping: ASCII characters in the range 0x41 ("A") through 0x5A ("Z") MUST be mapped to their lowercase equivalents in both the pattern and time zone identifiers being matched.
Parameters:
pattern=<text>
REQUIRED, and MUST occur only once.
Response: The response has the same format as the "list" action,
with one result object per successful match; see Section 6.2.
Possible Error Codes
urn:ietf:params:tzdist:error:invalid-pattern
The "pattern" URI query parameter has an incorrect value or
appears more than once.
5.5.1. Example: find action
In this example, the client asks for data about the time zone
"US/Eastern".
>> Request <<
GET /servlet/timezone/zones?pattern=US/Eastern HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"synctoken": "2009-10-11T09:32:11Z",
"timezones": [
{
"tzid": "America/New_York",
"etag": "123456789-000-111",
"last-modified": "2009-09-17T01:39:34Z",
"publisher": "Example.com",
"version": "2015a",
"aliases":["US/Eastern"],
"local-names": [
{
"name": "America/New_York",
"lang": "en_US"
}
]
},
{
"tzid": "America/Detroit",
"etag": "123456789-999-222",
"last-modified": "2009-09-17T01:39:34Z",
"publisher": "Example.com",
"version": "2015a",
"aliases":["US/Eastern"],
"local-names": [
{
"name": "America/Detroit",
"lang": "en_US"
}
]
},
...
]
}
5.6. "leapseconds" Action
Name: leapseconds
Request-URI Template:
{/service-prefix,data-prefix}/leapseconds
Description: This action allows a client to query the time zone data
distribution service to retrieve the current leap-second
information available on the server.
Parameters: None
Response: A JSON object containing an "expires" member, a
"publisher" member, a "version" member, and a "leapseconds"
member; see Section 6.4. The "expires" member in the JSON
response indicates the latest date covered by leap-second
information. For example (as in Section 5.6.1), if the "expires"
value is set to "2014-06-28" and the latest leap-second change
indicated was at "2012-07-01", then the data indicates that there
are no leap seconds added (or removed) between those two dates,
and information for leap seconds beyond the "expires" date is not
yet available.
The "leapseconds" member contains a list of JSON objects each of
which contains a "utc-offset" and "onset" member. The "onset"
member specifies the date (with the implied time of 00:00:00 UTC)
at which the corresponding UTC offset from TAI takes effect. In
other words, a leap second is added or removed just prior to time
00:00:00 UTC of the specified onset date. When a leap second is
added, the "utc-offset" value will be incremented by one; when a
leap second is removed, the "utc-offset" value will be decremented
by one.
Possible Error Codes No specific code.
5.6.1. Example: Get Leap-Second Information
In this example, the client requests the current leap-second
information from the server.
>> Request <<
GET /servlet/timezone/leapseconds HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"expires": "2015-12-28",
"publisher": "Example.com",
"version": "2015d",
"leapseconds": [
{
"utc-offset": 10,
"onset": "1972-01-01",
},
{
"utc-offset": 11,
"onset": "1972-07-01",
},
...
{
"utc-offset": 35,
"onset": "2012-07-01",
},
{
"utc-offset": 36,
"onset": "2015-07-01",
}
]
}
6. JSON Definitions
[RFC7159] defines the structure of JSON objects using a set of primitive elements. The structure of JSON objects used by this specification is described by the following set of rules: OBJECT represents a JSON object, defined in Section 4 of [RFC7159]. "OBJECT" is followed by a parenthesized list of "MEMBER" rule names. If a member rule name is preceded by a "?" (0x3F) character, that member is optional; otherwise, all members are required. If two or more member rule names are present, each separated from the other by a "|" (0x7C) character, then only one of those members MUST be present in the JSON object. JSON object members are unordered, and thus the order used in the rules is not significant. MEMBER represents a member of a JSON object, defined in Section 4 of [RFC7159]. "MEMBER" is followed by a rule name, the name of the member, a ":", and then the value. A value can be one of "OBJECT", "ARRAY", "NUMBER", "STRING", or "BOOLEAN" rules. ARRAY represents a JSON array, defined in Section 5 of [RFC7159]. "ARRAY" is followed by a value (one of "OBJECT", "ARRAY", "NUMBER", "STRING", or "BOOLEAN"), indicating the type of items used in the array. NUMBER represents a JSON number, defined in Section 6 of [RFC7159]. STRING represents a JSON string, defined in Section 7 of [RFC7159]. BOOLEAN represents either of the JSON values "true" or "false", defined in Section 3 of [RFC7159]. ; a line starting with a ";" (0x3B) character is a comment. Note, clients MUST ignore any unexpected JSON members in responses from the server.6.1. capabilities Action Response
Below are the rules for the JSON document returned for a "capabilities" action request. ; root object OBJECT (version, info, actions) ; The version number of the protocol supported - MUST be 1 MEMBER version "version" : NUMBER
; object containing service information
; Only one of primary_source or secondary_source MUST be present
MEMBER info "info" : OBJECT (
primary_source | secondary_source,
formats,
?truncated,
?provider_details,
?contacts
)
; The source of the time zone data provided by a "primary" server
MEMBER primary_source "primary-source" : STRING
; The time zone data server from which data is provided by a
; "secondary" server
MEMBER secondary_source "secondary-source" : STRING
; Array of one or more media types for the time zone data formats
; that the server can return
MEMBER formats "formats" : ARRAY STRING
; Present if the server is providing truncated time zone data. The
; value is an object providing details of the supported truncation
; modes.
MEMBER truncated "truncated" : OBJECT: (
any,
?ranges,
?untruncated
)
; Indicates whether the server can truncate time zone data at any
; start or end point. When set to "true", any start or end point is
; a valid value for use with the "start" and "end" URI query
; parameters in a "get" action request.
MEMBER any "any" : BOOLEAN
; Indicates which ranges of time the server has truncated data for.
; A value from this list may be used with the "start" and "end" URI
; query parameters in a "get" action request. Not present if "any"
; is set to "true".
MEMBER ranges "ranges" : ARRAY OBJECT (range-start, range-end)
; UTC date-time value (per [RFC3339]) for inclusive start of the
; range, or the single character "*" to indicate a value
; corresponding to the lower bound supplied by the publisher of the
; time zone data
MEMBER range-start "start" : STRING
; UTC date-time value (per [RFC3339]) for exclusive end of the range, ; or the single character "*" to indicate a value corresponding to ; the upper bound supplied by the publisher of the time zone data MEMBER range-end "end" : STRING ; Indicates whether the server can supply untruncated data. When ; set to "true", indicates that, in addition to truncated data being ; available, the server can return untruncated data if a "get" ; action request is executed without a "start" or "end" URI query ; parameter. MEMBER untruncated "untruncated" : BOOLEAN ; A URI where human-readable details about the time zone service ; is available MEMBER provider_details "provider-details" : STRING ; Array of URIs providing contact details for the server ; administrator MEMBER contacts "contacts" : ARRAY STRING ; Array of actions supported by the server MEMBER actions "actions" : ARRAY OBJECT ( action_name, action_params ) ; Name of the action MEMBER action_name: "name" : STRING ; Array of request-URI query parameters supported by the action MEMBER action_params: "parameters" ARRAY OBJECT ( param_name, ?param_required, ?param_multi, ?param_values ) ; Name of the parameter MEMBER param_name "name" : STRING ; If true, the parameter has to be present in the request-URI ; default is false MEMBER param_required "required" : BOOLEAN ; If true, the parameter can occur more than once in the request-URI ; default is false MEMBER param_multi "multi" : BOOLEAN,
; An array that defines the allowed set of values for the parameter ; In the absence of this member, any string value is acceptable MEMBER param_values "values" ARRAY STRING6.2. list/find Action Response
Below are the rules for the JSON document returned for a "list" or "find" action request. ; root object OBJECT (synctoken, timezones) ; Server-generated opaque token used for synchronizing changes MEMBER synctoken "synctoken" : STRING ; Array of time zone objects MEMBER timezones "timezones" : ARRAY OBJECT ( tzid, etag, last_modified, publisher, version, ?aliases, ?local_names, ) ; Time zone identifier MEMBER tzid "tzid" : STRING ; Current ETag for the corresponding time zone data resource MEMBER etag "etag" : STRING ; Date/time when the time zone data was last modified ; UTC date-time value as specified in [RFC3339] MEMBER last_modified "last-modified" : STRING ; Time zone data publisher MEMBER publisher "publisher" : STRING ; Current version of the time zone data as defined by the ; publisher MEMBER version "version" : STRING ; An array that lists the set of time zone aliases available ; for the corresponding time zone MEMBER aliases "aliases" : ARRAY STRING
; An array that lists the set of localized names available
; for the corresponding time zone
MEMBER local_names "local-names" : ARRAY OBJECT (
lname, lang, ?pref
)
; Language tag for the language of the associated name
MEMBER: lang "lang" : STRING
; Localized name
MEMBER lname "name" : STRING
; Indicates whether this is the preferred name for the associated
; language default: false
MEMBER pref "pref" : BOOLEAN
6.3. expand Action Response
Below are the rules for the JSON document returned for a "expand"
action request.
; root object
OBJECT (
tzid,
?start,
?end,
observances
)
; Time zone identifier
MEMBER tzid "tzid" : STRING
; The actual inclusive start point for the returned observances
; if different from the value of the "start" URI query parameter
MEMBER start "start" : STRING
; The actual exclusive end point for the returned observances
; if different from the value of the "end" URI query parameter
MEMBER end "end" : STRING
; Array of time zone objects
MEMBER observances "observances" : ARRAY OBJECT (
oname,
?olocal_names,
onset,
utc_offset_from,
utc_offset_to
)
; Observance name MEMBER oname "name" : STRING ; Array of localized observance names MEMBER olocal_names "local-names" : ARRAY STRING ; UTC date-time value (per [RFC3339]) at which the observance takes ; effect MEMBER onset "onset" : STRING ; The UTC offset in seconds before the start of this observance MEMBER utc_offset_from "utc-offset-from" : NUMBER ; The UTC offset in seconds at and after the start of this observance MEMBER utc_offset_to "utc-offset-to" : NUMBER6.4. leapseconds Action Response
Below are the rules for the JSON document returned for a "leapseconds" action request. ; root object OBJECT ( expires, publisher, version, leapseconds ) ; Last valid date covered by the data in this response ; full-date value as specified in [RFC3339] MEMBER expires "expires" : STRING ; Leap-second information publisher MEMBER publisher "publisher" : STRING ; Current version of the leap-second information as defined by the ; publisher MEMBER version "version" : STRING ; Array of leap-second objects MEMBER leapseconds "leapseconds" : ARRAY OBJECT ( utc_offset, onset )
; The UTC offset from TAI in seconds in effect at and after the ; specified date MEMBER utc_offset "utc-offset" : NUMBER ; full-date value (per [RFC3339]) at which the new UTC offset takes ; effect, at T00:00:00Z MEMBER onset "onset" : STRING7. New iCalendar Properties
7.1. Time Zone Upper Bound
Property Name: TZUNTIL Purpose: This property specifies an upper bound for the validity period of data within a "VTIMEZONE" component. Value Type: DATE-TIME Property Parameters: IANA and non-standard property parameters can be specified on this property. Conformance: This property can be specified zero times or one time within "VTIMEZONE" calendar components. Description: The value MUST be specified in the UTC time format. Time zone data in a "VTIMEZONE" component might cover only a fixed period of time. The start of such a period is clearly indicated by the earliest observance defined by the "STANDARD" and "DAYLIGHT" subcomponents. However, an upper bound on the validity period of the time zone data cannot be simply derived from the observance with the latest onset time, and [RFC5545] does not define a way to get such an upper bound. This specification introduces the "TZUNTIL" property for that purpose. It specifies an "exclusive" UTC date-time value that indicates the last time at which the time zone data is to be considered valid. This property is also used by time zone data distribution servers to indicate the truncation range end point of time zone data (as described in Section 3.9). Format Definition: This property is defined by the following notation in ABNF [RFC5234]: tzuntil = "TZUNTIL" tzuntilparam ":" date-time CRLF tzuntilparam = *(";" other-param)
Example: Suppose a time zone based on astronomical observations has
well-defined onset times through the year 2025, but the first
onset in 2026 is currently known only approximately. In that
case, the "TZUNTIL" property could be specified as follows:
TZUNTIL:20260101T000000Z
7.2. Time Zone Identifier Alias Property
Property Name: TZID-ALIAS-OF
Purpose: This property specifies a time zone identifier for which
the main time zone identifier is an alias.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can
be specified on this property.
Conformance: This property can be specified zero or more times
within "VTIMEZONE" calendar components.
Description: When the "VTIMEZONE" component uses a time zone
identifier alias for the "TZID" property value, the "TZID-ALIAS-
OF" property is used to indicate the time zone identifier of the
other time zone (see Section 3.7).
Format Definition: This property is defined by the following
notation in ABNF [RFC5234]:
tzid-alias-of = "TZID-ALIAS-OF" tzidaliasofparam ":"
[tzidprefix] text CRLF
tzidaliasofparam = *(";" other-param)
;tzidprefix defined in [RFC5545].
Example: The following is an example of this property:
TZID-ALIAS-OF:America/New_York
(next page on part 3)