Skip to content

Commit 040b3e9

Browse files
Add spec for Long custom scalar type (#26)
* Add spec for `Long` custom scalar type The `Long` data type is commonly used in many applications because the largest value that can be held in an `Int` value is `2^31-1`. See: graphql/graphql-spec#73 * Update scalars/contributed/jakobmerrild/long.md Co-authored-by: Martin Bonnin <martin@mbonnin.net> * Update scalars/contributed/jakobmerrild/long.md Co-authored-by: Martin Bonnin <martin@mbonnin.net> * Update wording of Long spec This makes the wording more consistent and removes all references to JSON. * Update Long spec to not allow strings for input There's a separate suggestion to update the guide lines to not mention being liberal in what is accepted for inputs. See: #40 * Rewrite Long spec in terms of String encoding Ultimately, not every language can easily parse arbitrarily large JSON numbers. As such we are better off using a string serialization scheme which then allows the adaptors to use whichever methods they see fit to turn the string into a different representation after coercion, e.g. Long or BigInt * Update date of spec The recent changes represent a significant departure from the original spec, so we update the date :) * Fix formatting and spelling --------- Co-authored-by: Martin Bonnin <martin@mbonnin.net>
1 parent 8b3cead commit 040b3e9

File tree

1 file changed

+72
-0
lines changed
  • scalars/contributed/jakobmerrild

1 file changed

+72
-0
lines changed
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
<!-- cspell:ignore jakobmerrild -->
2+
3+
# Long — GraphQL Custom Scalar
4+
5+
Author - jakobmerrild
6+
7+
Date - 2025-12-18
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 64-bit signed integer (non-fractional) value, ranging
17+
from `-2^63` to `2^63-1`.
18+
19+
# Name
20+
21+
The scalar should be named `Long` to match commonly used names for the same data
22+
structure in a variety of programming languages. Alternatively the scalar can be
23+
named `Int64` to represent the 64-bit encoding.
24+
25+
# Result spec
26+
27+
A field of type `Long` should result in a `string` value representing a base-10
28+
encoding of the underlying value without a fractional or exponential part. A
29+
leading `-` should only be added if the field represents a negative value.
30+
31+
These are valid examples:
32+
33+
| Output | Explanation |
34+
| ------------------------ | -------------------------------------------------------------- |
35+
| `"0"` | Zero is a valid integer within the range |
36+
| `"-9223372036854775808"` | This is the lowest value that can be represented in the range |
37+
| `"9223372036854775807"` | This is the largest value that can be represented in the range |
38+
39+
These are invalid examples:
40+
41+
| Output | Explanation |
42+
| ------------------------- | ------------------------------------------------------------------------ |
43+
| `"+1234"` | Leading `+` is not allowed |
44+
| `"-10223372036854775808"` | Value is lower than `-2^63` |
45+
| `"12223372036854775807"` | Value is greater than `2^63-1` |
46+
| `"123.0"` | Fractional part is not allowed even if it is zero |
47+
| `"1e6"` | Exponential notation is not allowed, even if it represents a valid value |
48+
| `12345` | Number representations of a valid value are not allowed |
49+
50+
# Input spec
51+
52+
For input `string` values shall be accepted so long as they fall within the
53+
range represented by the spec.
54+
55+
These are valid examples:
56+
57+
| Input | Explanation |
58+
| ------------------------ | -------------------------------------------------------------- |
59+
| `"0"` | StringValue within range |
60+
| `"-9223372036854775808"` | This is the lowest value that can be represented in the range |
61+
| `"9223372036854775807"` | This is the largest value that can be represented in the range |
62+
63+
These are invalid examples:
64+
65+
| Input | Explanation |
66+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
67+
| `"-10223372036854775808"` | Value is lower than `-2^63` |
68+
| `"12223372036854775807"` | Value is greater than `2^63-1` |
69+
| `"123.0"` | FloatValue is not allowed |
70+
| `"FFFFF"` | A StringValue containing a base-16 representation of a valid value is not allowed |
71+
| `"6543.000"` | A StringValue containing a base-10 representation with a fractional part is not allowed. Even if the fractional part is zero |
72+
| `987654321` | An IntValue containing a base-10 representation of the value is not allowed |

0 commit comments

Comments
 (0)