Scalar types in AWS AppSync

A GraphQL object type has a name and fields, which must resolve to some concrete data. That’s where the scalar types come in: they represent the leaves of the query. AppSync comes with a set of scalar types that can be used right out of the box, including a set of reserved types starting with an AWS prefix.

Note: You cannot use AWS as a prefix for custom types.

GraphQL Scalars

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining a field as an ID signifies that it is not intended to be human‐readable.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Boolean

The Boolean scalar type represents a boolean value of either true or false.

AppSync Defined Scalars

AWSDate

The AWSDate scalar type represents a valid extended ISO 8601 Date string. In other words, this scalar type accepts date strings of the form YYYY-MM-DD. This scalar type can also accept time zone offsets. For example, 1970-01-01Z, 1970-01-01-07:00 and 1970-01-01+05:30 are all valid dates. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.

AWSTime

The AWSTime scalar type represents a valid extended ISO 8601 Time string. In other words, this scalar type accepts time strings of the form hh:mm:ss.sss. The field after the seconds field is a nanoseconds field. It can accept between 1 and 9 digits. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). This scalar type can also accept time zone offsets. For example, 12:30Z, 12:30:24-07:00 and 12:30:24.500+05:30 are all valid time strings. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.

AWSDateTime

The AWSDateTime scalar type represents a valid extended ISO 8601 DateTime string. In other words, this scalar type accepts datetime strings of the form YYYY-MM-DDThh:mm:ss.sssZ. The field after the seconds field is a nanoseconds field. It can accept between 1 and 9 digits. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). The time zone offset is compulsory for this scalar. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.

AWSTimestamp

The AWSTimestamp scalar type represents the number of seconds that have elapsed since 1970-01-01T00:00Z. Timestamps are serialized and deserialized as numbers. Negative values are also accepted and these represent the number of seconds till 1970-01-01T00:00Z.

AWSEmail

The AWSEmail scalar type represents an Email address string that complies with RFC 822. For example, [e-mail] is a valid Email address.

AWSJSON

The AWSJSON scalar type represents a JSON string that complies with RFC 8259.

Maps like {"upvotes": 10}, lists like [1,2,3], and scalar values like "AWSJSON example string", 1, and true are accepted as valid JSON. They will automatically be parsed and loaded in the resolver mapping templates as Maps, Lists, or Scalar values rather than as the literal input strings. Invalid JSON strings like {a: 1}, {‘a’: 1} and Unquoted string will throw GraphQL validation errors.

AWSURL

The AWSURL scalar type represents a valid URL string. The URL may use any scheme and may also be a local URL (for example, <http://localhost/>). URLs without schemes are considered invalid. URLs which contain double slashes are also considered invalid.

AWSPhone

The AWSPhone scalar type represents a valid Phone Number. Phone numbers are serialized and deserialized as Strings. Phone numbers provided may be whitespace delimited or hyphenated. The number can specify a country code at the beginning but this is not required.

AWSIPAddress

The AWSIPAddress scalar type represents a valid IPv4 or IPv6 address string.

Example Schema Usage

If you are unfamiliar with creating GraphQL APIs in AWS AppSync, or connecting resolvers with Mapping Templates, please first review Designing a GraphQL API and Connecting Data Sources and Resolvers before moving forward.

Below we show a sample GraphQL schema which uses all of the custom scalars as an “object” as well as the resolver request and response templates for simple put, get, and list operations. Finally we show how this can be used when executing queries and mutations.

type Mutation {
    putObject(
        email: AWSEmail,
        json: AWSJSON,
        date: AWSDate,
        time: AWSTime,
        datetime: AWSDateTime,
        timestamp: AWSTimestamp,
        url: AWSURL,
        phoneno: AWSPhone,
        ip: AWSIPAddress
    ): Object
}

type Object {
    id: ID!
    email: AWSEmail
    json: AWSJSON
    date: AWSDate
    time: AWSTime
    datetime: AWSDateTime
    timestamp: AWSTimestamp
    url: AWSURL
    phoneno: AWSPhone
    ip: AWSIPAddress
}

type Query {
    getObject(id: ID!): Object
    listObjects: [Object]
}

schema {
    query: Query
    mutation: Mutation
}

Use the following request template for putObject:

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key" : {
        "id": $util.dynamodb.toDynamoDBJson($util.autoId()),
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

The response template for putObject will be:

$util.toJson($ctx.result)

Use the following request template for getObject:

{
    "version": "2017-02-28",
    "operation": "GetItem",
    "key": {
        "id": $util.dynamodb.toDynamoDBJson($ctx.args.id),
    }
}

The response template for getObject will be:

$util.toJson($ctx.result)

Use the following request template for listObjects:

{
    "version" : "2017-02-28",
    "operation" : "Scan",
}

The response template for listObjects will be:

$util.toJson($ctx.result.items)

Some examples of using this schema with GraphQL queries are below:

mutation CreateObject {
    putObject(email: "[e-mail]"
        json: "{\"a\":1, \"b\":3, \"string\": 234}"
        date: "1970-01-01Z"
        time: "12:00:34."
        datetime: "1930-01-01T16:00:00-07:00"
        timestamp: -123123
        url:"http://amazon.co.in"
        phoneno: "[phone]"
        ip: "127.0.0.1/8"
    ) {
        id
        email
        json
        date
        time
        datetime
        url
        timestamp
        phoneno
        ip
    }
}

query getObject {
    getObject(id:"0d97daf0-48e6-4ffc-8d48-0537e8a843d2"){
        email
        url
        timestamp
        phoneno
        ip
    }
}

query listObjects {
    listObjects {
        json
        date
        time
        datetime
    }
}