From 66fb671e7f09631fb1fea4fbc3545194db2e8e97 Mon Sep 17 00:00:00 2001 From: Jakob Merrild Date: Mon, 16 Dec 2024 11:24:15 +0100 Subject: [PATCH 1/5] 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: https://github.com/graphql/graphql-spec/issues/73 --- scalars/contributed/jakobmerrild/long.md | 79 ++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 scalars/contributed/jakobmerrild/long.md diff --git a/scalars/contributed/jakobmerrild/long.md b/scalars/contributed/jakobmerrild/long.md new file mode 100644 index 0000000..7f8177c --- /dev/null +++ b/scalars/contributed/jakobmerrild/long.md @@ -0,0 +1,79 @@ + + +# Long — GraphQL Custom Scalar + +Author - jakobmerrild + +Date - 2024-12-16 + +**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 64-bit signed integer (non-fractional) value, ranging from `-2^63` to `2^63-1`. Such values are commonly +used to represent timestamps as the number of milliseconds since the UNIX epoch (`1970-01-01T00:00:00.000Z`) +among other use cases. + +# Name + +The scalar should be named `Long` to match commonly used names for the same data structure in a variety of programming languages. +Alternatively the scalar can be named `Int64` to represent the 64-bit encoding. + +# Result JSON spec + +A field of type `Long` should result in a JSON `number` without a fractional or exponential part. A leading `-` should only be +added if the field represents a negative value. + +These are valid examples: + +| Output | Explanation | +| ---------------------- | -------------------------------------------------------------- | +| `0` | Zero is a valid integer within the range | +| `-9223372036854775808` | This is the lowest value that can be represented in the range | +| `9223372036854775807` | This is the largest value that can be represented in the range | + +These are invalid examples: + +| Output | Explanation | +| ----------------------- | ------------------------------------------------------------------------ | +| `+1234` | Leading `+` is not allowed | +| `-10223372036854775808` | Value is lower than `-2^63` | +| `12223372036854775807` | Value is greater than `2^63-1` | +| `123.0` | Fractional part is not allowed even if it is zero | +| `1e6` | Exponential notation is not allowed, even if it represents a valid value | +| `"12345"` | String representations of a valid value are not allowed | + +# Literal Input spec + +For input both IntValue and StringValue shall be accepted so long as the StringValue is a base-10 representation of a +valid value within the range. + +These are valid examples: + +| Input | Explanation | +| ---------------------- | ------------------------------------------------------------------------- | +| `0` | IntValue within range | +| `-9223372036854775808` | This is the lowest value that can be represented in the range | +| `9223372036854775807` | This is the largest value that can be represented in the range | +| `"987654321"` | A StringValue containing a base-10 representation of the value is allowed | + +These are invalid examples: + +| Output | Explanation | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `-10223372036854775808` | Value is lower than `-2^63` | +| `12223372036854775807` | Value is greater than `2^63-1` | +| `123.0` | FloatValue is not allowed | +| `"FFFFF"` | A StringValue containing a base-16 representation of a valid value is not allowed | +| `"6543.000"` | A StringValue containing a base-10 representation with a fractional part is not allowed. Even if the fractional part is zero | + +# Raw Input JSON spec + +For raw input the same rules apply as for Literal inputs. + +# References + +- [Support of `Long` (64-bit integer) scalar](https://github.com/graphql/graphql-spec/issues/73) From 086bfff99e38d0003679b31bfc4d911f1c5c7794 Mon Sep 17 00:00:00 2001 From: Jakob Merrild Date: Sun, 30 Nov 2025 14:23:48 +0100 Subject: [PATCH 2/5] Update scalars/contributed/jakobmerrild/long.md Co-authored-by: Martin Bonnin --- scalars/contributed/jakobmerrild/long.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scalars/contributed/jakobmerrild/long.md b/scalars/contributed/jakobmerrild/long.md index 7f8177c..9b6eafe 100644 --- a/scalars/contributed/jakobmerrild/long.md +++ b/scalars/contributed/jakobmerrild/long.md @@ -13,9 +13,7 @@ Copyright © GraphQL contributors. This specification is licensed under # Overview -This Scalar represents a 64-bit signed integer (non-fractional) value, ranging from `-2^63` to `2^63-1`. Such values are commonly -used to represent timestamps as the number of milliseconds since the UNIX epoch (`1970-01-01T00:00:00.000Z`) -among other use cases. +This scalar represents a 64-bit signed integer (non-fractional) value, ranging from `-2^63` to `2^63-1`. ``` # Name From efeab845a4f581f1cba8826bd287313b15178f02 Mon Sep 17 00:00:00 2001 From: Jakob Merrild Date: Sun, 30 Nov 2025 14:25:15 +0100 Subject: [PATCH 3/5] Update scalars/contributed/jakobmerrild/long.md Co-authored-by: Martin Bonnin --- scalars/contributed/jakobmerrild/long.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scalars/contributed/jakobmerrild/long.md b/scalars/contributed/jakobmerrild/long.md index 9b6eafe..3f0c8b5 100644 --- a/scalars/contributed/jakobmerrild/long.md +++ b/scalars/contributed/jakobmerrild/long.md @@ -20,7 +20,7 @@ This scalar represents a 64-bit signed integer (non-fractional) value, ranging f The scalar should be named `Long` to match commonly used names for the same data structure in a variety of programming languages. Alternatively the scalar can be named `Int64` to represent the 64-bit encoding. -# Result JSON spec +# Result coercion A field of type `Long` should result in a JSON `number` without a fractional or exponential part. A leading `-` should only be added if the field represents a negative value. From e20ed45ed039d875046b672e8d9565b341cd2ac3 Mon Sep 17 00:00:00 2001 From: Jakob Merrild Date: Tue, 2 Dec 2025 11:13:01 +0100 Subject: [PATCH 4/5] Update wording of Long spec This makes the wording more consistent and removes all references to JSON. --- scalars/contributed/jakobmerrild/long.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/scalars/contributed/jakobmerrild/long.md b/scalars/contributed/jakobmerrild/long.md index 3f0c8b5..5d2b3dc 100644 --- a/scalars/contributed/jakobmerrild/long.md +++ b/scalars/contributed/jakobmerrild/long.md @@ -22,7 +22,7 @@ Alternatively the scalar can be named `Int64` to represent the 64-bit encoding. # Result coercion -A field of type `Long` should result in a JSON `number` without a fractional or exponential part. A leading `-` should only be +A field of type `Long` should result in a `number` without a fractional or exponential part. A leading `-` should only be added if the field represents a negative value. These are valid examples: @@ -44,9 +44,9 @@ These are invalid examples: | `1e6` | Exponential notation is not allowed, even if it represents a valid value | | `"12345"` | String representations of a valid value are not allowed | -# Literal Input spec +# Input coercion -For input both IntValue and StringValue shall be accepted so long as the StringValue is a base-10 representation of a +For input both `number` and `string` shall be accepted so long as the `string` is a base-10 representation of a valid value within the range. These are valid examples: @@ -68,10 +68,3 @@ These are invalid examples: | `"FFFFF"` | A StringValue containing a base-16 representation of a valid value is not allowed | | `"6543.000"` | A StringValue containing a base-10 representation with a fractional part is not allowed. Even if the fractional part is zero | -# Raw Input JSON spec - -For raw input the same rules apply as for Literal inputs. - -# References - -- [Support of `Long` (64-bit integer) scalar](https://github.com/graphql/graphql-spec/issues/73) From 28ba68657a58002293c445db8bb3de19db765e37 Mon Sep 17 00:00:00 2001 From: Jakob Merrild Date: Tue, 2 Dec 2025 13:05:21 +0100 Subject: [PATCH 5/5] 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: https://github.com/graphql/graphql-scalars/pull/40 --- scalars/contributed/jakobmerrild/long.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/scalars/contributed/jakobmerrild/long.md b/scalars/contributed/jakobmerrild/long.md index 5d2b3dc..ffb4aa5 100644 --- a/scalars/contributed/jakobmerrild/long.md +++ b/scalars/contributed/jakobmerrild/long.md @@ -46,8 +46,7 @@ These are invalid examples: # Input coercion -For input both `number` and `string` shall be accepted so long as the `string` is a base-10 representation of a -valid value within the range. +For input `number` values shall be accepted so long as they fall within the range represented by the spec. These are valid examples: @@ -56,7 +55,6 @@ These are valid examples: | `0` | IntValue within range | | `-9223372036854775808` | This is the lowest value that can be represented in the range | | `9223372036854775807` | This is the largest value that can be represented in the range | -| `"987654321"` | A StringValue containing a base-10 representation of the value is allowed | These are invalid examples: @@ -67,4 +65,5 @@ These are invalid examples: | `123.0` | FloatValue is not allowed | | `"FFFFF"` | A StringValue containing a base-16 representation of a valid value is not allowed | | `"6543.000"` | A StringValue containing a base-10 representation with a fractional part is not allowed. Even if the fractional part is zero | +| `"987654321"` | A StringValue containing a base-10 representation of the value is not allowed |