JSONPath 사용법: 기호별 뜻 한눈에 정리

JSONPath 경로식이 원하는 값을 정확히 가리키는지는 눈으로만 봐서는 확신하기 어렵습니다. $, ., [ ], [*], .. 같은 기호는 정해진 규칙에 따라 계산됩니다.

그 규칙만 알면 어떤 경로식이 어떤 값을 고르는지 손으로도 추적할 수 있습니다. 이 글은 예시 JSON 하나로 각 기호가 실제로 무엇을 선택하는지 하나씩 확인합니다.

요약 ① $는 JSON 문서 전체를, .속성이나 ['속성']은 객체의 특정 키 하나를 가리킵니다. ② [숫자]는 배열의 n번째 값(음수는 뒤에서부터)을, [*]나 .*는 그 위치의 모든 값을 가리킵니다. ③ ..는 모든 깊이를 재귀적으로 찾고, 결과는 일치 개수와 상관없이 항상 배열로 나옵니다.

API 응답에서 원하는 값만 뽑고 싶을 때 겪는 문제

JSON 데이터를 다루다 보면 $.data.items[0].name처럼 생긴 경로식을 문서나 예제 코드에서 자주 만납니다. 이 표현식 하나로 중첩된 JSON 구조 어딘가에 있는 값 하나를 바로 가리킬 수 있다는 게 JSONPath의 요점입니다.

문제는 그 경로식이 자신이 가진 JSON 구조에서도 똑같이 동작하는지입니다. 키 이름이 다르거나 배열 순서가 다르면, 겉보기에 비슷한 경로식이 전혀 다른 값을 가리키거나 아무 값도 찾지 못합니다.

대괄호 안에 숫자를 넣을지 *를 넣을지, . 뒤에 *를 붙이면 무엇이 달라지는지, ..는 정확히 어디까지 찾는지 — 기호 하나 차이로 결과가 달라지는데, 그 차이를 눈으로만 보고 예측하기는 쉽지 않습니다.

도구 없이 기호 규칙만으로 직접 계산하는 방법

JSONPath는 구현체마다 지원하는 문법 범위가 조금씩 다릅니다. 여기서 정리하는 다섯 가지 규칙은 아래 예시 JSON을 기준으로, 문자 그대로 하나씩 적용하면 결과를 손으로도 재현할 수 있는 범위입니다.

{
  "store": {
    "book": [
      { "title": "가난한 찰리의 연감", "price": 22000 },
      { "title": "현명한 투자자", "price": 18500 }
    ],
    "bicycle": { "color": "red", "price": 129000 }
  }
}

규칙은 다섯 가지입니다.

1. $ — 문서 전체를 가리킵니다. 경로식이 $ 하나뿐이면 결과는 이 JSON 전체가 담긴 배열 1개입니다.
2. .속성 또는 ['속성'] — 객체에서 그 이름의 키를 하나 선택합니다. $.store.bicycle.color는 문자열 "red" 하나를 가리킵니다.
3. [숫자] — 배열에서 그 순서(0부터 시작)의 값을 하나 선택합니다. 음수는 배열 끝에서부터 셉니다. $.store.book[0]은 첫 번째 책을, $.store.book[-1]은 마지막 책을 가리킵니다.
4. [*] 또는 .* — 그 위치에 있는 모든 값을 선택합니다. $.store.book[*]는 book 배열의 원소인 책 객체 2개를 모두 선택합니다.
5. .. — 뒤에 오는 이름을 문서의 모든 깊이에서 찾습니다. $..price는 book 안의 price 두 개와 bicycle의 price까지 총 세 개를 찾아냅니다.

$.store.book[*].title이 실제로 어떻게 계산되는지 순서대로 따라가면 이렇습니다.

• 1단계 $ → 문서 전체 1개가 대상입니다.
• 2단계 .store → store 객체 1개로 좁혀집니다.
• 3단계 .book → book 배열 1개(배열 자체가 값)로 좁혀집니다.
• 4단계 [*] → book 배열의 원소 각각, 즉 책 객체 2개로 늘어납니다.
• 5단계 .title → 남은 책 객체 각각에서 title 키를 뽑아 문자열 2개가 됩니다.

최종 결과는 ["가난한 찰리의 연감", "현명한 투자자"]이고 일치 개수는 2개입니다. 이 다섯 단계를 그대로 적용하면 어떤 경로식이든 손으로 결과를 예측할 수 있습니다.

손으로 짚은 이 다섯 단계가 자신의 JSON과 경로식에서도 맞게 계산되는지 저희 도구로 확인하기.

직접 해보기 →

자주 헷갈리는 지점

JSONPath를 처음 써보면 결과가 예상과 다르게 나오는 지점이 몇 군데 있습니다. 아래는 실제로 그 경로식을 넣었을 때 벌어지는 일입니다.

필터식과 슬라이스가 조용히 실패하는 이유는 대괄호 안의 내용을 인덱스 숫자, 와일드카드(*), 따옴표로 감싼 이름 — 이 세 형태로만 해석하기 때문입니다.

세 형태에 맞지 않는 내용은 전부 "그런 이름의 키를 찾아라"는 뜻으로 처리되고, 그런 키가 실제로 없으니 결과가 비게 됩니다.

정리

• $는 문서 전체, .속성이나 ['속성']은 객체의 키 하나를 가리킵니다.
• [숫자]는 배열 인덱스(음수는 뒤에서부터), [*]나 .*는 그 위치의 모든 값을 가리킵니다.
• ..는 모든 깊이를 재귀적으로 찾아 일치하는 값을 전부 모읍니다.
• 결과는 일치 개수와 관계없이 항상 배열로 나오고, 일치가 없으면 오류 대신 "일치하는 값이 없습니다"로 표시됩니다.
• 필터식 ?()과 슬라이스 [1:3]은 지원되지 않으며, 지원 범위를 벗어난 문법은 오류가 아니라 조용한 매칭 0건으로 나타납니다.

자주 묻는 질문

결과가 왜 항상 배열로 나오나요?

[*]나 ..는 여러 값을 한 번에 찾을 수 있어, 일치 개수와 관계없이 결과를 배열로 통일해 보여줍니다. $ 하나만 입력해 문서 전체를 가리킬 때도 원소 1개짜리 배열로 나옵니다.

필터식 ?()이나 슬라이스 [1:3]은 왜 지원하지 않나요?

이 도구는 $, .속성, ['속성'], [숫자], [*]·.*, .. 여섯 가지 문법만 해석합니다.

?()나 [1:3]처럼 이 범위를 벗어난 문법을 넣으면 오류가 아니라 대괄호 안 내용을 그대로 속성 이름으로 취급해 매칭 0건으로 처리됩니다.

입력한 JSON이 서버로 전송되나요?

아니요. JSON 파싱과 경로 평가 모두 브라우저 안에서만 이뤄지고, 입력한 데이터는 서버로 전송되거나 저장되지 않습니다.

음수 인덱스는 정확히 어떻게 계산되나요?

배열 길이에 음수 인덱스를 더한 값이 실제 위치가 됩니다. 예를 들어 원소가 2개인 배열에서 [-1]은 2 + (-1) = 1번, 즉 마지막 원소를 가리킵니다. 계산된 위치가 배열 범위를 벗어나면 매칭 0건이 됩니다.