Skip to content

Commit 4292a5b

Browse files
martinbonninglen-84
martinbonnin
and
glen-84
authored
Add scalar specifications for Long, LocalDateTime, LocalDate, YearMonth, LocalTime, Instant (#41)
* Add long, localdatetime, and void * Fix cspell * Update localdatetime-v0.1.md * Update scalars/contributed/apollographql/localdatetime-v0.1.md Co-authored-by: Glen <glen.84@gmail.com> * Add missing 'it' * Update scalars/contributed/apollographql/instant-v0.1.md Co-authored-by: Glen <glen.84@gmail.com> * better wording * format * Update scalars/contributed/apollographql/long-v0.1.md Co-authored-by: Glen <glen.84@gmail.com> --------- Co-authored-by: Glen <glen.84@gmail.com>
1 parent 9846731 commit 4292a5b

File tree

7 files changed

+499
-0
lines changed

7 files changed

+499
-0
lines changed

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,8 @@
2727
"prettier": {
2828
"proseWrap": "always",
2929
"trailingComma": "none"
30+
},
31+
"cspell": {
32+
"words": ["secfrac", "apollographql", "fullyear", "mday", "numoffset"]
3033
}
3134
}

‎scalars/contributed/apollographql/instant-v0.1.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Instant — GraphQL Custom Scalar
2+
3+
Author - apollographql
4+
5+
Date - 2025-12-04
6+
7+
**License and Copyright**
8+
9+
Copyright © GraphQL contributors. This specification is licensed under
10+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
11+
12+
# Overview
13+
14+
This scalar represents a specific instant in time in a way that is independent
15+
of a time zone. For example, "1970-01-01T00:00:00" does not represent a moment
16+
in time since this would happen at different times in different time zones:
17+
someone in Tokyo would think it is already 1970-01-01 several hours earlier than
18+
someone in Berlin would. To represent such entities, use the LocalDateTime. In
19+
contrast, "1970-01-01T00:00:00+00:00" can be represented as an Instant.
20+
21+
Using [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6)
22+
format, a `Instant` is represented as `date-time`:
23+
24+
```
25+
date-fullyear = 4DIGIT
26+
date-month = 2DIGIT ; 01-12
27+
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
28+
; month/year
29+
time-hour = 2DIGIT ; 00-23
30+
time-minute = 2DIGIT ; 00-59
31+
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second
32+
; rules
33+
time-secfrac = "." 1*DIGIT
34+
time-numoffset = ("+" / "-") time-hour ":" time-minute
35+
time-offset = "Z" / time-numoffset
36+
37+
partial-time = time-hour ":" time-minute ":" time-second
38+
[time-secfrac]
39+
full-date = date-fullyear "-" date-month "-" date-mday
40+
full-time = partial-time time-offset
41+
42+
date-time = full-date "T" full-time
43+
```
44+
45+
Usage of the uppercase "T" character is recommended, but lowercase "t" is also
46+
valid, in accordance with RFC 3339.
47+
48+
**Fractional second precision:**
49+
50+
RFC 3339 allows representing fractional seconds with arbitrary precision, which
51+
is impractical in most programming languages.
52+
53+
For convenience, this specification enforces nanosecond precision with at most
54+
nine digits.
55+
56+
# Recommended Name
57+
58+
The recommended name is `Instant`.
59+
60+
# GraphQL input coercion
61+
62+
The input must be a
63+
[GraphQL StringValue](https://spec.graphql.org/September2025/#StringValue)
64+
matching the description above.
65+
66+
All other values must raise an error.
67+
68+
# JSON input coercion
69+
70+
The input must be a [JSON string](https://www.json.org/json-en.html) matching
71+
the description above.
72+
73+
All other values must raise an error.
74+
75+
# JSON result coercion
76+
77+
The result must be a [JSON string](https://www.json.org/json-en.html) matching
78+
the description above.
79+
80+
# Examples
81+
82+
Because GraphQL StringValue and JSON string are so similar, the first column in
83+
the table below may be understood as either a GraphQL StringValue or a JSON
84+
string.
85+
86+
| Value | Description |
87+
| ------------------------------- | ------------------------------------------ |
88+
| `1983-10-20T23:59:59+00:00` | A valid instant. |
89+
| `1983-10-20T23:59:59Z` | The zero offset may be represented as "Z". |
90+
| `1983-10-20T23:59:59z` | Lowercase "z" may be used. |
91+
| `1983-10-20t23:59:59Z` | Lowercase "t" may be used. |
92+
| `1983-10-20T23:59:59.123+02:00` | An instant with a fractional second. |
93+
94+
These are invalid examples:
95+
96+
| Value | Why is it invalid |
97+
| ------------------------------ | -------------------------------------- |
98+
| `1983-10-20T23:59:59` | Missing offset. |
99+
| `1983-10-20T23:59:59+00:00:00` | Offset may not include seconds. |
100+
| `1983-10-20T23:59:59 00:00` | Offset must contain a "+" or "-" sign. |

‎scalars/contributed/apollographql/localdate-v0.1.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# LocalDate — GraphQL Custom Scalar
2+
3+
Author - apollographql
4+
5+
Date - 2025-12-04
6+
7+
**License and Copyright**
8+
9+
Copyright © GraphQL contributors. This specification is licensed under
10+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
11+
12+
# Overview
13+
14+
This scalar represents a local date, without any reference to a time zone.
15+
16+
Using [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6)
17+
format, a `LocalDate` is represented as `full-date`:
18+
19+
```
20+
date-fullyear = 4DIGIT ; 0000-9999
21+
date-month = 2DIGIT ; 01-12
22+
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
23+
; month/year
24+
25+
full-date = date-fullyear "-" date-month "-" date-mday
26+
```
27+
28+
# Recommended Name
29+
30+
The recommended name is `LocalDate`.
31+
32+
# GraphQL input coercion
33+
34+
The input must be a
35+
[GraphQL StringValue](https://spec.graphql.org/September2025/#StringValue)
36+
matching the description above.
37+
38+
All other values must raise an error.
39+
40+
# JSON input coercion
41+
42+
The input must be a [JSON string](https://www.json.org/json-en.html) matching
43+
the description above.
44+
45+
All other values must raise an error.
46+
47+
# JSON result coercion
48+
49+
The result must be a [JSON string](https://www.json.org/json-en.html) matching
50+
the description above.
51+
52+
# Examples
53+
54+
Because GraphQL StringValue and JSON string are so similar, the first column in
55+
the table below may be understood as either a GraphQL StringValue or a JSON
56+
string.
57+
58+
| Value | Description |
59+
| ------------ | ------------- |
60+
| `1983-10-20` | A valid date. |
61+
62+
These are invalid examples:
63+
64+
| Value | Why is it invalid |
65+
| --------------------- | --------------------------------------- |
66+
| `1983-01-20T23:59:59` | Time is not allowed. |
67+
| `1983-00-20` | 00 is not a valid month. |
68+
| `1983-01-32` | 32 is not a valid day. |
69+
| `10000-10-20` | More than 4 digits for `date-fullyear`. |
70+
| `52-10-20` | Less than 4 digits for `date-fullyear`. |

‎scalars/contributed/apollographql/localdatetime-v0.1.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# LocalDateTime — GraphQL Custom Scalar
2+
3+
Author - apollographql
4+
5+
Date - 2025-12-04
6+
7+
**License and Copyright**
8+
9+
Copyright © GraphQL contributors. This specification is licensed under
10+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
11+
12+
# Overview
13+
14+
This scalar represents a local date and time, without any reference to a time
15+
zone.
16+
17+
Using [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6)
18+
format, a `LocalDateTime` is represented as `full-date "T" partial-time`:
19+
20+
```
21+
date-fullyear = 4DIGIT ; 0000-9999
22+
date-month = 2DIGIT ; 01-12
23+
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
24+
; month/year
25+
time-hour = 2DIGIT ; 00-23
26+
time-minute = 2DIGIT ; 00-59
27+
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second
28+
; rules
29+
time-secfrac = "." 1*9DIGIT
30+
31+
partial-time = time-hour ":" time-minute ":" time-second
32+
[time-secfrac]
33+
full-date = date-fullyear "-" date-month "-" date-mday
34+
35+
local-date-time = full-date "T" partial-time
36+
```
37+
38+
Usage of the uppercase "T" character is recommended, but lowercase "t" is also
39+
valid, in accordance with RFC 3339.
40+
41+
**Fractional second precision:**
42+
43+
RFC 3339 allows representing fractional seconds with arbitrary precision, which
44+
is impractical in most programming languages.
45+
46+
For convenience, this specification enforces nanosecond precision with at most
47+
nine digits.
48+
49+
Note: JavaScript `Date` only has millisecond precision. Use `LocalDateTime` with
50+
care if you are using it in applications that require precise times.
51+
52+
# Recommended Name
53+
54+
The recommended name is `LocalDateTime`.
55+
56+
# GraphQL input coercion
57+
58+
The input must be a
59+
[GraphQL StringValue](https://spec.graphql.org/September2025/#StringValue)
60+
matching the description above.
61+
62+
All other values must raise an error.
63+
64+
# JSON input coercion
65+
66+
The input must be a [JSON string](https://www.json.org/json-en.html) matching
67+
the description above.
68+
69+
All other values must raise an error.
70+
71+
# JSON result coercion
72+
73+
The result must be a [JSON string](https://www.json.org/json-en.html) matching
74+
the description above.
75+
76+
# Examples
77+
78+
Because GraphQL StringValue and JSON string are so similar, the first column in
79+
the table below may be understood as either a GraphQL StringValue or a JSON
80+
string.
81+
82+
| Value | Description |
83+
| ------------------------------- | -------------------------------- |
84+
| `1983-10-20T23:59:59` | A valid date. |
85+
| `1983-10-20t23:59:59` | Lowercase "t" may be used. |
86+
| `1983-10-20T23:59:59.123` | A date with a fractional second. |
87+
| `1983-10-20T23:59:59.123000` | Trailing zeroes are valid. |
88+
| `1983-10-20T23:59:59.123456789` | Nanosecond precision. |
89+
90+
These are invalid examples:
91+
92+
| Value | Why is it invalid |
93+
| ---------------------------------- | --------------------------------------- |
94+
| `1983-10-20 23:59:59` | Missing "T" separator. |
95+
| `1983-00-20T23:59:59` | 00 is not a valid month. |
96+
| `1983-01-32T23:59:59` | 32 is not a valid day. |
97+
| `1983-01-32T23:59:59.123456789123` | Seconds exceed nanosecond precision. |
98+
| `2018-04-01T15:20:15-07:00` | Time offsets are not allowed. |
99+
| `10000-10-20 23:59:59` | More than 4 digits for `date-fullyear`. |
100+
| `52-10-20 23:59:59` | Less than 4 digits for `date-fullyear`. |

‎scalars/contributed/apollographql/localtime-v0.1.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# LocalTime — GraphQL Custom Scalar
2+
3+
Author - apollographql
4+
5+
Date - 2025-12-04
6+
7+
**License and Copyright**
8+
9+
Copyright © GraphQL contributors. This specification is licensed under
10+
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).
11+
12+
# Overview
13+
14+
This scalar represents a local date and time, without any reference to a time
15+
zone.
16+
17+
Using [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6)
18+
format, a `LocalTime` is represented as `partial-time`:
19+
20+
```
21+
time-hour = 2DIGIT ; 00-23
22+
time-minute = 2DIGIT ; 00-59
23+
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second
24+
; rules
25+
time-secfrac = "." 1*9DIGIT
26+
27+
partial-time = time-hour ":" time-minute ":" time-second
28+
[time-secfrac]
29+
```
30+
31+
**Fractional second precision:**
32+
33+
RFC 3339 allows representing fractional seconds with arbitrary precision, which
34+
is impractical in most programming languages.
35+
36+
For convenience, this specification enforces nanosecond precision with at most
37+
nine digits.
38+
39+
Note: JavaScript `Date` only has millisecond precision. Use `LocalTime` with
40+
care if you are using it in applications that require precise times.
41+
42+
# Recommended Name
43+
44+
The recommended name is `LocalTime`.
45+
46+
# GraphQL input coercion
47+
48+
The input must be a
49+
[GraphQL StringValue](https://spec.graphql.org/September2025/#StringValue)
50+
matching the description above.
51+
52+
All other values must raise an error.
53+
54+
# JSON input coercion
55+
56+
The input must be a [JSON string](https://www.json.org/json-en.html) matching
57+
the description above.
58+
59+
All other values must raise an error.
60+
61+
# JSON result coercion
62+
63+
The result must be a [JSON string](https://www.json.org/json-en.html) matching
64+
the description above.
65+
66+
# Examples
67+
68+
Because GraphQL StringValue and JSON string are so similar, the first column in
69+
the table below may be understood as either a GraphQL StringValue or a JSON
70+
string.
71+
72+
| Value | Description |
73+
| -------------------- | -------------------------------- |
74+
| `23:59:59` | A valid time. |
75+
| `23:59:59.123` | A time with a fractional second. |
76+
| `23:59:59.123000` | Trailing zeroes are valid. |
77+
| `23:59:59.123456789` | Nanosecond precision. |
78+
79+
These are invalid examples:
80+
81+
| Value | Why is it invalid |
82+
| ----------------------- | ------------------------------------- |
83+
| `24:59:59` | `24` is not a valid `time-hour`. |
84+
| `23:60:59` | `60` is not a valid `time-minute`. |
85+
| `23:59:61` | `61` is not a valid `time-second`. |
86+
| `23:59:59.123456789123` | Seconds exceed nanosecond precision. |
87+
| `23:59:59.1234567890` | More than nine digits for `sec-frac`. |
88+
| `15:20:15-07:00` | Time offsets are not allowed. |

0 commit comments

Comments
 (0)