쿼리 약식 문법

문서에 연산이 하나뿐이고 그 연산이 변수도 없고 지시문도 적용되어 있지 않은 쿼리인 경우, 해당 연산은 query 키워드와 연산 이름을 생략한 약식 표기(shorthand)로 표현할 수 있습니다.

예를 들어, 이름이 없는 이 쿼리 연산은 쿼리 약식 문법으로 작성된 것입니다.

Example № 5{
  field
}

약식 쿼리 문법에는 설명(Descriptions)을 사용할 수 없습니다.

인자는 순서가 없다

인자는 어떤 구문적 순서로 제공되어도 동일한 의미를 유지합니다.

다음 두 연산은 의미적으로 동일합니다:

Example № 11{
  picture(width: 200, height: 100)
}

Example № 12{
  picture(height: 100, width: 200)
}

프래그먼트 내에서의 변수 사용

변수는 프래그먼트 내부에서 사용할 수 있습니다. 변수는 주어진 연산에 대해 전역 범위를 가지므로, 프래그먼트 내에서 사용되는 변수는 그 프래그먼트를 (직접 또는 간접적으로) 포함하는 모든 최상위 연산에서 선언되어야 합니다. 만약 프래그먼트에서 변수가 참조되는데 해당 변수를 정의하지 않는 연산에서 그 프래그먼트를 포함하면, 그 연산은 유효하지 않습니다(자세한 내용은 All Variable Uses Defined 참조).

의미론

지시문 순서의 중요성

지시문은 특정 구문적 순서로 제공될 수 있으며, 그 순서는 의미론적 해석을 가질 수 있습니다.

다음 두 타입 정의는 서로 다른 의미를 가질 수 있습니다:

Example № 33type Person
  @addExternalFields(source: "profiles")
  @excludeField(name: "photo") {
  name: String
}

Example № 34type Person
  @excludeField(name: "photo")
  @addExternalFields(source: "profiles") {
  name: String
}

Parsing a Schema Coordinate

SchemaCoordinate는 자체 어휘 토큰 집합을 가진 독립적인 문법입니다. 이는 Document 내부에 포함되지 않습니다. SchemaCoordinate의 소스 텍스트는 SourceCharacter의 연속이어야 합니다.

다른 GraphQL 문서와 달리, SchemaCoordinate는 문자 시퀀스 내에 Whitespace나 다른 Ignored 문법을 포함해서는 안 됩니다. 이는 각 schema coordinate가 단일하고 모호하지 않은 어휘 형태를 갖도록 보장합니다.

Resolving a Schema Coordinate

schema element를 참조하려면, schema coordinate를 GraphQL schema의 문맥에서 해석해야 합니다.

만약 해당 schema element를 찾을 수 없다면 resolve 함수는 값을 반환하지 않습니다(오류를 발생시키지는 않습니다). 그러나 schema coordinate 내의 비-리프(non-leaf) 노드 중 어느 하나라도 schema에서 찾을 수 없을 경우에는 오류가 발생합니다.

Examples

위 표는 아래 스키마를 기준으로 각 종류의 schema coordinate 예시를 보여줍니다.

type Query {
  searchBusiness(criteria: SearchCriteria!): [Business]
}

input SearchCriteria {
  name: String
  filter: SearchFilter
}

enum SearchFilter {
  OPEN_NOW
  DELIVERS_TAKEOUT
  VEGETARIAN_MENU
}

type Business {
  id: ID
  name: String
  email: String @private(scope: "loggedIn")
}

directive @private(scope: String!) on FIELD_DEFINITION

Built-in Scalars

GraphQL은 잘 정의된 기본 스칼라 집합을 명시합니다: Int, Float, String, Boolean, 및 ID. GraphQL 프레임워크는 이들 타입을 모두 지원해야 하며, 이러한 이름으로 타입을 제공하는 서비스는 이 문서에서 설명하는 동작을 따라야 합니다. 예를 들어, 서비스가 Int라는 타입을 포함시키고 그것을 64비트 정수나 국제화 정보 등 문서에서 정의한 것과 다른 용도로 사용해서는 안 됩니다.

__Schema 내성 타입에서 타입 집합을 반환할 때, 참조된 모든 내장 스칼라는 포함되어야 합니다. 만약 어떤 내장 스칼라 타입이 스키마의 어디에서도 참조되지 않으면(그 타입의 필드, 인수, 또는 입력 필드가 없음) 포함되어서는 안 됩니다.

