Skip to content

Commit

Permalink
Move Representing Time section to Advanced Concepts section.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed Aug 4, 2024
1 parent 0b8827b commit 25f4df9
Showing 1 changed file with 98 additions and 95 deletions.
193 changes: 98 additions & 95 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1970,101 +1970,6 @@ <h3>Validity Period</h3>
valid from the time the `verifiable credential` was created.
</p>

<h4>Representing Time</h4>

<p>
Implementers are urged to understand that representing and processing time
values is not as straight-forward as it might seem and have a variety of
idiosyncrasies that are not immediately obvious nor uniformly observed in
different regions of the world. For example:
</p>

<ul>
<li>
Calendaring systems other than the Gregorian calendar are actively used by
various regions.
</li>
<li>
When processing Daylight Saving/Summer Time, it is important to understand that
1) it is not observed in all regions, 2) it does not necessarily begin or end on
the same day or at the same time of day, and 3) the amount or direction of the
adjustment does not always match other similar regions.
</li>
<li>
Leap seconds might not be taken into account in all software systems, especially
for dates and times that precede the introduction of the leap second. Leap
seconds can affects highly sensitive systems that depend on the exact
millisecond offset from the epoch. However, note that for most applications the
only moment in time that is affected is the one second period of the leap second
itself. That is, the moment after the most recent leap second can always be
represented as the first moment of the next day (for example,
`2023-01-01T00:00:00Z`), regardless of whether the system in question
understands leap seconds.
</li>
</ul>

<p>
These are just a few examples that illustrate that the actual time of day, as
would be seen on a clock on the wall, can exist in one region but not exist in
another region. For this reason, implementers are urged to use time values
that are more universal, such as values anchored to the `Z` time zone over
values that are affected by Daylight Saving/Summer Time.
</p>

<p>
This specification attempts to increase the number of universally recognized
combinations of dates and times, and reduce the potential for
misinterpretation of time values, by utilizing the
`dateTimeStamp` construction first established by the [<a
data-cite="XMLSCHEMA11-2#dateTimeStamp">XMLSCHEMA11-2</a>] specification. In
order to reduce misinterpretations between different time zones, all time values
expressed in [=conforming documents=] SHOULD be specified in `dateTimeStamp`
format, either in Universal Coordinated Time (UTC), denoted by a `Z` at the end
of the value, or with a time zone offset relative to UTC. Time values that are
incorrectly serialized without an offset MUST be interpreted as UTC. Examples of
valid time zone offsets relative to UTC include `Z`, `+01:00`, `-08:00`, and
`+14:00`. See the regular expression at the end of this section for a formal
definition of all acceptable values.
</p>

<p>
Time zone definitions are occasionally changed by their governing body. When
replacing or issuing new [=verifiable credentials=], implementers are advised
to ensure that changes to local time zone rules do not result in unexpected gaps
in validity. For example, consider the zone `America/Los_Angeles`, which has
a raw offset of UTC-8 and had voted to stop observing daylight savings time in
the year 2024. A given [=verifiable credential=] that had a `validUtil`
value of `2024-07-12T12:00:00-07:00`, might be re-issued to have a
`validFrom` value of `2024-07-12T12:00:00-08:00`, which would create a gap of
an hour where the [=verifiable credential=] would not be valid.
</p>

<p>
Implementers that desire to check `dateTimeStamp` values for validity
can use the regular expression provided below, which is reproduced from the [<a
data-cite="XMLSCHEMA11-2#dateTimeStamp">XMLSCHEMA11-2</a>] specification for
convenience. To avoid doubt, the regular expression in [[XMLSCHEMA11-2]] is the
normative definition. Implementers are advised that not all
`dateTimeStamp` values that pass the regular expression below are
valid moments in time. For example, the regular expression below allows for 31
days in every month, which allows for leap years, and leap seconds, as well as
days in places where they do not exist. That said, modern system libraries that
generate `dateTimeStamp` values are often error-free in their
generation of valid `dateTimeStamp` values. The regular
expression shown below (minus the whitespace included here for readability),
is often adequate when processing library-generated dates and times on
modern systems.
</p>

<pre class="example nohighlight"
title="Regular expression to detect a valid XML Schema 1.1: Part 2 dateTimeStamp">
-?([1-9][0-9]{3,}|0[0-9]{3})
-(0[1-9]|1[0-2])
-(0[1-9]|[12][0-9]|3[01])
T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]+)?|(24:00:00(\.0+)?))
(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))
</pre>

