01
배포 중인 SDL을 이전 칸에 두기
비교 방향은 이전 버전에서 새 버전입니다. 양쪽을 바꾸면 제거와 추가의 뜻이 바뀌고 위험도 다시 계산되므로 잘못 붙여 넣었을 때 교환 기능을 사용하세요.
GraphQL 문서
GraphQL 스키마 비교릴리스 전에 계약 변경 검토
현재 배포된 전체 SDL은 이전 칸에, 제안한 전체 SDL은 새 칸에 넣으세요. 순서가 위험 판단을 결정합니다.
GraphQL 스키마 비교
이전 스키마 SDL
새 스키마 SDL
차이 결과
완전한 스키마 SDL 두 개를 입력하거나 예제를 불러오세요.
두 SDL은 현재 브라우저에서만 분석합니다. API 요청, 업로드, 기록 저장, URL 입력 전달은 하지 않습니다.
옵션
GraphQL.js가 호환성 손상과 잠재적 위험을 판정합니다. 나머지 구조 변경과 사용 중단 표시는 별도로 보여 주며 안전하다고 단정하지 않습니다.
SDL 하나당 100,000자, 토큰 20,000개, 중첩 100단계까지입니다. 비교는 8초 후 중단됩니다.
완전한 스키마 SDL 두 개를 입력하거나 예제를 불러오세요.
GraphQL 스키마 비교는 SDL의 줄 순서나 공백이 바뀌어 텍스트 diff가 복잡할 때 유용합니다. 실제 클라이언트가 참조하는 타입, 필드, 인수의 계약이 어떻게 달라졌는지 확인할 수 있습니다.
구조 변화와 위험 판정은 분리해서 봐야 합니다. GraphQL.js가 위험으로 분류하지 않은 새 필드나 사용 중단 표시도 결과에 남겨 두어 검토자가 놓치지 않도록 합니다. 스키마 변경 사항을 한곳에서 읽되 분류의 근거는 구분합니다.
GraphQL 스키마 비교가 필요한 이유
글자 차이보다 API 계약의 의미에 집중합니다.
공백을 걷어 내고 경로를 확인
GraphQL 스키마 비교는 두 SDL을 파싱한 뒤 타입과 필드, 인수의 경로를 대조합니다. 정의 순서나 들여쓰기만 바뀌었다면 차이로 세지 않으며, 사라진 필드는 이름과 이전 값을 보여 줍니다.
위험과 사용 중단을 따로 표시
enum 값 추가는 잠재적 위험이지만 @deprecated 추가는 기존 호출을 곧바로 막지 않습니다. GraphQL 스키마 비교는 두 사건을 분리하고 일반적인 새 필드도 기록하여 미분류를 안전하다고 표현하지 않습니다.
방향을 확인하고 최신 결과만 내보내기
02
자동 실행을 작업에 맞추기
기본값은 입력이 약 350ms 멈춘 뒤 자동 비교입니다. 긴 SDL을 붙여 넣을 때는 자동을 끄고 비교 버튼 또는 Ctrl/Cmd+Enter로 현재 두 문서만 처리할 수 있습니다.
03
오류와 결과의 최신 상태 확인
수정 직후 기존 보고서는 오래된 상태가 되어 복사와 다운로드가 비활성화됩니다. 오류가 가리키는 칸과 행·열을 고친 뒤 다시 비교하세요. 화면에 100개씩 보여도 내보내기에는 전체가 포함됩니다.
구조와 호환성 신호를 함께 보기
의미를 아는 구조 경로
타입, 필드, 인수, 입력 객체, enum, union, 지시어를 경로별로 비교합니다. 공백과 선언 순서 변경은 계약 변경으로 취급하지 않습니다.
검증된 위험 분류
GraphQL.js가 호환성 손상과 잠재적 위험을 판정하며 규칙 코드를 함께 표시합니다. 나머지 구조 변경은 무조건 안전하다고 주장하지 않습니다. GraphQL Inspector의 원격 CI 설정 없이 두 로컬 SDL을 검토할 수 있습니다.
사용 중단 기록과 전체 보고서
@deprecated의 추가 및 이유 변경을 따로 기록합니다. 사용 중단 필드를 실제로 제거하면 여전히 호환성 손상입니다. 다운로드에는 모든 항목이 포함됩니다.
정적 SDL 비교가 닿는 범위
- 양쪽 모두 완전한 SDL이어야 함
- Query 루트가 없는 타입 조각이나 정의되지 않은 타입 참조는 완전한 스키마가 아닙니다. GraphQL 스키마 비교는 오류가 있으면 빈 차이 보고서를 만들지 않고 해당 칸과 가능한 행·열을 알려 줍니다.
- 클라이언트 사용량은 알 수 없음
- 호환성 손상은 기존 연산이 실패할 수 있다는 뜻입니다. 실제로 어느 클라이언트가 그 필드를 쓰는지 확인하지 않으므로 영향도는 별도 사용 데이터로 판단해야 합니다.
- 원격 URL과 introspection JSON은 입력 아님
- 이 도구는 SDL 텍스트 두 개만 받으며 네트워크 요청이나 GraphQL 연산을 실행하지 않습니다. introspection JSON만 있다면 먼저 전체 SDL로 변환하세요.
- 이름 변경은 제거와 추가
- 두 정적 스냅샷만으로 이름 변경 의도를 추론하지 않습니다. 이전 필드가 @deprecated였더라도 실제 제거는 규칙상 호환성 손상으로 남습니다.
GraphQL 스키마 비교 관련 질문
Mutation 인수가 null을 허용하도록 바뀌면 호환성이 깨지나요?
필수 Mutation 인수를 nullable로 바꾸면 허용하는 입력이 넓어지므로 GraphQL.js는 대개 그 방향을 호환성 손상으로 보지 않습니다. 반대로 필수로 바꾸면 값을 생략하던 기존 호출이 실패할 수 있습니다.
GraphQL enum에 값을 추가하면 호환성이 깨지나요?
새 enum 값은 기존 쿼리의 검증을 곧바로 깨뜨리지 않더라도 모든 값을 분기 처리하는 클라이언트에는 예상 밖일 수 있습니다. 그래서 잠재적 위험으로 구분합니다.
기존 클라이언트를 깨뜨리지 않고 GraphQL 타입 이름을 바꿀 수 있나요?
SDL 두 개에는 변경 의도가 적혀 있지 않습니다. GraphQL 스키마 비교는 이전 타입 제거와 새 타입 추가를 따로 보고하므로 전환용 별칭이나 단계적 이전을 API에서 설계해야 합니다.
GraphQL Mutation을 사용 중단으로 표시할 수 있나요?
Mutation은 루트 타입의 필드이므로 @deprecated를 붙일 수 있습니다. 표시만으로 기존 연산이 없어지지 않으며 나중에 필드를 제거하면 기본 규칙은 호환성 손상으로 판정합니다.
null을 허용하지 않던 필드를 nullable로 바꾸면 호환성이 깨지나요?
출력 필드를 non-null에서 nullable로 바꾸면 생성된 클라이언트 타입의 가정이 달라져 GraphQL.js가 호환성 손상으로 표시합니다. 반대 방향도 resolver의 실제 반환값을 별도로 시험해야 합니다.
예상과 다른 결과가 나왔나요?
다음 변경을 GraphQL 스키마 비교로 검토
현재 SDL과 제안 SDL을 나란히 놓고 위험과 나머지 구조 변화를 확인한 뒤 최신 보고서를 내려받으세요.