1Goals

This specification defines the custom scalar type Long that is useful for dealing with integers larger than those handled by Int.

Note: All mentions of Long are referring to the scalar type defined by this specification. All mentions of Long are referring to user declared scalar name.

2Definition

• Long is a 64-bit signed Integer.
• Long supports numbers from -9223372036854775808 to 9223372036854775807 inclusive by default. More details about range configuration is provided in Customizing the Long Type.
• A scalar type with any name can be marked as Long using the built in @specifiedBy directive. The URL to mark the type as Long in the @specifiedBy directive is https://ibm.github.io/graphql-specs/custom-scalars/long.html.
• In the absence of the @specifiedBy directive, an implementation may treat a scalar type as Long if the name of the type is Long.
• If the @specifiedBy directive is present, an implementation can only treat a scalar type as Long if the @specifiedBy directive provides the URL of the specification of Long.

3Example of the Long Type

The following example uses Long:

Example № 1scalar LargeNumber @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/long.html")
scalar Long
scalar UnknownScalar

type Asguardian {
  name: String
  age: LargeNumber
}

type Query {
  asguardians(max: Long = 4000000000000): [Asguardian]
}

In the example above, the following points should be noted:

• Scalar LargeNumber is considered to be Long because we used the URL for the Long specification in the @specifiedBy directive.
• Despite the absence of a URL, Long may be recognized as a Long because the name of the scalar type is Long and there is no @specifiedBy directive to mark it otherwise.
• UnknownScalar is not considered to be Long as none of the preceding two conditions are satisfied.
• The max argument used in Query.asguardians has a default value larger than the upper bound of a 32-bit signed Integer.
• Asguardian.age is of type LargeNumber because we expect large numbers to be returned by the resolver function for this field.

This is a simple example query that matches the schema:

Example № 2Query example {
  asguardians(max: 3000000000000) {
    name
    age
  }
}

4Customizing the Long Type

The lower and upper bounds of Long can be changed via the @scalarParam directive as defined here. The parameters used in the @scalarParam directive to specify the bounds are:

• min, a string representation of a Long value used to specify the lower bound (default is "-9223372036854775808").
• max, a string representation of a Long value used to specify the upper bound (default is "9223372036854775807").

The following conditions apply to range modification:

• min, after coercion to a Long, must not be lower than the default lower bound.
• max, after coercion to a Long, must not be greater than the default upper bound.
• min must not be greater than max, after both are coerced to Long values.

5Example of Long Type Customization

The following example demonstrates how to modify the range of Long using the @scalarParam directive:

Example № 3directive @scalarParam (name: String!, value: String!) repeatable on SCALAR
scalar LargeNumber @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/long.html")
@scalarParam (name: "min", value: "0")
@scalarParam (name: "max", value: "5000000000000")
scalar Long @scalarParam (name: "max", value: "4000000000000")

type Asguardian {
  name: String
  age: LargeNumber
}

type Query {
  asguardians(max: Long = 4000000000000): [Asguardian] @listSize(slicingArguments: ["max"])
}

In this example, please note:

• LargeNumber is a Long that will only support numbers from 0 through 5000000000000, inclusive.
• Long is a Long that will only support numbers from -9223372036854775808 (the default) through 4000000000000, inclusive.

6Result Coercion

Fields returning the type Long expect to encounter 64-bit integer internal values.

All integer values must coerce to the equivalent Long value.

GraphQL services may coerce non-integer internal values to Long when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning 1 for the floating-point number 1.0, or returning 123 for the string "123". In scenarios where coercion may lose data, a field error should be raised. For example, the floating-point number 1.2 should raise a field error instead of being truncated to the Long value 1.

If the integer internal value represents a value less than -9223372036854775808 or greater than 9223372036854775807, a field error should be raised.

7Input Coercion

As an input type, only valid integers within the range of Long are accepted. All values that are not valid Long, including numeric strings, must raise a request error indicating an incorrect type.