</section>

<section>
Expand Down Expand Up @@ -3800,6 +3705,104 @@ <h3>Zero-Knowledge Proofs</h3>

</section>

<section class="normative">
<h3>Representing Time</h3>

<p>
Implementers are urged to understand that representing and processing time
values is not as straight-forward as it might seem and have a variety of
idiosyncrasies that are not immediately obvious nor uniformly observed in
different regions of the world. For example:
</p>

<ul>
<li>
Calendaring systems other than the Gregorian calendar are actively used by
various regions.
</li>
<li>
When processing Daylight Saving/Summer Time, it is important to understand that
1) it is not observed in all regions, 2) it does not necessarily begin or end on
the same day or at the same time of day, and 3) the amount or direction of the
adjustment does not always match other similar regions.
</li>
<li>
Leap seconds might not be taken into account in all software systems, especially
for dates and times that precede the introduction of the leap second. Leap
seconds can affects highly sensitive systems that depend on the exact
millisecond offset from the epoch. However, note that for most applications the
only moment in time that is affected is the one second period of the leap second
itself. That is, the moment after the most recent leap second can always be
represented as the first moment of the next day (for example,
`2023-01-01T00:00:00Z`), regardless of whether the system in question
understands leap seconds.
</li>
</ul>

<p>
These are just a few examples that illustrate that the actual time of day, as
would be seen on a clock on the wall, can exist in one region but not exist in
another region. For this reason, implementers are urged to use time values
that are more universal, such as values anchored to the `Z` time zone over
values that are affected by Daylight Saving/Summer Time.
</p>

<p>
This specification attempts to increase the number of universally recognized
combinations of dates and times, and reduce the potential for
misinterpretation of time values, by utilizing the
`dateTimeStamp` construction first established by the [<a
data-cite="XMLSCHEMA11-2#dateTimeStamp">XMLSCHEMA11-2</a>] specification. In
order to reduce misinterpretations between different time zones, all time values
expressed in [=conforming documents=] SHOULD be specified in `dateTimeStamp`
format, either in Universal Coordinated Time (UTC), denoted by a `Z` at the end
of the value, or with a time zone offset relative to UTC. Time values that are
incorrectly serialized without an offset MUST be interpreted as UTC. Examples of
valid time zone offsets relative to UTC include `Z`, `+01:00`, `-08:00`, and
`+14:00`. See the regular expression at the end of this section for a formal
definition of all acceptable values.
</p>

<p>
Time zone definitions are occasionally changed by their governing body. When
replacing or issuing new [=verifiable credentials=], implementers are advised
to ensure that changes to local time zone rules do not result in unexpected gaps
in validity. For example, consider the zone `America/Los_Angeles`, which has
a raw offset of UTC-8 and had voted to stop observing daylight savings time in
the year 2024. A given [=verifiable credential=] that had a `validUtil`
value of `2024-07-12T12:00:00-07:00`, might be re-issued to have a
`validFrom` value of `2024-07-12T12:00:00-08:00`, which would create a gap of
an hour where the [=verifiable credential=] would not be valid.
</p>

<p>
Implementers that desire to check `dateTimeStamp` values for validity
can use the regular expression provided below, which is reproduced from the [<a
data-cite="XMLSCHEMA11-2#dateTimeStamp">XMLSCHEMA11-2</a>] specification for
convenience. To avoid doubt, the regular expression in [[XMLSCHEMA11-2]] is the
normative definition. Implementers are advised that not all
`dateTimeStamp` values that pass the regular expression below are
valid moments in time. For example, the regular expression below allows for 31
days in every month, which allows for leap years, and leap seconds, as well as
days in places where they do not exist. That said, modern system libraries that
generate `dateTimeStamp` values are often error-free in their
generation of valid `dateTimeStamp` values. The regular
expression shown below (minus the whitespace included here for readability),
is often adequate when processing library-generated dates and times on
modern systems.
</p>

<pre class="example nohighlight"
title="Regular expression to detect a valid XML Schema 1.1: Part 2 dateTimeStamp">
-?([1-9][0-9]{3,}|0[0-9]{3})
-(0[1-9]|1[0-2])
-(0[1-9]|[12][0-9]|3[01])
T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]+)?|(24:00:00(\.0+)?))
(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))
</pre>

</section>

<section class="informative">
<h3>Authorization</h3>

Expand Down

0 comments on commit 25f4df9

Please sign in to comment.