Skip to content

Commit 20a0f64

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 20a0f64

File tree

2 files changed

+159
-0
lines changed

2 files changed

+159
-0
lines changed

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
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
20+
following components are 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
25+
[Internal Earth Rotation Service](https://en.wikipedia.org/wiki/International_Earth_Rotation_and_Reference_Systems_Service)).
26+
- calendar week (as this is seven calendar days).
27+
28+
Days (unlike calendar days) are supported under the definition of
29+
[ISO 31-1](https://en.wikipedia.org/wiki/ISO_31-1): 24 hours.
30+
31+
Negative durations per [ISO 8601-2](https://en.wikipedia.org/wiki/ISO_8601) are
32+
supported.
33+
34+
# Name
35+
36+
`AccurateDuration`, originating from the wording in
37+
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601):
38+
39+
<blockquote>Duration can be expressed by a combination of components with accurate duration (hour, minute and second)
40+
and components with nominal duration (year, month, week and day).</blockquote>
41+
42+
# Input/Result specification
43+
44+
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) defines a duration as either:
45+
46+
- `PnYnMnDTnHnMnS`
47+
- `PnW`
48+
49+
Instead, the specification `PDTnHnMn.nS` is used, with the further amendments:
50+
51+
- Year/Month/Week components are not supported.
52+
- Days are considered to be always 24 hours.
53+
- The entire string may be prefixed with a `-` to signify a negative duration.
54+
- Each component may be prefixed with a `-` to signify a negative component.
55+
- The seconds component (and only the seconds component) may have a fractional
56+
component of up to 9 digits.
57+
- Overflowing of components above their maximum (e.g. 60 for a minute) is
58+
allowed. For example, `PT90M` is valid and equivalent to `PT1H30M`.
59+
60+
## Positive examples
61+
62+
| String | Explanation |
63+
| ---------------- | -------------------------------------------------------- |
64+
| `PT2M` | A duration representing 2 minutes. |
65+
| `PT120S` | A duration representing 120 seconds (2 minutes). |
66+
| `PT0.000000001S` | A duration representing 1 nanosecond. |
67+
| `-P1D` | A duration representing 1 negative day. |
68+
| `P1D-2H` | A duration representing two hours fewer than a full day. |
69+
70+
## Negative examples
71+
72+
| String | Explanation |
73+
| ----------------- | --------------------------------------------------------------- |
74+
| `P1Y` | Calendar years are not supported. |
75+
| `P1M` | Calendar months are not supported. |
76+
| `P1W` | Calendar weeks are not supported. |
77+
| `P0.5D` | Fractional component is only supported for seconds. |
78+
| `PT0.0000000001S` | Fractional component in seconds only supports at most 9 digits. |
79+
| `PTS` | Digits must precede units. |
80+
81+
# References
82+
83+
- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)

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

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

0 commit comments

Comments
 (0)