JSONPath란 무엇인가요?

JSONPath는 JSON 문서에서 값을 추출하기 위한 쿼리 언어입니다. 2007년 Stefan Goessner가 XML의 XPath에 대응하는 개념으로 처음 제안했으며, JSONPath를 사용하면 $.store.book[*].author와 같은 표현식으로 반복문이나 수동 탐색 코드 없이 book 배열 안의 모든 author 필드를 선택할 수 있습니다. 이 언어는 2024년 2월 IETF가 발표한 RFC 9535로 표준화되었습니다.

JSONPath 표현식은 항상 문서의 루트를 나타내는 $로 시작합니다. 그 다음 셀렉터를 연결합니다. 객체 키에는 점 표기법, 배열 인덱스에는 대괄호 표기법, 모든 자식 요소에는 와일드카드, 중첩의 모든 레벨을 탐색하려면 재귀 하강 연산자(..)를 사용합니다. [?(@.price < 10)]과 같은 필터 표현식으로 값에 대한 조건을 기반으로 요소를 선택할 수 있습니다.

JSONPath는 Postman과 같은 API 테스트 도구, Datadog 및 Splunk 같은 옵저버빌리티 플랫폼, Apache NiFi 같은 워크플로 엔진, 그리고 JavaScript, Python, Go, Java, C# 전반의 프로그래밍 라이브러리에서 활용됩니다. 코드나 설정 파일에 표현식을 넣기 전에 실제 데이터로 테스트하면 JSON 구조가 예상과 다를 때 발생하는 조용한 오류를 방지할 수 있습니다.

이 JSONPath 테스터를 사용하는 이유

JSONPath 표현식을 직접 작성하면 오류가 발생하기 쉽습니다. 점 하나가 빠지거나 잘못된 대괄호 유형, 또는 잘못된 필터 문법은 아무런 오류 메시지 없이 빈 결과를 반환할 수 있습니다. 이 도구는 표현식이 무엇과 일치하는지 즉각적인 시각적 피드백을 제공합니다.

⚡

즉각적인 결과

JSON을 붙여넣고 표현식을 입력하면 실시간으로 일치하는 값이 업데이트됩니다. 쿼리를 확인하기 위해 스크립트를 실행하거나 페이지를 새로 고칠 필요가 없습니다.

🔒

프라이버시 우선

모든 평가는 브라우저 내에서 실행됩니다. JSON 데이터는 사용자의 기기를 벗어나지 않으므로 프로덕션 API 응답이나 자격 증명이 포함된 설정 파일에 대한 표현식을 안전하게 테스트할 수 있습니다.

📋

결과 바로 복사

클릭 한 번으로 일치하는 출력을 JSON으로 복사하세요. 재포맷 없이 테스트 어설션, 문서, 또는 API 응답 예제에 바로 붙여넣을 수 있습니다.

🛠️

별도 설정 불필요

npm 패키지를 설치하거나 Python 가상 환경을 만들 필요가 없습니다. 페이지를 열고 데이터를 붙여넣은 다음 쿼리를 시작하세요. 브라우저가 있는 모든 기기에서 작동합니다.

JSONPath 활용 사례

프론트엔드 개발

API 응답에서 React 상태나 Vue 계산 속성에 연결하기 전에 필요한 중첩 값을 정확히 추출하세요. 실제 API 페이로드에서 경로 표현식을 먼저 테스트하세요.

백엔드 API 테스트

Postman과 REST-assured는 JSONPath를 사용해 응답 본문을 어설션합니다. 테스트 스크립트에 복사하기 전에 여기서 어설션 표현식을 작성하고 검증해 디버그 사이클을 줄이세요.

DevOps 설정

Kubernetes 커스텀 리소스 정의, AWS Step Functions, Terraform 데이터 소스는 JSON 출력에서 값을 추출하기 위해 JSONPath 표현식을 허용합니다. 배포 전에 경로를 검증하세요.

QA 테스트 자동화

계약 테스트 및 통합 테스트를 위한 JSONPath 기반 어설션을 작성하세요. JSON 구조에 선택적 또는 null 가능 필드가 있을 때 표현식이 예상 값과 올바르게 일치하는지 확인하세요.

데이터 파이프라인 추출

Apache NiFi, Logstash, 커스텀 ETL 스크립트는 JSONPath를 사용해 반정형 로그 데이터 및 이벤트 스트림에서 필드를 추출합니다. 파이프라인 배포 전에 샘플 페이로드로 표현식을 테스트하세요.

학습 및 실험

