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
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.
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 -(231) and 232-1.
Float
-
An IEEE 754 floating point value.
Boolean
-
A Boolean value, either
true
orfalse
.
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
.
The AWSDate
, AWSTime
, and AWSDateTime
scalars can
optionally include a time zone
offset1970-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/
ormailto:example@example.com
. 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: "example@example.com" 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: "+1 555 764 4377" 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 } }