타입 시스템 정의 언어로 GraphQL 스키마를 표현할 때는 간결함을 위해 모든 내장 스칼라를 생략해야 합니다.

Custom Scalars

GraphQL 서비스는 내장 스칼라 외에 사용자 정의 스칼라 타입을 사용할 수 있습니다. 예를 들어, 서비스는 직렬화 시 문자열로 표현되지만 RFC 4122를 준수하는 UUID라는 스칼라를 정의할 수 있습니다. UUID 타입의 필드를 질의할 때는 RFC 4122 호환 파서로 결과를 파싱할 수 있다는 것을 신뢰할 수 있습니다. 또 다른 유용한 사용자 정의 스칼라 예시는 URL로, 문자열로 직렬화되지만 서비스가 유효한 URL임을 보장합니다.

사용자 정의 스칼라를 정의할 때, GraphQL 서비스는 scalar specification URL을 @specifiedBy 지시문이나 specifiedByURL 내성 필드를 통해 제공해야 합니다. 이 URL은 스칼라의 데이터 형식, 직렬화 및 강제 규칙에 대한 사람이 읽을 수 있는 명세에 링크해야 합니다.

예를 들어, UUID 스칼라를 제공하는 서비스는 RFC 4122 또는 그 RFC의 합리적인 부분집합을 정의한 문서로 연결할 수 있습니다. 만약 scalar specification URL이 존재하면, 이를 인식하는 시스템과 도구는 해당 명세의 규칙을 준수해야 합니다.

Example № 43scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986")
scalar DateTime
  @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")

사용자 정의 scalar specification URL은 모호성을 피하기 위해 단일하고 안정적인 형식을 제공해야 합니다. 만약 링크된 명세가 변경 중이라면, 서비스는 변경될 가능성이 있는 리소스 대신 고정된 버전으로 링크해야 합니다.

사용자 정의 scalar specification URL는 정의된 이후 변경해서는 안 됩니다. 이를 변경하면 도구가 중단되거나 링크된 명세의 내용에 대한 깨지는 변경을 초래할 수 있습니다.

내장 스칼라 타입은 이 문서에서 규정되므로 scalar specification URL을 제공해서는 안 됩니다.

Result Coercion and Serialization

GraphQL 서비스는 특정 스칼라 타입의 필드를 준비할 때 그 스칼라 타입이 설명하는 계약을 준수해야 하며, 값이 강제(coerce)될 수 없거나 강제 과정에서 데이터 손실이 발생할 경우 execution error를 발생시켜야 합니다.

서비스는 내부의 다른 타입들을 기대되는 반환 타입으로 합리적으로 강제할 수 있도록 선택할 수 있습니다. 예를 들어 Int 타입의 필드를 강제할 때 불리언 true를 1로, 문자열 "123"을 10진수 123으로 파싱할 수 있습니다. 그러나 정보 손실이 발생할 가능성이 있는 경우에는 execution error를 발생시켜야 합니다.

이러한 강제 동작은 클라이언트에 관찰되지 않기 때문에, 강제의 정확한 규칙은 구현에 맡겨집니다. 서비스의 유일한 요구사항은 결과가 기대되는 스칼라 타입을 준수해야 한다는 점입니다.

GraphQL 스칼라는 사용 중인 직렬화 형식에 따라 직렬화됩니다. 각 스칼라 타입에 가장 적합한 직렬화 원시형이 있을 수 있으며, 서비스는 적절한 경우 해당 원시형을 생성해야 합니다.

Serialization Format을 참고하면 JSON 및 기타 형식에서 스칼라의 직렬화에 대한 자세한 정보를 볼 수 있습니다.

Input Coercion

GraphQL 서비스가 인수의 입력으로 스칼라 타입을 기대할 경우, 강제는 관찰 가능하므로 규칙이 잘 정의되어야 합니다. 입력 값이 강제 규칙에 일치하지 않으면 실행 전에 입력 값이 검증되므로 request error를 발생시켜야 합니다.

GraphQL은 정수 및 부동소수점 입력 값을 표현하는 서로 다른 상수 리터럴을 가지며, 강제 규칙은 만나는 입력 값의 종류에 따라 다르게 적용될 수 있습니다. 또한 GraphQL은 변수를 통해 매개변수화될 수 있고, 변수 값은 종종 HTTP 같은 전송에 직렬화되어 전송됩니다. 일부 일반 직렬화(예: JSON)는 정수와 부동소수점을 구분하지 않기 때문에, 분수 부분이 비어 있으면 정수 입력 값(예: 1.0)으로 해석되고, 그렇지 않으면 부동소수점 입력 값으로 해석됩니다.