JSONPath를 처음 배우는 학생이나 개발자는 로컬 환경 없이 샘플 JSON에 다양한 표현식을 시도하며 와일드카드, 재귀 하강, 필터가 어떻게 동작하는지 이해할 수 있습니다.

JSONPath 구문 참조

RFC 9535는 표준 JSONPath 구문을 정의합니다. 아래 표는 대부분의 쿼리에서 사용하게 될 연산자를 다룹니다. 모든 표현식은 $(루트 노드)로 시작하며 하나 이상의 셀렉터를 연결해 문서 구조를 탐색합니다.

연산자	설명	예시
$	Root element	$.store
.key	Child property	$.store.book
[n]	Array index (zero-based)	$.store.book[0]
[*]	All elements in array/object	$.store.book[*]
..	Recursive descent	$..author
[start:end]	Array slice	$.store.book[0:2]
[?()]	Filter expression	$.store.book[?(@.price<10)]
@	Current node (inside filter)	$.store.book[?(@.isbn)]

JSONPath vs jq vs XPath

JSONPath, jq, XPath는 동일한 문제(구조화된 데이터 쿼리)를 서로 다른 형식과 사용 사례에서 해결합니다. JSONPath는 JSON을 대상으로 하며 대부분의 언어에서 라이브러리로 제공됩니다. jq는 자체 튜링 완전 필터 언어를 가진 독립 실행형 CLI 도구입니다. XPath는 XML을 대상으로 하며 W3C 사양 스택의 일부입니다.

기능	JSONPath	jq	XPath
데이터 형식	JSON	JSON	XML
첫 번째 요소 접근	$.store.book[0]	.store.book[0]	/store/book[1]
재귀 검색	$..price	.. \| .price?	//price
필터 표현식	[?(@.price<10)]	select(.price < 10)	[price<10]
사양	RFC 9535	stedolan.github.io	W3C XPath 3.1

코드 예제

인기 있는 언어와 도구에서 JSONPath 표현식을 평가하는 방법입니다. 각 예제는 비교를 위해 동일한 bookstore JSON 구조를 사용합니다.

JavaScript (jsonpath-plus)

import { JSONPath } from 'jsonpath-plus';

const data = {
  store: {
    book: [
      { title: 'Moby Dick', price: 8.99 },
      { title: 'The Great Gatsby', price: 12.99 }
    ]
  }
};

// Get all book titles
JSONPath({ path: '$.store.book[*].title', json: data });
// → ['Moby Dick', 'The Great Gatsby']

// Recursive descent — find every price in the document
JSONPath({ path: '$..price', json: data });
// → [8.99, 12.99]

// Filter — books under $10
JSONPath({ path: '$.store.book[?(@.price < 10)]', json: data });
// → [{ title: 'Moby Dick', price: 8.99 }]

Python (jsonpath-ng)

from jsonpath_ng.ext import parse
import json

data = {
    "store": {
        "book": [
            {"title": "Moby Dick", "price": 8.99},
            {"title": "The Great Gatsby", "price": 12.99}
        ]
    }
}

# Get all book titles
expr = parse("$.store.book[*].title")
titles = [match.value for match in expr.find(data)]
# → ['Moby Dick', 'The Great Gatsby']

# Recursive descent — all prices
expr = parse("$..price")
prices = [match.value for match in expr.find(data)]
# → [8.99, 12.99]

# Filter — books under $10
expr = parse("$.store.book[?price < 10]")
cheap = [match.value for match in expr.find(data)]
# → [{"title": "Moby Dick", "price": 8.99}]

Go (ohler55/ojg)

package main

import (
    "fmt"
    "github.com/ohler55/ojg/jp"
    "github.com/ohler55/ojg/oj"
)

func main() {
    src := `{
        "store": {
            "book": [
                {"title": "Moby Dick", "price": 8.99},
                {"title": "The Great Gatsby", "price": 12.99}
            ]
        }
    }`

    obj, _ := oj.ParseString(src)

    // Get all book titles
    expr, _ := jp.ParseString("$.store.book[*].title")
    results := expr.Get(obj)
    fmt.Println(results)
    // → [Moby Dick The Great Gatsby]

    // Recursive descent — all prices
    expr2, _ := jp.ParseString("$..price")
    fmt.Println(expr2.Get(obj))
    // → [8.99 12.99]
}

CLI (jq alternative syntax)

# jq uses its own syntax, not JSONPath, but solves the same problem.
# Mapping common JSONPath patterns to jq:

# $.store.book[*].title → get all titles
echo '{"store":{"book":[{"title":"Moby Dick"},{"title":"Gatsby"}]}}' | \
  jq '.store.book[].title'
# → "Moby Dick"
# → "Gatsby"

# $..price → recursive descent for "price" keys
echo '{"a":{"price":1},"b":{"price":2}}' | \
  jq '.. | .price? // empty'
# → 1
# → 2

# Filter: books where price < 10
echo '{"store":{"book":[{"title":"A","price":8},{"title":"B","price":12}]}}' | \
  jq '.store.book[] | select(.price < 10)'
# → {"title":"A","price":8}

자주 묻는 질문

JSONPath와 jq의 차이점은 무엇인가요?

JSONPath는 라이브러리로서 애플리케이션에 내장되도록 설계된 쿼리 언어입니다. 경로 표현식을 사용해 JSON 문서에서 일치하는 값을 반환합니다. jq는 조건문, 함수, 문자열 보간 등을 포함한 완전한 프로그래밍 언어로 JSON을 변환하는 독립 실행형 CLI 도구입니다. Postman 같은 도구나 코드에 쿼리를 내장할 때는 JSONPath를 사용하고, 임시 커맨드라인 데이터 변환에는 jq를 사용하세요.

JSONPath는 공식 표준인가요?

네. IETF는 2024년 2월 RFC 9535("JSONPath: Query Expressions for JSON")를 발표했습니다. 그 이전에 JSONPath는 2007년 Stefan Goessner의 비공식 사양으로만 존재했고, 이로 인해 구현 간 불일치가 발생했습니다. RFC 9535는 상호 운용성을 위한 구문, 의미론, 정규화 형식을 정의합니다.

JSONPath에서 재귀 하강(..)은 어떻게 동작하나요?

재귀 하강 연산자(..)는 JSON 문서의 모든 레벨에서 뒤에 오는 키를 검색합니다. 예를 들어 $..price는 깊이에 상관없이 "price" 키와 연결된 모든 값을 반환합니다. 이는 일치하는 노드를 수집하는 깊이 우선 탐색과 동일합니다. 대용량 문서에서 재귀 하강은 많은 결과를 반환할 수 있고 직접 경로보다 느릴 수 있습니다.

JSONPath로 JSON 데이터를 수정할 수 있나요?

아니요. JSONPath는 읽기 전용 쿼리 언어입니다. 값을 선택하고 반환하지만 노드를 삽입, 업데이트, 삭제할 수 없습니다. JSONPath 표현식을 기반으로 JSON을 수정하려면 쿼리 후 프로그래밍 언어의 JSON 조작 함수를 사용해야 합니다. Python의 jsonpath-ng 같은 일부 라이브러리는 매치 객체에 set() 메서드를 제공하지만, 이는 JSONPath 사양의 일부가 아닌 라이브러리 확장 기능입니다.

JSONPath 필터 표현식에서 @ 기호는 무엇을 의미하나요?

@ 기호는 필터 표현식에서 현재 평가 중인 노드를 나타냅니다. $.store.book[?(@.price < 10)]에서 필터는 book 배열의 각 요소를 반복하며, @는 각 book 객체를 차례로 나타냅니다. @.price는 현재 book의 price 필드에 접근합니다. @ 없이는 필터가 어느 노드의 속성을 확인해야 할지 알 수 없습니다.

JSONPath에서 특수 문자나 공백이 포함된 키는 어떻게 처리하나요?

따옴표와 함께 대괄호 표기법을 사용하세요: $['store']['book title']. 대괄호 표기법은 점, 공백, 유니코드 문자가 포함된 키를 포함해 모든 키에 적용됩니다. 점 표기법($.store.key)은 유효한 식별자(문자, 숫자, 밑줄)인 키에만 적용됩니다. RFC 9535는 구현이 작은따옴표와 큰따옴표 대괄호 표기법을 모두 지원하도록 요구합니다.

JSONPath 표현식이 빈 결과를 반환하는 이유는 무엇인가요?

가장 일반적인 원인은 키 이름 오타(JSONPath는 대소문자를 구분함), 특수 문자가 포함된 키에 점 표기법 사용, 시작 부분에 $ 루트 기호 누락, 또는 단일 객체인 값을 배열로 잘못 가정하는 것입니다. JSON을 테스터 도구에 붙여넣고 먼저 더 단순한 하위 표현식(예: $.store)으로 시작해 더 많은 셀렉터를 추가하기 전에 경로의 각 세그먼트가 올바르게 해석되는지 확인하세요.

JSONPath 테스터