GraphQL スキーマ仕様: 組み込みのスカラー型とカスタムスカラー型

更新: 2022-09-16 / 作成: 2022-09-16

5 つの組み込みスカラー型 (Scalar types)

GraphQL 仕様で定義されているスカラー型は次の 5 つで、これらを各オブジェクト型のフィールドの型や、フィールド引数の型として使用します。

型名	意味
`Int`	符号付き 32 ビット整数
`Float`	符号付き倍精度浮動小数点数
`String`	文字列（UTF-8 エンコーディング）
`Boolean`	`true` または `false`
`ID`	一意の識別子。データ形式としては `String` と同様ですが、`ID` はリーダブル（意味のある単語）にはなっていないことを示唆します。`ID` は GraphQL サーバーとクライアントの間でオブジェクトの同一性を示すために使用します。

これ以外の型を使用したいときは、独自のオブジェクト型、スカラー型、列挙型を定義して使用します。

カスタムスカラー型 (Custom scalar types)

スカラー型にフォーマット制約を設けたいときや、任意のクラスのインスタンスとして扱いたいときは、独自の カスタムスカラー型 を定義します。例えば、日時や E メールアドレス、UUID、URI などは、カスタムスカラーを使うべき典型的なフィールドの例です。カスタムスカラーは、スキーマドキュメント内で scalar キーワードを使って定義できます。

カスタムスカラー型の定義

"""
日時を表すスカラー型 (ISO 8601 形式の文字列)
"""
scalar DateTime

type Event {
  title: String!
  startAt: DateTime
}

ライブラリの実装によりますが、カスタムスカラー型をそのまま使おうとすると、単なる String 型として扱われます。カスタムスカラー型のデータを GraphQL サーバー型でどのようにハンドルするかは、サーバーライブラリごとに実装方法が提供されています。例えば、下記は Golang の gqlgen ライブラリにおけるカスタムスカラー型のドキュメントです。実装例として、yes や no として送られてきた文字列データを、Golang の bool 型として参照できるようにする方法が紹介されています。

参考: Mapping GraphQL scalar types to Go types — gqlgen

カスタムスカラー型のデータは、サーバーには文字列として送られてきますが、サーバー側でカスタムスカラー用の Unmarshal/Marshal 実装を行っておくことで、リゾルバー内の実装では、任意のクラスのインスタンスとして扱えるようになります。どのようなクラスにマッピングすべきかは、実装言語に依存します。

簡単に言うと、どこでフォーマットチェックをするかというだけの話なのですが、各リゾルバー内で受信した文字列のフォーマットチェックを行うよりは、カスタムスカラー型ごとの処理として Marshal/Unmarshal 処理が定義されている方が分かりやすいでしょう。

GraphQL

GraphQL スキーマ仕様
へ戻る

5 つの組み込みスカラー型 (Scalar types)

カスタムスカラー型 (Custom scalar types)

関連記事