아래 모든 타입에 대해, Non-Null을 제외하고는 명시적 값 null이 제공되면 입력 강제의 결과는 null입니다.

필드 정렬

객체를 질의할 때, 결과 필드 매핑은 실행 중에 만난 순서대로 개념적으로 정렬됩니다. 단, 해당 타입에 적용되지 않는 프래그먼트와 @skip 또는 @include 지시문으로 건너뛴 필드나 프래그먼트는 제외됩니다. 이 정렬은 CollectFields() 알고리즘을 사용할 때 올바르게 생성됩니다.

순서를 표현할 수 있는 응답 직렬화 형식은 이 정렬을 유지해야 합니다. unordered map만 표현할 수 있는 형식(예: JSON)이라도 텍스트상으로는 이 순서를 보존해야 합니다. 예를 들어 두 필드 {foo, bar}가 그 순서대로 질의되었다면, 결과 JSON 직렬화는 같은 순서로 {"foo": "...", "bar": "..."}를 포함해야 합니다.

요청에 나타난 필드 순서와 동일한 순서로 응답을 생성하면 디버깅 시 사람이 읽기 쉽고, 응답의 속성 순서를 예측할 수 있을 때 더 효율적인 파싱이 가능합니다.

프래그먼트가 다른 필드보다 먼저 펼쳐지면, 그 프래그먼트가 지정하는 필드들은 뒤따르는 필드들보다 먼저 응답에 나타납니다.

