tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7808

 
 
 

Time Zone Data Distribution Service

Part 2 of 3, p. 18 to 41
Prev RFC Part       Next RFC Part

 


prevText      Top      ToC       Page 18 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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 RFC Part