Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7808

Time Zone Data Distribution Service

Pages: 56
Proposed Standard
Part 2 of 3 – Pages 18 to 41
First   Prev   Next

Top   ToC   RFC7808 - Page 18   prevText

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
Top   ToC   RFC7808 - Page 19
   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"] },
Top   ToC   RFC7808 - Page 20
     "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",
Top   ToC   RFC7808 - Page 21
             "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.
Top   ToC   RFC7808 - Page 22
   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... ] }
Top   ToC   RFC7808 - Page 23

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.
Top   ToC   RFC7808 - Page 24
      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
Top   ToC   RFC7808 - Page 25

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 GMT

5.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
Top   ToC   RFC7808 - Page 26
   ...
   END:VTIMEZONE
   END:VCALENDAR

5.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
Top   ToC   RFC7808 - Page 27
   BEGIN:STANDARD
   DTSTART:20101231T190000
   TZNAME:EST
   TZOFFSETFROM:-0500
   TZOFFSETTO:-0500
   END:STANDARD
   ...
   END:VTIMEZONE
   END:VCALENDAR

5.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.
Top   ToC   RFC7808 - Page 28
   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
Top   ToC   RFC7808 - Page 29
         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 }, ] }
Top   ToC   RFC7808 - Page 30

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.
Top   ToC   RFC7808 - Page 31
   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" } ] },
Top   ToC   RFC7808 - Page 32
       {
         "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
Top   ToC   RFC7808 - Page 33
      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", } ] }
Top   ToC   RFC7808 - Page 34

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
Top   ToC   RFC7808 - Page 35
   ; 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
Top   ToC   RFC7808 - Page 36
   ; 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,
Top   ToC   RFC7808 - Page 37
   ; 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 STRING

6.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
Top   ToC   RFC7808 - Page 38
   ; 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 )
Top   ToC   RFC7808 - Page 39
   ; 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" : NUMBER

6.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 )
Top   ToC   RFC7808 - Page 40
   ; 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" : STRING

7. 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)
Top   ToC   RFC7808 - Page 41
   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)

Next Section