Scalar types in AWS AppSync

A GraphQL object type has a name and fields, and those fields can have sub-fields. Ultimately, an object type's fields must resolve to scalar types, which represent the leaves of the query. For more information about object types and scalars, see Schemas and Types on the GraphQL website.

In addition to a default set of GraphQL scalars, AWS AppSync includes a set of reserved scalars that start with an AWS prefix. AWS AppSync does not support custom scalars.

Note

You cannot use AWS as a prefix for custom object types.

GraphQL defines the following default scalars:

ID

A unique identifier for an object. This scalar is serialized like a String but isn't meant to be human-readable.

String

A UTF-8 character sequence.

Int

An integer value between -(2³¹) and 2³²-1.

Float

An IEEE 754 floating point value.

Boolean

A Boolean value, either true or false.

AWS AppSync defines the following scalars:

AWSDate

An extended ISO 8601 date string in the format YYYY-MM-DD.

AWSTime

An extended ISO 8601 time string in the format hh:mm:ss.sss.

AWSDateTime

An extended ISO 8601 date and time string in the format YYYY-MM-DDThh:mm:ss.sssZ.

Note

The AWSDate, AWSTime, and AWSDateTime scalars can optionally include a time zone offset. For example, the values 1970-01-01Z, 1970-01-01-07:00, and 1970-01-01+05:30 are all valid for AWSDate. The time zone offset must be either Z (UTC) or an offset in hours and minutes (and, optionally, seconds). For example, ±hh:mm:ss. The seconds field in the time zone offset is considered valid even though it's not part of the ISO 8601 standard.

AWSTimestamp

An integer value representing the number of seconds before or after 1970-01-01-T00:00Z.

AWSEmail

An email address in the format local-part@domain-part as defined by RFC 822.

AWSJSON

A JSON string. Any valid JSON construct is automatically parsed and loaded in the resolver mapping templates as maps, lists, or scalar values rather than as the literal input strings. Unquoted strings or otherwise invalid JSON result in a GraphQL validation error.

AWSPhone

A phone number. This value is stored as a string. Phone numbers can contain either spaces or hyphens to separate digit groups. Phone numbers without a country code are assumed to be US/North American numbers adhering to the North American Numbering Plan (NANP).

AWSURL

A URL as defined by RFC 1738. For example, https://www.amazon.com/dp/B000NZW3KC/ or mailto:[e-mail]. URLs must contain a schema (http, mailto) and can't contain two forward slashes (//) in the path part.

AWSIPAddress

A valid IPv4 or IPv6 address. IPv4 addresses are expected in quad-dotted notation (123.12.34.56). IPv6 addresses are expected in non-bracketed, colon-separated format (1a2b:3c4b::1234:4567). You can include an optional CIDR suffix (123.45.67.89/16) to indicate subnet mask.

Schema usage example

If you're unfamiliar with creating GraphQL APIs in AWS AppSync, or with connecting resolvers with mapping templates, we recommend first reviewing Designing a GraphQL API and Resolver tutorials.

The following example GraphQL schema uses all of the custom scalars as an "object" and shows the resolver request and response templates for basic put, get, and list operations. Finally, the example shows how you can use this when running 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 is:

$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 is:

$util.toJson($ctx.result)

Use the following request template for listObjects:

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

The response template for listObjects is:

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

The following are some examples of using this schema with GraphQL queries:

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:"https://amazon.com"
        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
    }
}