GraphQL 명세 ⑧: September 2025 에디션의 새로움

드디어 시리즈의 마지막 편입니다. 1편부터 7편까지 GraphQL 명세의 본문 여섯 개 장을 차례로 읽어왔는데요. 그동안 곳곳에서 “이건 September 2025에서 새로 들어왔다”, “자세한 건 마지막 편에서”라며 미뤄둔 이야기들이 있었습니다. 이번 편에서 그 약속들을 한자리에 모아 갚으려고 합니다.

1편에서 짚었듯 September 2025 에디션은 2021년 10월 이후 4년 만의 정식 개정판입니다. 그동안 쌓인 변경 제안이 한꺼번에 반영됐는데요. 흥미로운 건 핵심 신규 기능들을 나란히 놓고 보면, 하나의 방향을 가리키고 있다는 점입니다. 바로 사람뿐 아니라 도구와 AI가 GraphQL을 더 잘 다루도록 돕는 방향입니다. 하나씩 살펴보겠습니다.

스키마 좌표: 스키마의 한 점을 정확히 가리키기

첫 번째는 스키마 좌표(Schema Coordinates) 입니다. 이름 그대로 스키마 안의 특정 위치를 문자열 하나로 정확히 가리키는 표준 표기법인데요. 그동안 “User 타입의 name 필드”를 말하려면 풀어서 설명하거나 각자 다른 방식으로 적어야 했지만, 이제는 약속된 형식이 생겼습니다.

User                  # User 타입
User.name             # User 타입의 name 필드
User.name(id:)        # 그 필드의 id 인자
@deprecated           # deprecated 디렉티브
@deprecated(reason:)  # 그 디렉티브의 reason 인자

타입은 이름으로, 필드는 타입.필드로, 인자는 타입.필드(인자:)로 가리킵니다. 3편에서 본 타입 시스템의 모든 요소에 이렇게 고유한 주소를 매길 수 있게 된 건데요.

별것 아닌 듯 보이지만 쓰임새가 넓습니다. 스키마의 어떤 필드가 얼마나 쓰이는지 추적하거나, 변경 이력을 남기거나, 자동화 도구가 코드 리뷰에서 “이 필드를 건드렸다”고 정확히 짚어줄 때 모두 공통된 좌표 체계가 필요하기 때문입니다. 사람이 문서에 적기에도 편하고, 기계가 파싱하기에도 명확한 이 표기법은 GraphQL 생태계의 도구들이 같은 언어로 대화할 수 있는 기반이 됩니다.

@oneOf 입력 객체: 여럿 중 정확히 하나

두 번째는 3편에서 미리 맛본 @oneOf 입력 객체입니다. 입력 객체에 @oneOf를 붙이면 “이 안의 필드 중 정확히 하나만 채워야 한다”는 제약이 스키마 차원에서 생긴다고 했는데요.

input UserBy @oneOf {
  id: ID
  email: String
  username: String
}

type Query {
  user(by: UserBy!): User
}

이 스키마는 “사용자를 id로 찾거나, email로 찾거나, username으로 찾되 한 번에 하나의 기준만 쓸 수 있다”를 명확히 표현합니다. 예전에는 세 인자를 다 optional로 두고 리졸버 안에서 “둘 이상 들어오면 에러” 같은 검사를 직접 짜야 했는데요. 이제는 그 규칙이 타입에 박혀 있어서, 5편에서 본 검증 단계가 알아서 걸러줍니다.

이게 왜 도구 친화적일까요? 스키마만 보면 입력 규칙이 완전히 드러나기 때문입니다. 폼을 자동 생성하는 도구는 “셋 중 하나만 입력받는 UI”를 만들 수 있고, 코드를 생성하는 도구는 정확한 유니온 타입을 찍어낼 수 있습니다. 사람이 별도 문서로 “주의: 하나만 넣으세요”라고 안내할 필요 없이, 규칙이 스키마 자체에 담기는 거죠.

실행 문서에도 설명문을 달 수 있습니다

세 번째 변화가 어쩌면 가장 상징적입니다. 바로 실행 문서에 설명문(description)을 다는 기능인데요. 원래 GraphQL에서 설명문은 스키마 쪽에만 달 수 있었습니다. 타입이나 필드 위에 삼중 따옴표로 설명을 붙이는 그 방식 말이죠.

"""
사용자를 나타내는 타입
"""
type User {
  """
  사용자의 표시 이름
  """
  name: String!
}

September 2025부터는 이 설명문을 2편에서 본 쿼리나 뮤테이션, 프래그먼트 같은 실행 문서에도 달 수 있게 됐습니다.

"""
대시보드 상단에 보여줄 사용자 요약 정보를 가져온다
"""
query UserSummary($id: ID!) {
  user(id: $id) {
    name
  }
}

