브라우저에서 JSONPath: 실제로 쓰이는 패턴을 위한 실용 레퍼런스와 테스터

XML이 기본이었고 모두가 XPath를 배우던 시절을 기억할 만큼 오래 API와 일했습니다. JSONPath는 JSON에 대한 동등한 언어이고, 몇 년간 피해 다닌 끝에(JavaScript로 그냥 쓰면 되니까, 그렇죠?) 이제는 받아들였습니다. JSONPath가 유일하게 사용 가능한 언어인 곳이 너무 많아서 — Postman 변수, AWS Step Functions, 쿠버네티스 셀렉터, Datadog 필터 — 능숙해지면 실질적인 시간을 아낄 수 있습니다.

이 가이드는 제가 시작했을 때 있었으면 했던 레퍼런스입니다. 실제로 프로덕션에 등장하는 문법, 저에게 몇 시간을 잡아먹은 함정들, 그리고 ToolBox Hubs의 JSONPath 테스터로 결과가 중요한 곳에 붙여넣기 전에 표현식을 확인하는 방법을 다룹니다.

JSONPath란 무엇인가, 빠르게

JSONPath는 JSON 문서를 위한 쿼리 언어입니다. $.store.book[*].author 같은 표현식을 주면 일치하는 모든 값을 반환합니다. $는 루트, 점과 대괄호는 구조 안으로 이동하며, 특수 연산자로 필터링, 슬라이싱, 재귀 탐색이 가능합니다.

XML에 XPath를 사용해본 적이 있다면 멘탈 모델이 직접 전이됩니다. 그렇지 않다면 JavaScript의 점 표기법을 더 강력하게 만든 버전이라고 생각하세요 — "$10 미만의 모든 책" 또는 "문서의 어느 깊이에서든 모든 저자"를 한 줄로 표현할 수 있습니다.

모두가 사용하는 정식 예제는 Stefan Goessner의 원문에서 가져온 것입니다:

{
  "store": {
    "book": [
      { "category": "fiction", "author": "Tolkien", "price": 22.99 },
      { "category": "reference", "author": "Rees", "price": 8.95 }
    ],
    "bicycle": { "color": "red", "price": 19.95 }
  }
}

$.store.book[*].author는 ["Tolkien", "Rees"]를 반환합니다. $..price는 [22.99, 8.95, 19.95]를 반환합니다. $.store.book[?(@.price < 10)]는 두 번째 책 객체를 반환합니다. 이게 전부입니다.

90%의 경우 사용하게 될 연산자들

수십 개의 JSONPath 연산자가 있지만, 그 중 다섯 개가 실무에서 작성하는 거의 모든 것을 커버합니다.

$ — 루트

모든 JSONPath 표현식은 $로 시작합니다. 문서의 최상단을 가리킵니다. 기술적으로 생략할 수도 있지만(일부 라이브러리는 관대합니다) 명시적으로 작성하면 의도가 명확해집니다.

.field — 자식 접근

표준 점 표기법. $.users.0.email은 루트에서 users 배열로, 인덱스 0을 선택하고 email을 읽습니다. JavaScript와 동일하지만 0이 속성 이름으로 작동합니다.

[n] — 배열 인덱스

배열 접근을 위한 대괄호 표기법, 인덱스가 동적이거나 필드명에 특수 문자가 있을 때 유용합니다. $.users[0], $.users[-1](마지막 항목), $.users[0:3](0부터 3까지 제외 슬라이스).

음수 인덱스는 끝에서부터 카운트합니다. $.users[-1]은 마지막 사용자입니다. $.users[-3:]는 마지막 세 명을 제공합니다. 모든 구현에서 지원되지는 않습니다 — RFC 9535가 표준화하지만 의존한다면 라이브러리를 확인하세요.

[*] — 와일드카드

배열의 모든 항목 또는 객체의 모든 값을 매치합니다. $.users[*].email은 모든 사용자의 이메일을 반환합니다. $.config.*는 config 객체의 모든 값을 반환합니다. 속성 접근과 결합하면 일반적인 구조를 평탄화할 수 있습니다.

..field — 재귀 탐색

가장 강력한 연산자이며 제가 가장 많이 사용하는 것입니다. $..price는 깊이에 관계없이 문서 어디서든 모든 price 필드를 찾습니다. 정확한 구조를 모르거나 신경 쓰지 않을 때 유용합니다.