Example № 53{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

다음과 같은 순서화된 결과를 생성합니다:

Example № 54{
  "foo": 1,
  "bar": 2,
  "baz": 3,
  "qux": 4
}

선택에서 동일한 필드가 여러 번 질의되면, 첫 번째로 만난 시점을 기준으로 정렬됩니다. 단, 해당 타입에 적용되지 않는 프래그먼트는 정렬에 영향을 주지 않습니다.

Example № 55{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

다음과 같은 순서화된 결과를 생성합니다:

Example № 56{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

또한, 지시문으로 인해 필드가 제외되면 해당 필드는 정렬에 고려되지 않습니다.

Example № 57{
  foo @skip(if: true)
  bar
  foo
}

다음과 같은 순서화된 결과를 생성합니다:

Example № 58{
  "bar": 1,
  "foo": 2
}

결과 강제화

객체를 강제하는 결과를 결정하는 것은 GraphQL 실행자의 핵심이며, 자세한 내용은 값 완성(Value Completion)을 참조하십시오.

입력 강제화

객체는 입력으로는 절대 유효하지 않습니다.

타입 검증

객체 타입은 잘못 정의된 경우 유효하지 않을 수 있습니다. 다음 규칙 집합은 GraphQL 스키마의 모든 객체 타입이 따라야 합니다.

1. 객체 타입은 하나 이상의 필드를 정의해야 합니다.
2. 객체 타입의 각 필드에 대해:
   1. 해당 객체 타입 내에서 필드 이름은 고유해야 하며, 두 필드가 같은 이름을 가질 수 없습니다.
   2. 필드 이름은 "__" (언더스코어 두 개)로 시작해서는 안 됩니다.
   3. 필드가 반환하는 타입은 IsOutputType(fieldType)가 true를 반환하는 타입이어야 합니다.
   4. 해당 필드의 각 인수에 대해:
      1. 인수 이름은 "__"로 시작해서는 안 됩니다.
      2. 해당 필드 내에서 인수 이름은 고유해야 하며, 두 인수가 같은 이름을 가질 수 없습니다.
      3. 인수의 타입은 IsInputType(argumentType)가 true를 반환하는 입력 타입이어야 합니다.
      4. 인수 타입이 Non-Null이고 기본 값이 정의되어 있지 않다면:
         1. @deprecated 지시문은 이 인수에 적용되어서는 안 됩니다.
      5. 인수가 기본 값을 가지면, 그 기본 값은 해당 타입에 대한 강제 규칙에 따라 argumentType과 호환되어야 합니다.
3. 객체 타입은 하나 이상의 고유한 인터페이스를 구현한다고 선언할 수 있습니다.
4. 객체 타입은 구현하는 모든 인터페이스의 상위 집합이어야 합니다:
   1. 이 객체 타입을 objectType이라 하겠습니다.
   2. 각각의 선언된 인터페이스 interfaceType에 대해, IsValidImplementation(objectType, interfaceType)는 true여야 합니다.

인터페이스가 인터페이스를 구현함

한 인터페이스가 다른 인터페이스를 구현한다고 정의할 때, 구현하는 인터페이스는 구현되는 인터페이스에 의해 지정된 각 필드를 정의해야 합니다. 예를 들어, Resource 인터페이스가 Node 인터페이스를 구현하려면 id 필드를 정의해야 합니다:

Example № 70interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

전이적으로 구현된 인터페이스(구현되는 인터페이스가 다시 구현하는 인터페이스)들도 구현 타입 또는 인터페이스에 정의되어 있어야 합니다. 예를 들어, Image는 Resource를 구현하려면 또한 Node도 구현해야 합니다:

Example № 71interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

interface Image implements Resource & Node {
  id: ID!
  url: String
  thumbnail: String
}

인터페이스 정의는 순환 참조를 포함하거나 자기 자신을 구현해서는 안 됩니다. 다음 예제는 Node와 Named가 서로 자신을 구현하고 있어 잘못된 예입니다:

Counter Example № 72interface Node implements Named & Node {
  id: ID!
  name: String
}

interface Named implements Node & Named {
  id: ID!
  name: String
}

결과 강제화

인터페이스 타입은 특정 결과가 어떤 객체에 해당하는지 판별할 방법을 가져야 합니다. 일단 객체를 판별하면, 인터페이스에 대한 결과 강제화는 해당 객체에 대한 결과 강제화와 동일합니다.

입력 강제화

인터페이스는 입력으로는 절대 유효하지 않습니다.

타입 검증

인터페이스 타입은 잘못 정의된 경우 유효하지 않을 수 있습니다.

1. 인터페이스 타입은 하나 이상의 필드를 정의해야 합니다.
2. 인터페이스 타입의 각 필드에 대해:
   1. 그 필드는 해당 인터페이스 타입 내에서 고유한 이름을 가져야 하며, 두 필드가 같은 이름을 가질 수 없습니다.
   2. 그 필드의 이름은 "__"(언더스코어 두 개)로 시작해서는 안 됩니다.
   3. 그 필드가 반환하는 타입은 IsOutputType(fieldType)가 true를 반환하는 타입이어야 합니다.
   4. 그 필드의 각 인수에 대해:
      1. 인수의 이름은 "__"로 시작해서는 안 됩니다.
      2. 그 인수는 해당 필드 내에서 고유한 이름을 가져야 하며, 두 인수가 같은 이름을 가질 수 없습니다.
      3. 그 인수는 IsInputType(argumentType)가 true를 반환하는 입력 타입을 받아야 합니다.
3. 인터페이스 타입은 하나 이상의 고유한 인터페이스를 선언적으로 구현할 수 있으나, 자기 자신을 구현해서는 안 됩니다.
4. 인터페이스 타입은 구현하는 모든 인터페이스의 상위 집합이어야 합니다:
   1. 이 인터페이스 타입을 implementingType라 합시다.
   2. 각각 선언된 구현 인터페이스 implementedType에 대해, IsValidImplementation(implementingType, implementedType)는 true여야 합니다.

결과 강제화

유니언 타입은 주어진 결과가 어떤 객체에 해당하는지 판별하는 방법을 가져야 합니다. 일단 판별하면, 유니언의 결과 강제화는 해당 객체의 결과 강제화와 동일합니다.

입력 강제화

유니언은 입력으로는 절대 유효하지 않습니다.

타입 검증

유니언 타입은 잘못 정의된 경우 유효하지 않을 수 있습니다.

1. 유니언 타입은 하나 이상의 고유한 멤버 타입을 포함해야 합니다.
2. 유니언의 멤버 타입은 모두 객체 기본 타입(Object base types)이어야 합니다; 스칼라, 인터페이스 및 다른 유니언 타입은 유니언의 멤버가 될 수 없습니다. 마찬가지로 래핑 타입도 유니언의 멤버가 될 수 없습니다.

결과 강제화

GraphQL 서비스는 정의된 가능한 값들 중 하나를 반환해야 합니다. 합리적인 강제가 불가능한 경우에는 execution error를 발생시켜야 합니다.

입력 강제화

GraphQL은 열거형 입력 값을 표현하는 상수 리터럴을 제공합니다. GraphQL 문자열 리터럴은 열거형 입력으로 허용되어서는 안 되며, 대신 요청 오류를 발생시켜야 합니다.

EDN과 같이 비문자 상징 값을 별도로 표현하는 직렬화(예: EDN)는 그런 값들만 열거형 입력으로 허용해야 합니다. 그렇지 않은 대부분의 전송 직렬화에서는 문자열을 동일한 이름을 가진 열거형 입력 값으로 해석할 수 있습니다.

타입 검증

열거형 타입은 잘못 정의된 경우 유효하지 않을 수 있습니다.

1. 열거형은 하나 이상의 고유한 열거값을 정의해야 합니다.

순환 참조

입력 객체는 다른 입력 객체를 필드 타입으로 참조할 수 있습니다. 순환 참조는 입력 객체가 직접적으로 또는 참조된 입력 객체를 통해 자신을 참조할 때 발생합니다.

일반적으로 순환 참조는 허용되지만, Non-Null 단일 필드의 끊기지 않는 연쇄로 정의되어서는 안 됩니다. 그런 입력 객체는 합법적인 값을 제공할 방법이 없기 때문에 유효하지 않습니다.

다음 예제는 필드 self를 생략하거나 값으로 null을 제공할 수 있으므로 유효한 순환 참조 입력 타입입니다.

Example № 81input Example {
  self: Example
  value: String
}

다음 예제도 유효합니다. 이 경우 self 필드는 빈 List가 될 수 있습니다.

Example № 82input Example {
  self: [Example!]!
  value: String
}

다음 예제는 유효하지 않습니다. self 필드에 유한한 값을 제공할 수 없기 때문입니다.

Counter Example № 83input Example {
  value: String
  self: Example!
}

다음 예제도 유효하지 않습니다. First.second와 Second.first 필드에 의해 Non-Null 단일 순환 참조가 발생하기 때문입니다.

Counter Example № 84input First {
  second: Second!
  value: String
}

input Second {
  first: First!
  value: String
}

결과 강제화

입력 객체는 결과로서 유효하지 않습니다. 입력 객체 타입은 객체(Object)나 인터페이스 필드의 반환 타입이 될 수 없습니다.

입력 강제화

입력 객체의 값은 입력 객체 리터럴이거나 변수로 제공된 순서 없는 맵이어야 하며, 그렇지 않으면 request error가 발생해야 합니다. 어느 경우든 입력 객체 리터럴 또는 순서 없는 맵은 이 입력 객체 타입의 필드로 정의되지 않은 이름을 포함해서는 안 되며, 포함되어 있다면 요청 오류가 발생해야 합니다.

강제의 결과는 해당 입력 객체 타입에 의해 정의되고 값이 존재하는 각 필드에 대한 항목을 가진 순서 없는 맵입니다. 결과 맵은 다음 규칙으로 구성됩니다:

• 만약 정의된 입력 객체 필드에 대해 값이 제공되지 않았고 그 필드 정의가 기본값을 제공한다면, 해당 입력 필드 타입의 강제 규칙에 따라 기본값을 강제한 결과를 사용해야 합니다. 기본값이 제공되지 않았고 입력 객체 필드의 타입이 Non-Null이면 오류를 발생시켜야 합니다. 그렇지 않고 필드가 필수적이지 않다면 강제된 맵에 항목을 추가하지 않습니다.
• 만약 입력 객체 필드에 대해 값으로 null이 제공되었고 필드의 타입이 Non-Null 타입이 아니라면, 강제된 순서 없는 맵의 항목은 null 값을 가집니다. 즉, 명시적으로 제공된 null 값과 값을 제공하지 않은 경우는 의미상 다릅니다.
• 만약 입력 객체 필드에 리터럴 값이 제공되면, 강제된 순서 없는 맵의 항목은 그 필드 타입의 입력 강제 규칙에 따라 강제한 결과를 가집니다.
• 만약 입력 객체 필드에 변수가 제공되면, 해당 변수의 런타임 값이 사용되어야 합니다. 런타임 값이 null이고 필드 타입이 Non-Null이면 execution error가 발생해야 합니다. 런타임 값이 제공되지 않으면 변수 정의의 기본값을 사용해야 합니다. 변수 정의가 기본값을 제공하지 않으면 입력 객체 필드 정의의 기본값을 사용해야 합니다.

다음은 String 필드 a와 필수(Non-Null) Int! 필드 b를 가진 입력 객체 타입의 입력 강제화 예시입니다:

Example № 85input ExampleInputObject {
  a: String
  b: Int!
}

타입 검증

1. 입력 객체 타입은 하나 이상의 입력 필드를 정의해야 합니다.
2. 입력 객체 타입의 각 입력 필드에 대해:
   1. 입력 필드는 해당 입력 객체 타입 내에서 고유한 이름을 가져야 하며, 두 입력 필드가 같은 이름을 가질 수 없습니다.
   2. 입력 필드의 이름은 "__"(언더스코어 두 개)로 시작해서는 안 됩니다.
   3. 입력 필드는 IsInputType(inputFieldType)가 true를 반환하는 타입을 받아야 합니다.
   4. 만약 입력 필드 타입이 Non-Null이고 기본값이 정의되어 있지 않다면:
      1. @deprecated 지시문은 이 입력 필드에 적용되어서는 안 됩니다.
   5. 만약 입력 객체가 OneOf Input Object라면:
      1. 입력 필드의 타입은 nullable이어야 합니다.
      2. 입력 필드는 기본값을 가져서는 안 됩니다.
3. 입력 객체가 직접적으로 또는 참조된 입력 객체를 통해 자신을 참조하는 경우, 참조 연쇄의 최소한 하나의 필드는 nullable 또는 List 타입이어야 합니다.
4. InputObjectDefaultValueHasCycle(inputObject)는 false여야 합니다.

결과 강제화

GraphQL 서비스는 리스트 타입의 결과로 반드시 순서 있는 리스트를 반환해야 합니다. 리스트의 각 항목은 항목 타입에 대한 결과 강제화의 결과여야 합니다. 합리적인 강제가 불가능한 경우에는 실행 오류를 발생시켜야 합니다. 특히, 비-리스트 값이 반환되면 강제가 실패해야 하는데, 이는 타입 시스템과 구현 간의 기대 불일치를 나타냅니다.

리스트의 항목 타입이 널 허용(nullable)인 경우, 개별 항목의 준비 또는 강제 중에 발생한 오류는 해당 위치의 값이 null이 되도록 하며 응답에 실행 오류를 추가해야 합니다. 항목 타입이 Non-Null인 경우에는 개별 항목에서 발생한 실행 오류가 리스트 전체에 대한 실행 오류를 초래해야 합니다.

입력 강제화

입력으로 기대될 때, 리스트 값은 리스트의 항목 타입이 각 항목을 수용할 수 있을 때만 허용됩니다.

리스트 타입에 대한 입력으로 전달된 값이 리스트가 아니고 null도 아닐 경우, 입력 강제의 결과는 크기 1의 리스트가 되며, 단일 항목 값은 제공된 값에 대해 리스트의 항목 타입에 대한 입력 강제를 수행한 결과입니다(중첩 리스트의 경우 재귀적으로 적용될 수 있음).

이를 통해 여러 값을 허용하는 입력(종종 "var args"라 불림)은 입력 타입을 리스트로 선언할 수 있으며, 단일 값의 일반적인 경우 클라이언트는 직접 그 값을 전달할 수 있어 리스트를 구성할 필요가 없습니다.

다음은 다양한 리스트 타입과 값에 대한 입력 강제화 예시입니다:

널 허용 vs 선택적

필드는 선택 집합의 컨텍스트 내에서 항상 선택적입니다. 필드는 생략될 수 있으며 선택 집합은 (선택 집합이 비어있지 않은 한) 여전히 유효합니다. 그러나 Non-Null 타입을 반환하는 필드는 질의되었을 때 결코 null을 반환하지 않습니다.

입력(예: 필드 인수)은 기본적으로 항상 선택적입니다. 그러나 non-null 입력 타입은 필수입니다. Non-Null 입력 타입은 null 값을 허용하지 않을 뿐만 아니라 생략도 허용하지 않습니다. 단순화를 위해 nullable 타입은 항상 선택적이며 non-null 타입은 항상 필수로 간주됩니다.

결과 강제화

위의 모든 결과 강제화에서 null은 유효한 값으로 간주되었습니다. Non-Null 타입의 결과를 강제하려면 래핑된 타입의 강제화를 수행해야 합니다. 그 결과가 null이 아니면, Non-Null 타입의 강제 결과는 그 값입니다. 결과가 null이면 실행 오류를 발생시켜야 합니다.

입력 강제화

Non-Null 타입의 인수나 입력 객체 필드가 제공되지 않았거나, 리터럴 값으로 null이 제공되었거나, 런타임에 값이 제공되지 않았거나 null이 제공된 변수가 전달된 경우에는 요청 오류를 발생시켜야 합니다.

Non-Null 타입에 제공된 값이 null이 아닌 리터럴 값이거나 Non-Null 변수 값이라면, 래핑된 타입에 대한 입력 강제를 사용하여 강제됩니다.

Non-Null 인수는 생략될 수 없습니다:

Counter Example № 87{
  fieldWithNonNullArg
}

Non-Null 인수에 null 값을 제공할 수 없습니다:

Counter Example № 88{
  fieldWithNonNullArg(nonNullArg: null)
}

Nullable 타입의 변수를 Non-Null 인수에 제공할 수 없습니다:

Example № 89query withNullableVariable($var: String) {
  fieldWithNonNullArg(nonNullArg: $var)
}

타입 검증

1. Non-Null 타입은 다른 Non-Null 타입을 래핑해서는 안 됩니다.

내장 지시자

내장 지시자는 본 명세 내에서 정의된 모든 지시자를 의미합니다.

GraphQL 구현체는 @skip 및 @include 지시자를 제공해야 합니다.

타입 시스템 정의 언어를 지원하는 GraphQL 구현체는 스키마의 사용 중단된 부분을 표현할 때 @deprecated 지시자를 제공해야 합니다.

타입 시스템 정의 언어를 지원하는 GraphQL 구현체는 사용자 정의 스칼라 정의를 표현할 때 @specifiedBy 지시자를 제공하는 것이 좋습니다.

타입 시스템 정의 언어로 GraphQL 스키마를 표현할 때 OneOf 입력 객체를 나타내는 경우 @oneOf 지시자를 제공하는 것이 좋습니다.

타입 시스템 정의 언어를 사용하여 GraphQL 스키마를 표현할 때 간결함을 위해 어떤 내장 지시자든 생략할 수 있습니다.

GraphQL 서비스를 introspect(내부 검사)할 때 제공된 모든 지시자들(어떤 내장 지시자 포함)은 반환된 지시자 집합에 포함되어야 합니다.

사용자 정의 지시자

GraphQL 서비스 및 클라이언트 도구는 본 문서에 정의된 것 외에 추가적인 사용자 정의 지시자를 제공할 수 있습니다. 지시자는 GraphQL을 사용자 정의 또는 실험적 동작으로 확장하는 권장 수단입니다.

지시자는 선언된 위치에서만 사용되어야 합니다. 다음 예시는 필드에 주석을 달기 위해 사용할 수 있는 지시자를 정의한 것입니다:

Example № 90directive @example on FIELD

fragment SomeFragment on SomeType {
  field @example
}

긴 위치 목록을 표현할 때 형식을 돕기 위해 선택적으로 앞에 | 문자를 붙여 지시자 위치를 정의할 수 있습니다:

Example № 91directive @example on
  | FIELD
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT

지시자는 타입 시스템 정의 언어에도 주석을 달기 위해 사용될 수 있으며, 이는 GraphQL 실행 서비스를 생성하거나 클라이언트 런타임 코드를 생성하는 등 추가 메타데이터를 제공하는 데 유용합니다.

다음 예에서는 지시자 @example가 필드 및 인수 정의를 주석합니다:

Example № 92directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

type SomeType {
  field(arg: Int @example): String @example
}

지시자는 repeatable 키워드를 포함하여 반복 가능하도록 정의할 수 있습니다. 동일한 위치에서 서로 다른 인수로 같은 지시자를 여러 번 사용해야 하는 경우(특히 지시자를 통해 타입 또는 스키마 확장에 추가 정보를 제공해야 할 때) 반복 가능한 지시자가 유용합니다:

Example № 93directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE

type Book @delegateField(name: "pageCount") @delegateField(name: "author") {
  id: ID!
}

extend type Book @delegateField(name: "index")

지시자를 정의할 때 해당 지시자가 직접적 또는 간접적으로 자신을 참조해서는 안 됩니다:

Counter Example № 94directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION

타입 검증

1. 지시자 정의는 최소 하나의 DirectiveLocation을 포함해야 합니다.
2. 지시자 정의는 자신을 직접 참조하는 지시자의 사용을 포함해서는 안 됩니다.
3. 지시자 정의는 이 지시자를 포함하도록 전이적으로 참조하는 타입 또는 지시자를 참조하여 자신을 간접적으로 참조하는 지시자의 사용을 포함해서는 안 됩니다.
4. 지시자의 이름은 "__" (밑줄 두 개)로 시작해서는 안 됩니다.
5. 각 지시자 인수에 대하여:
   1. 해당 인수의 이름은 "__" (밑줄 두 개)로 시작해서는 안 됩니다.
   2. 그 지시자 내에서 인수 이름은 고유해야 하며, 동일한 이름을 가진 두 인수가 존재해서는 안 됩니다.
   3. 인수는 IsInputType(argumentType)가 true를 반환하는 타입을 허용해야 합니다.

일급 문서화

내성 시스템의 모든 타입은 타입 설계자가 기능 외에 문서를 게시할 수 있도록 description 필드(타입 String)를 제공합니다. GraphQL 서비스는 description 필드를 Markdown 문법(CommonMark 규격)을 사용하여 반환할 수 있으므로, description을 표시하는 도구는 CommonMark 호환 Markdown 렌더러를 사용하는 것이 권장됩니다.

폐기(Deprecation)

하위 호환성 관리를 지원하기 위해, GraphQL 필드, 인수, 입력 필드 및 열거형 값은 폐기되었는지 여부(isDeprecated: Boolean!)와 왜 폐기되었는지에 대한 설명(deprecationReason: String)을 나타낼 수 있습니다.

GraphQL 내성을 사용하여 제작된 도구는 폐기를 존중하여, 정보 숨김이나 개발자용 경고를 통해 폐기된 사용을 권장하지 않도록 해야 합니다.

안정적 정렬

스키마 가독성과 안정성을 향상시키기 위해 모든 데이터 컬렉션의 관찰 가능한 순서는 보존되어야 합니다. 스키마가 TypeSystemDocument에서 생성될 때, 내성은 각 요소 목록에 대해 소스의 동일한 순서로 항목을 반환해야 합니다: 객체 필드, 입력 객체 필드, 인수, 열거형 값, 지시문, 유니언 멤버 타입, 그리고 구현된 인터페이스.

스키마 내성 스키마

스키마 내성 시스템 자체는 GraphQL 스키마로 표현됩니다. 아래는 스키마 내성을 제공하는 전체 타입 시스템 정의 집합으로, 아래 섹션들에서 완전하게 정의되어 있습니다.

type __Schema {
  description: String
  types: [__Type!]!
  queryType: __Type!
  mutationType: __Type
  subscriptionType: __Type
  directives: [__Directive!]!
}

type __Type {
  kind: __TypeKind!
  name: String
  description: String
  # may be non-null for custom SCALAR, otherwise null.
  specifiedByURL: String
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  fields(includeDeprecated: Boolean! = false): [__Field!]
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  interfaces: [__Type!]
  # must be non-null for INTERFACE and UNION, otherwise null.
  possibleTypes: [__Type!]
  # must be non-null for ENUM, otherwise null.
  enumValues(includeDeprecated: Boolean! = false): [__EnumValue!]
  # must be non-null for INPUT_OBJECT, otherwise null.
  inputFields(includeDeprecated: Boolean! = false): [__InputValue!]
  # must be non-null for NON_NULL and LIST, otherwise null.
  ofType: __Type
  # must be non-null for INPUT_OBJECT, otherwise null.
  isOneOf: Boolean
}

enum __TypeKind {
  SCALAR
  OBJECT
  INTERFACE
  UNION
  ENUM
  INPUT_OBJECT
  LIST
  NON_NULL
}

type __Field {
  name: String!
  description: String
  args(includeDeprecated: Boolean! = false): [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

type __InputValue {
  name: String!
  description: String
  type: __Type!
  defaultValue: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __EnumValue {
  name: String!
  description: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __Directive {
  name: String!
  description: String
  isRepeatable: Boolean!
  locations: [__DirectiveLocation!]!
  args(includeDeprecated: Boolean! = false): [__InputValue!]!
}

enum __DirectiveLocation {
  QUERY
  MUTATION
  SUBSCRIPTION
  FIELD
  FRAGMENT_DEFINITION
  FRAGMENT_SPREAD
  INLINE_FRAGMENT
  VARIABLE_DEFINITION
  SCHEMA
  SCALAR
  OBJECT
  FIELD_DEFINITION
  ARGUMENT_DEFINITION
  INTERFACE
  UNION
  ENUM
  ENUM_VALUE
  INPUT_OBJECT
  INPUT_FIELD_DEFINITION
}