그리고 이 설명문은 단순한 주석이 아니라, 2편에서 다룬 문서의 추상 구문 트리(AST)에 정식으로 포함됩니다. 즉 도구가 파싱하면 이 설명을 데이터로 읽어낼 수 있다는 뜻인데요.

평범한 주석과 뭐가 다를까요? 주석은 파싱하면 버려지지만, 설명문은 구조의 일부로 남습니다. 그래서 저장된 쿼리 모음을 문서화하거나, 이 쿼리가 무슨 의도인지를 도구가 이해해야 할 때 활용할 수 있습니다. 특히 LLM에게 “이 쿼리가 무엇을 하는 것인지” 맥락을 줄 때, 코드 안에 의도가 구조적으로 박혀 있으면 훨씬 안전하게 다룰 수 있습니다.

그 밖에 다듬어진 것들

굵직한 세 가지 외에도 명세 곳곳이 다듬어졌습니다. 비슷한 성격의 정리들이라 묶어서 짚어보겠습니다.

• 전체 유니코드 지원 — 쿼리 문서의 문법이 유니코드 전 범위를 제대로 다루도록 정리되어, 다양한 언어의 문자를 더 일관되게 처리합니다.
• @deprecated의 확장 — 3편에서 본 deprecated 표시를 필드뿐 아니라 인자와 입력 필드에도 붙일 수 있도록 규칙이 명확해졌습니다.
• 실행과 에러 용어 정리 — 6편과 7편에서 본 실행 과정과 에러 처리의 용어가 더 엄밀하게 다듬어져, 구현체마다 미묘하게 다르던 동작이 더 예측 가능해졌습니다.
• 요청 extensions의 명문화 — 7편에서 본 extensions를 응답뿐 아니라 요청에도 실어 보낼 수 있다는 점이 분명히 정리됐습니다.

하나하나는 작아 보여도, 이런 정리들이 쌓이면 서로 다른 GraphQL 구현체들이 더 똑같이 동작하게 됩니다. 표준이 모호한 곳을 메우는 일이야말로 명세 개정의 가장 중요한 임무인데요.

왜 하필 지금, 이런 변화일까요

신규 기능들을 나란히 놓고 보면 공통점이 보입니다. 스키마 좌표는 도구가 스키마의 한 점을 정확히 지목하게 하고, @oneOf는 입력 규칙을 스키마에 새겨 도구가 읽게 하며, 실행 문서 설명문은 쿼리의 의도를 구조에 담아 기계가 이해하게 합니다. 모두 사람의 머릿속이나 별도 문서에만 있던 정보를, 기계가 읽을 수 있는 구조로 끌어내리는 방향인데요.

이건 우연이 아닙니다. AI 코딩 에이전트와 자동화 도구가 코드를 직접 읽고 쓰는 시대에, 의도가 코드 바깥에 흩어져 있으면 도구가 실수하기 쉽습니다. 반대로 규칙과 의도가 타입과 스키마에 명시적으로 박혀 있으면, 도구도 LLM도 그걸 단서 삼아 더 안전하게 동작할 수 있는데요. 이는 테스트와 타입으로 AI의 결과물을 제어하자는 스펙 주도 개발의 문제의식과도 정확히 같은 결입니다. GraphQL 명세가 4년 만의 개정에서 이 방향을 택했다는 건, 표준이 시대의 흐름을 읽고 있다는 신호로 봐도 좋겠습니다.

마치며: 여덟 편을 돌아보며

이번 편에서는 GraphQL September 2025 에디션의 신규 기능들을 한자리에 모아봤습니다. 스키마의 한 점을 정확히 가리키는 스키마 좌표, 여럿 중 하나만 받게 하는 @oneOf 입력 객체, 쿼리의 의도를 구조에 담는 실행 문서 설명문, 그리고 곳곳을 다듬은 작은 정리들까지 살펴봤는데요. 이 변화들이 하나같이 도구와 AI 친화라는 방향으로 수렴한다는 점도 짚어봤습니다.

여기까지가 1편에서 펼쳐 보였던 지도의 끝입니다. 명세가 무엇을 정하는 문서인지에서 출발해, 쿼리 언어와 타입 시스템, 인트로스펙션, 검증, 실행, 응답을 거쳐 최신 개정까지 함께 걸어왔는데요. 이제 명세 원문을 펼쳐도 어느 장이 무슨 이야기를 하는지, 그 안의 용어가 무엇을 가리키는지 한결 또렷하게 읽히실 겁니다.

명세를 읽는 일은 한 번으로 끝나지 않습니다. 실무에서 “이 동작이 표준일까 라이브러리 확장일까” 궁금할 때마다 GraphQL September 2025 명세를 직접 펼쳐 확인하는 습관을 들이시면, 이 시리즈가 그 첫걸음으로 오래 남으면 좋겠습니다. 그동안 함께 읽어주셔서 고맙습니다. 🙇