탐색은 경로를 신경 쓰지 않습니다 — 패턴과 일치하는 모든 것을 찾을 뿐입니다. 즉흥적인 데이터 탐색("이 응답에 사용자 ID가 있나?")에는 좋지만, 데이터에 같은 키 이름이 다른 컨텍스트에서 나타나면 위험합니다(사용자의 name 필드와 역할의 name 필드 둘 다 $..name과 매치됩니다).

필터: 사람들이 막히는 곳

필터 표현식은 [?(...)]로 작성하며, 내용은 배열의 각 항목에 대해 평가되는 불리언 표현식입니다. 필터 안에서 @는 현재 항목을 가리킵니다.

$.store.book[?(@.price < 10)]
$.users[?(@.role == 'admin')]
$.events[?(@.timestamp > 1700000000)]

사람들이 걸려 넘어지는 부분은 @입니다. JavaScript의 this 또는 forEach 안의 현재 항목과 동등합니다. @가 없으면 필터는 어떤 필드도 참조할 수 없습니다 — [?(price < 10)]는 작동하지 않습니다. price가 정의되지 않았기 때문입니다. 엔진은 현재 항목 안을 봐야 한다는 것을 모릅니다.

비교 연산자

라이브러리 전반에서 보편적: ==, !=, <, >, <=, >=.

오른쪽은 리터럴일 수 있습니다: 숫자(@.age > 18), 작은따옴표 문자열(@.role == 'admin'), 큰따옴표 문자열, true, false, 또는 null.

보편적이지 않은 것: 두 필드를 서로 비교하기(@.price > @.cost), 정규식 매칭(@.email =~ /.*@example\.com/), length()나 match() 같은 함수 호출. 일부 라이브러리는 지원하지만 많은 곳에서는 그렇지 않습니다. ToolBox Hubs의 JSONPath 테스터는 리터럴 값에 대한 기본 비교를 지원하며, 이는 실제 쿼리의 대다수를 커버합니다.

불리언 조합

표준 구현은 조건을 결합하기 위해 &&와 ||를 지원합니다:

$.products[?(@.in_stock == true && @.price < 50)]
$.events[?(@.severity == 'error' || @.severity == 'critical')]

JSONPath에서 복잡한 불리언 로직을 작성하고 있다면 보통 실제 코드로 내려가야 한다는 신호입니다 — 6개월 후 표현식을 읽는 미래의 자신이 고마워할 겁니다. JSONPath는 단순한 선택에 빛나며, 복잡한 비즈니스 로직은 진짜 언어에 속합니다.

슬라이스: 일부 항목만 필요할 때

[start:end:step]은 Python 슬라이싱과 정확히 동일하게 작동합니다.

• [0:5] — 처음 5개 항목
• [5:] — 인덱스 5부터 끝까지
• [:3] — 처음 3개 항목 ([0:3]과 동일)
• [-3:] — 마지막 3개 항목
• [::2] — 격항 항목
• [::-1] — 역순 (어디서나 지원되지는 않음)

슬라이싱은 JSONPath의 깔끔한 부분 중 하나입니다. Python에서 직접 가져온 것이며 예측 가능하게 동작합니다. "처음 N개 결과를 줘" 또는 "첫 번째를 제외한 모든 것을 줘" 패턴에 많이 사용합니다.

실제로 업무에서 등장하는 패턴

이론은 충분합니다; 실제 쿼리를 봅시다.

API 응답 필터링

API가 페이지네이션된 결과를 반환하고 특정 항목을 찾고 싶습니다. 테스트 프레임워크 또는 Postman의 JSONPath:

$.data[?(@.status == 'active')].id

활성 항목 모두의 ID를 반환합니다. API에 "상태로 필터링" 매개변수가 없다면 코드에서 변환하는 것보다 빠릅니다.

웹훅 페이로드에서 값 추출

Stripe, GitHub 등에서 웹훅을 처리하면서 특정 필드를 가져와야 합니다. AWS EventBridge 규칙, Step Functions 또는 Logic Apps의 JSONPath:

$.detail.payload.items[*].sku

주문의 모든 항목 SKU를 반환합니다. 클라우드 워크플로우 도구는 선언적이고 검사 가능하기 때문에 JSONPath에 의존하며, 임베디드 JavaScript는 보안 및 유지보수 부담이 됩니다.

