Skip to content

Commit 8f46ea1

Browse files
AlexandreCarltonAlexandreCarlton
committed
Add AccurateDuration and NominalDuration
This pull request attempts to document two different types of Durations per the ISO 8601 standard: - `AccurateDuration`, relating to the portion of a Duration that is context-free (that is, it only contains seconds, minutes, hours, and 24-hour days). - `NominalDuration`, relating ot the portion that is dependent on the position in the calendar with respect to which the duration is being evaluated. It contains calendar years, months, weeks and days. Please see graphql-java/graphql-java-extended-scalars#132 for the implementation in `graphql-java`.
1 parent 64615c9 commit 8f46ea1

File tree

2 files changed

+155
-0
lines changed

2 files changed

+155
-0
lines changed

‎scalars/contributed/AlexandreCarlton/accurate-duration.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<!-- cspell:ignore Alexandre -->
2+
3+
# AccurateDuration — GraphQL Custom Scalar
4+
5+
Author - AlexandreCarlton
6+
7+
Date - 2024-03-17
8+
9+
**License and Copyright**
10+
11+
Copyright © GraphQL contributors. This specification is licensed under
12+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
13+
14+
# Overview
15+
16+
This Scalar represents an exact length in time. It is a refinement of the
17+
duration as defined by [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) with
18+
the caveat that it does not support calendar components that would otherwise
19+
require the knowledge of a date to determine a precise value. As such, the following components are
20+
excluded:
21+
22+
- calendar year (as this can be potentially a leap year).
23+
- calendar month as this may contain a variable number of days).
24+
- calendar day (as this may contain leap seconds by decision of the [Internal Earth Rotation Service](https://en.wikipedia.org/wiki/International_Earth_Rotation_and_Reference_Systems_Service)).
25+
- calendar week (as this is seven calendar days).
26+
27+
Days (unlike calendar days) are supported under the definition of [ISO 31-1](https://en.wikipedia.org/wiki/ISO_31-1): 24 hours.
28+
29+
Negative durations per [ISO 8601-2](https://en.wikipedia.org/wiki/ISO_8601) are
30+
supported.
31+
32+
# Name
33+
34+
`AccurateDuration`, originating from the wording in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601):
35+
36+
<blockquote>Duration can be expressed by a combination of components with accurate duration (hour, minute and second)
37+
and components with nominal duration (year, month, week and day).</blockquote>
38+
39+
# Input/Result specification
40+
41+
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) defines a duration as
42+
either:
43+
44+
- `PnYnMnDTnHnMnS`
45+
- `PnW`
46+
47+
Instead, the specification `PDTnHnMn.nS` is used, with the further amendments:
48+
49+
- Year/Month/Week components are not supported.
50+
- Days are considered to be always 24 hours.
51+
- The entire string may be prefixed with a `-` to signify a negative duration.
52+
- Each component may be prefixed with a `-` to signify a negative component.
53+
- The seconds component (and only the seconds component) may have a fractional
54+
component of up to 9 digits.
55+
- Overflowing of components above their maximum (e.g. 60 for a minute) is
56+
allowed. For example, `PT90M` is valid and equivalent to `PT1H30M`.
57+
58+
## Positive examples
59+
60+
| String | Explanation |
61+
| ---------------- | ----------- |
62+
| `PT2M` | A duration representing 2 minutes. |
63+
| `PT120S` | A duration representing 120 seconds (2 minutes). |
64+
| `PT0.000000001S` | A duration representing 1 nanosecond. |
65+
| `-P1D` | A duration representing 1 negative day. |
66+
| `P1D-2H` | A duration representing two hours fewer than a full day. |
67+
68+
## Negative examples
69+
70+
| String | Explanation |
71+
| ----------------- | --------------------------------------------------------------- |
72+
| `P1Y` | Calendar years are not supported. |
73+
| `P1M` | Calendar months are not supported. |
74+
| `P1W` | Calendar weeks are not supported. |
75+
| `P0.5D` | Fractional component is only supported for seconds. |
76+
| `PT0.0000000001S` | Fractional component in seconds only supports at most 9 digits. |
77+
| `PTS` | Digits must preced units. |
78+
79+
# References
80+
81+
- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)

‎scalars/contributed/AlexandreCarlton/nominal-duration.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<!-- cspell:ignore Alexandre -->
2+
3+
# AccurateDuration — GraphQL Custom Scalar
4+
5+
Author - AlexandreCarlton
6+
7+
Date - 2024-03-17
8+
9+
**License and Copyright**
10+
11+
Copyright © GraphQL contributors. This specification is licensed under
12+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
13+
14+
# Overview
15+
16+
This Scalar represents a length in time in years, months, weeks or days. It is
17+
a refinement of the duration as defined by [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
18+
with the caveat that it only supports calendar components that require the
19+
knowledge of the particular calendar position with which the duration is being
20+
evaluated. As such, only the following components are included:
21+
22+
- calendar year (as this can be potentially a leap year).
23+
- calendar month as this may contain a variable number of days).
24+
- calendar day (as this may contain leap seconds by decision of the [Internal Earth Rotation Service](https://en.wikipedia.org/wiki/International_Earth_Rotation_and_Reference_Systems_Service)).
25+
- calendar week (as this is seven calendar days).
26+
27+
Negative durations per [ISO 8601-2](https://en.wikipedia.org/wiki/ISO_8601) are
28+
supported.
29+
30+
# Name
31+
32+
`NominalDuration`, originating from the wording in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601):
33+
34+
<blockquote>Duration can be expressed by a combination of components with accurate duration (hour, minute and second)
35+
and components with nominal duration (year, month, week and day).</blockquote>
36+
37+
# Input/Result specification
38+
39+
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) defines a duration as
40+
either:
41+
42+
- `PnYnMnDTnHnMnS`
43+
- `PnW`
44+
45+
Instead, the specification `PnYnMnWnD` is used, with the further amendments:
46+
47+
- The entire string may be prefixed with a `-` to signify a negative duration.
48+
- Each component may be prefixed with a `-` to signify a negative component.
49+
- A calendar week may be declared alongside calendar year/month/day components.
50+
51+
## Positive examples
52+
53+
| String | Explanation |
54+
| -------- | ------------------------------------------------------------------------- |
55+
| `P1Y` | A duration representing a calendar year. |
56+
| `P2W` | A duration representing two calendar weeks. |
57+
| `-P1Y2M` | A negative duration representing a calendar year and calendar month. |
58+
| `P1Y-2M` | A duration representing a two calendar months fewer than a calendar year. |
59+
| `P2M3W` | A duration representing a two calendar months and three calendar weeks. |
60+
| `P24M` | A duration representing a twenty four calendar months. |
61+
62+
## Negative examples
63+
64+
| String | Explanation |
65+
| ------- | ---------------------------------------- |
66+
| `PT1H` | Hours are not supported. |
67+
| `PT1M` | Minutes are not supported. |
68+
| `PT1S` | Seconds are not supported. |
69+
| `P1.5Y` | Fractional components are not supported. |
70+
| `PY` | Digits must precede units. |
71+
72+
# References
73+
74+
- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)

0 commit comments

Comments
 (0)