From 20a0f64086243686e3d89385730a4b0d7294a77f Mon Sep 17 00:00:00 2001 From: Alexandre Carlton Date: Sun, 17 Mar 2024 01:03:53 +1100 Subject: [PATCH] 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 https://github.com/graphql-java/graphql-java-extended-scalars/pull/132 for the implementation in `graphql-java`. --- .../AlexandreCarlton/accurate-duration.md | 83 +++++++++++++++++++ .../AlexandreCarlton/nominal-duration.md | 76 +++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 scalars/contributed/AlexandreCarlton/accurate-duration.md create mode 100644 scalars/contributed/AlexandreCarlton/nominal-duration.md diff --git a/scalars/contributed/AlexandreCarlton/accurate-duration.md b/scalars/contributed/AlexandreCarlton/accurate-duration.md new file mode 100644 index 0000000..5f0974b --- /dev/null +++ b/scalars/contributed/AlexandreCarlton/accurate-duration.md @@ -0,0 +1,83 @@ + + +# AccurateDuration — GraphQL Custom Scalar + +Author - AlexandreCarlton + +Date - 2024-03-17 + +**License and Copyright** + +Copyright © GraphQL contributors. This specification is licensed under +[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0). + +# Overview + +This Scalar represents an exact length in time. It is a refinement of the +duration as defined by [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) with +the caveat that it does not support calendar components that would otherwise +require the knowledge of a date to determine a precise value. As such, the +following components are excluded: + +- calendar year (as this can be potentially a leap year). +- calendar month as this may contain a variable number of days). +- 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)). +- calendar week (as this is seven calendar days). + +Days (unlike calendar days) are supported under the definition of +[ISO 31-1](https://en.wikipedia.org/wiki/ISO_31-1): 24 hours. + +Negative durations per [ISO 8601-2](https://en.wikipedia.org/wiki/ISO_8601) are +supported. + +# Name + +`AccurateDuration`, originating from the wording in +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601): + +
Duration can be expressed by a combination of components with accurate duration (hour, minute and second) +and components with nominal duration (year, month, week and day).
+ +# Input/Result specification + +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) defines a duration as either: + +- `PnYnMnDTnHnMnS` +- `PnW` + +Instead, the specification `PDTnHnMn.nS` is used, with the further amendments: + +- Year/Month/Week components are not supported. +- Days are considered to be always 24 hours. +- The entire string may be prefixed with a `-` to signify a negative duration. +- Each component may be prefixed with a `-` to signify a negative component. +- The seconds component (and only the seconds component) may have a fractional + component of up to 9 digits. +- Overflowing of components above their maximum (e.g. 60 for a minute) is + allowed. For example, `PT90M` is valid and equivalent to `PT1H30M`. + +## Positive examples + +| String | Explanation | +| ---------------- | -------------------------------------------------------- | +| `PT2M` | A duration representing 2 minutes. | +| `PT120S` | A duration representing 120 seconds (2 minutes). | +| `PT0.000000001S` | A duration representing 1 nanosecond. | +| `-P1D` | A duration representing 1 negative day. | +| `P1D-2H` | A duration representing two hours fewer than a full day. | + +## Negative examples + +| String | Explanation | +| ----------------- | --------------------------------------------------------------- | +| `P1Y` | Calendar years are not supported. | +| `P1M` | Calendar months are not supported. | +| `P1W` | Calendar weeks are not supported. | +| `P0.5D` | Fractional component is only supported for seconds. | +| `PT0.0000000001S` | Fractional component in seconds only supports at most 9 digits. | +| `PTS` | Digits must precede units. | + +# References + +- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) diff --git a/scalars/contributed/AlexandreCarlton/nominal-duration.md b/scalars/contributed/AlexandreCarlton/nominal-duration.md new file mode 100644 index 0000000..7d4f961 --- /dev/null +++ b/scalars/contributed/AlexandreCarlton/nominal-duration.md @@ -0,0 +1,76 @@ + + +# AccurateDuration — GraphQL Custom Scalar + +Author - AlexandreCarlton + +Date - 2024-03-17 + +**License and Copyright** + +Copyright © GraphQL contributors. This specification is licensed under +[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0). + +# Overview + +This Scalar represents a length in time in years, months, weeks or days. It is a +refinement of the duration as defined by +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) with the caveat that it only +supports calendar components that require the knowledge of the particular +calendar position with which the duration is being evaluated. As such, only the +following components are included: + +- calendar year (as this can be potentially a leap year). +- calendar month as this may contain a variable number of days). +- 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)). +- calendar week (as this is seven calendar days). + +Negative durations per [ISO 8601-2](https://en.wikipedia.org/wiki/ISO_8601) are +supported. + +# Name + +`NominalDuration`, originating from the wording in +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601): + +
Duration can be expressed by a combination of components with accurate duration (hour, minute and second) +and components with nominal duration (year, month, week and day).
+ +# Input/Result specification + +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) defines a duration as either: + +- `PnYnMnDTnHnMnS` +- `PnW` + +Instead, the specification `PnYnMnWnD` is used, with the further amendments: + +- The entire string may be prefixed with a `-` to signify a negative duration. +- Each component may be prefixed with a `-` to signify a negative component. +- A calendar week may be declared alongside calendar year/month/day components. + +## Positive examples + +| String | Explanation | +| -------- | ------------------------------------------------------------------------- | +| `P1Y` | A duration representing a calendar year. | +| `P2W` | A duration representing two calendar weeks. | +| `-P1Y2M` | A negative duration representing a calendar year and calendar month. | +| `P1Y-2M` | A duration representing a two calendar months fewer than a calendar year. | +| `P2M3W` | A duration representing a two calendar months and three calendar weeks. | +| `P24M` | A duration representing a twenty four calendar months. | + +## Negative examples + +| String | Explanation | +| ------- | ---------------------------------------- | +| `PT1H` | Hours are not supported. | +| `PT1M` | Minutes are not supported. | +| `PT1S` | Seconds are not supported. | +| `P1.5Y` | Fractional components are not supported. | +| `PY` | Digits must precede units. | + +# References + +- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)