깊이 중첩된 데이터에서 항목 찾기

정확한 구조는 모르지만 어딘가에 사용자 ID가 있다는 것은 압니다:

$..userId

중첩 깊이에 관계없이 문서의 모든 userId 필드를 반환합니다. 익숙하지 않은 API 응답이나 서드파티 통합 작업 시 탐색에 유용합니다.

스키마와 같은 제약 조건 검증

리스트의 모든 항목이 특정 필드를 가지고 있는지 확인해야 합니다:

$.users[?(!@.email)]

이메일이 없는 사용자를 반환합니다. 결과가 비어 있으면 데이터가 깨끗합니다. 이 패턴은 JSON 출력을 파싱하고 그 구조를 단언하는 CI 테스트 스크립트에서 잘 작동합니다.

함정들 (개인적인 목록)

이것들은 저에게 시간을 잡아먹은 것들입니다.

필터의 @는 필수입니다. [?(@.price < 10)] 대신 [?(price < 10)]을 작성하는 것이 가장 흔한 실수입니다. @ 없이는 엔진이 price가 현재 항목의 필드를 가리킨다는 것을 모릅니다.

필터는 매치되는 항목을 반환하지, 필터에 사용한 필드를 반환하지 않습니다. $..book[?(@.price < 10)]는 책 객체를 반환하지 가격을 반환하지 않습니다. 가격만 얻으려면: $..book[?(@.price < 10)].price.

표현식 안의 따옴표가 중요합니다. 둘러싼 언어와 혼동되지 않도록 JSONPath 문자열 안에 작은따옴표를 사용하세요. JSON 설정 파일에서 JSONPath는 문자열 값이므로 JSONPath 자체가 작은따옴표를 사용합니다: "$.users[?(@.role == 'admin')]". 혼합하면 파싱 오류가 발생합니다.

재귀 탐색은 그림자 매치를 찾습니다. $..name은 관련 없는 중첩 객체의 것을 포함하여 모든 name 필드와 매치됩니다. 같은 문서에 사용자 name 필드와 제품 name 필드가 있다면 둘 다 반환됩니다. 중요할 때는 구체적이어야 합니다.

인덱스 0 대 속성 "0". $.items[0]은 배열에서 작동합니다. $.items.0은 작동할 수도 있고 아닐 수도 있습니다 — 대부분의 파서는 배열에 대해 거부하지만(대괄호 전용) 객체의 속성 이름으로는 받아들입니다. 배열 접근에는 대괄호를 고수하세요.

빈 결과는 오류가 아닙니다. JSONPath가 아무것도 매치하지 않으면 예외가 아닌 빈 배열 []을 얻습니다. 이는 올바른 동작이지만 오타를 숨길 수 있습니다. 결과를 기대했는데 못 얻었다면 경로를 다시 확인하세요.

RFC 9535 대 Goessner 시대 라이브러리

JSONPath를 정의한 2007년 원문은 비공식적이었습니다 — 예제로 문법을 설명했지만 엣지 케이스에서의 동작을 공식적으로 명세하지 않았습니다. 다른 라이브러리 구현은 다른 선택을 했고, 수년에 걸쳐 차이가 누적되었습니다.

2024년에 RFC 9535가 공식 사양으로 발행되었습니다. 특히 다음에 대해 문법과 의미를 표준화합니다:

• 필터 표현식 문법
• 함수 확장 (length, count, match, search, value)
• 출력의 정규화된 경로 (각 결과가 위치를 포함)
• 정규식 매칭을 위한 I-Regexp 프로파일

새 프로젝트를 시작한다면 RFC 9535를 타겟으로 하는 라이브러리를 선호하세요 — Node용 jsonpath-rfc9535, Python 포트, jp CLI 도구. 기존 코드를 유지보수한다면 Goessner 시대 구현을 사용하고 있을 가능성이 큽니다; 괜찮습니다, 차이가 존재한다는 것만 알면 됩니다.

ToolBox Hubs의 JSONPath 테스터는 구현 전반에서 일관되게 작동하는 가장 일반적인 연산자를 구현합니다. 타겟 환경에서 작동하지 않을 것을 테스트하지 않도록 필터 문법에 의도적으로 보수적입니다.

JSONPath가 jq에 밀리는 곳

jq를 언급하지 않으면 오해의 소지가 있을 겁니다.

JSONPath는 JSON에서 값을 찾는 데 좋습니다. jq는 JSON을 찾고 변환하는 데 좋습니다. 다음이 필요하다면:

• 객체를 다른 형태로 투영 (.users | map({id, email}))
• 값 집계 (map(.price) | add)
• 여러 작업 결합
• 복잡한 조건부 로직 처리

jq가 극적으로 더 좋습니다. JSONPath에는 집계가 없고, map/reduce가 없으며, 함수 결합이 없습니다. 이것들은 버그가 아닙니다 — 범위 결정입니다. JSONPath는 쿼리 언어이고, jq는 변환 언어입니다.

올바른 도구는 환경에 따라 다릅니다. JSONPath는 임베드하기 단순(의존성 없이 문자열 파서뿐)하기 때문에 어디에나 있습니다. jq는 바이너리가 필요하고 브라우저 컨텍스트나 제한된 환경에서 사용하기 어렵습니다. Postman 테스트나 Step Function 입력 매핑에서는 JSONPath만 있습니다. 셸 파이프라인이나 서버 측 데이터 변환에서는 jq가 보통 더 좋습니다.

실용적인 워크플로우

이제 제가 실제로 JSONPath를 사용하는 방법:

1. JSON 포맷터에서 API 응답이나 JSON 문서를 열어 읽기 좋게 만듭니다.

2. 추출하고 싶은 값을 식별합니다. 보통 정신적으로 경로를 추적할 수 있습니다: "users 배열, 항목 N, role 필드, admin과 같음."

3. JSONPath 테스터를 열고 JSON을 붙여넣고 표현식을 작성합니다. 원하는 것을 정확히 반환할 때까지 반복합니다.

4. 작동하는 표현식을 그것이 살아야 할 곳으로 복사합니다 — Postman 테스트, AWS Step Function, 쿠버네티스 셀렉터.

5. 더 복잡한 것(변환, 집계)을 만들고 있다면 jq로 전환합니다.

이 워크플로우는 통합에서 "왜 내 JSONPath가 매치되지 않을까" 디버깅 시간을 몇 시간 줄여줍니다. 테스터는 대부분의 튜토리얼이 건너뛰는 누락된 단계입니다 — 문법을 보여주고 처음부터 올바르게 작성할 수 있다고 가정합니다. 보통은 그렇지 않으며, 특히 필터에서 그렇습니다.

더 넓은 JSON 워크플로우를 위한 도구 추천

JSONPath는 JSON 워크플로우의 한 도구입니다. 관련 유틸리티와 짝을 이루면 전체 파이프라인이 더 매끄러워집니다:

• JSON 포맷터 — 쿼리 전에 보기 좋게; 최소화된 JSON은 읽을 수 없음
• JSON Diff — JSONPath가 두 응답 간 다른 결과를 반환할 때, diff로 무엇이 변했는지 확인
• JSON to TypeScript — 샘플에서 TypeScript 타입을 생성한 다음, 스키마와 매치되는 JSONPath 작성에 타입 사용
• JSON 스키마 생성기 — 검증을 위한 JSON Schema 생성; 쿼리를 위한 JSONPath와 상호 보완적

JSONPath 테스터는 무료, 브라우저 전용이며 JSON을 어디로도 보내지 않습니다. 붙여넣고, 쿼리하고, 반복하고, 복사하세요. 그게 루프입니다.

마무리 노트

JSONPath는 화려하지 않습니다. 누구도 배우는 데 흥분하는 언어가 아닙니다. 하지만 한 시간을 들여 능숙해지면 수년간의 API 디버깅, 클라우드 워크플로우 구성, 데이터 탐색에 걸쳐 보상받습니다. 문법은 일반적인 패턴을 외울 만큼 작습니다. 함정은 내재화할 만큼 예측 가능합니다.

처음이라면: 기본 패턴($.field, $..field, $.array[*], [?(@.field == 'value')])으로 시작하고 단순한 것을 잠시 사용해본 후에야 필터 복잡성을 시도하세요. 대부분의 실제 쿼리는 단순합니다. 복잡성은 보통 코드로 더 잘 해결되는 엣지 케이스에서 옵니다.