What is JSONPath and what is it used for?

JSONPath is a query language for JSON, analogous to XPath for XML. It lets you extract values from a JSON document using path expressions. $.store.book[0].title selects the title of the first book. $.store.book[*].author selects all authors. $..price selects all price values at any depth. JSONPath is used in API testing (Postman, REST Assured), data transformation pipelines, AWS IAM policies, Kubernetes JSON patches, and observability tools for filtering JSON log data.

What is the difference between dot notation and bracket notation in JSONPath?

Both access the same values but have different capabilities. Dot notation: $.store.book.title — clean and readable, works for simple key names. Bracket notation: $.store['book']['title'] — required for keys with spaces, special characters, or numeric indices: $['my key']['0']. Bracket notation also supports expressions: $[?(@.price < 10)] (filter), $[0,2] (union), $[0:3] (slice). Mix both: $.store.book[0]['long key name'].

What are JSONPath filter expressions and how do I use them?

Filter expressions select elements that match a condition: $.store.book[?(@.price = (comparisons), && || (logical), =~ (regex match in some implementations). Examples: [?(@.category == 'fiction')] — filter by string equality; [?(@.isbn)] — filter elements that have an isbn property. Not all JSONPath implementations support all filter operators.

Is JSONPath standardized?

JSONPath was originally defined informally by Stefan Goessner in 2007. It was not an official standard until IETF RFC 9535 was published in 2024, which standardizes the syntax and semantics. Many implementations predate RFC 9535 and have minor differences — especially in filter expressions, recursive descent behavior, and how they handle edge cases. When interoperability matters, test your expressions against the specific library you will use (jsonpath-plus, Jayway for Java, jsonpath for Python).

آزمایشگر JSONPath

Q: What are JSONPath filter expressions and how do I use them?

Filter expressions select elements that match a condition: $.store.book[?(@.price = (comparisons), && || (logical), =~ (regex match in some implementations). Examples: [?(@.category == 'fiction')] — filter by string equality; [?(@.isbn)] — filter elements that have an isbn property. Not all JSONPath implementations support all filter operators.

Q: Is JSONPath standardized?

JSONPath was originally defined informally by Stefan Goessner in 2007. It was not an official standard until IETF RFC 9535 was published in 2024, which standardizes the syntax and semantics. Many implementations predate RFC 9535 and have minor differences — especially in filter expressions, recursive descent behavior, and how they handle edge cases. When interoperability matters, test your expressions against the specific library you will use (jsonpath-plus, Jayway for Java, jsonpath for Python).

عبارت JSONPath

ورودی JSON

نتایج

Loading editor...

نتیجه‌ای یافت نشد

نحو	توضیحات
$	شیء یا آرایهٔ ریشه
@	گرهٔ فعلی (در عبارات فیلتر استفاده می‌شود)
object.property	فرزند با نشانه‌گذاری نقطه‌ای
['object'].['property']	فرزند یا فرزندان با نشانه‌گذاری کروشه‌ای
..property	پیمایش بازگشتی
*	کاراکتر عام. همهٔ عناصر را انتخاب می‌کند
[n]	عنصر n‌ام را از یک آرایه انتخاب می‌کند
[n1,n2]	آیتم‌های n1 و n2 آرایه را انتخاب می‌کند (اجتماع)
[start:end:step]	عملگر برش آرایه
?(expression)	عبارت فیلتر
(expression)	عبارت اسکریپت

جزئیات فنی

تستر JSONPath چگونه کار می‌کند

این ابزار چه کاری انجام می‌دهد

آزمونگر JSONPath به شما اجازه می‌دهد داده‌های JSON تو‌در‌تو را با استفاده از عبارت‌های JSONPath پرس‌وجو کنید؛ مشابه کاری که XPath برای XML انجام می‌دهد. این آزمونگر jsonpath به‌عنوان یک تست‌کنندهٔ عبارت JSONPath و انتخاب‌گر JSON عمل می‌کند و به توسعه‌دهندگان کمک می‌کند مقادیر، آرایه‌ها یا آبجکت‌های مشخصی را از ساختارهای پیچیدهٔ JSON استخراج کنند. وقتی نیاز دارید jsonpath را آنلاین تست کنید، این ابزار همهٔ مقادیر منطبق و مسیرهایشان را نشان می‌دهد. این ابزار از نحو JSONPath پشتیبانی می‌کند، از جمله نشانه‌گذاری نقطه‌ای ( $.store.book)، نشانه‌گذاری براکت ( $['store']['book'])، وایلدکارت‌ها ( $..*)، برش آرایه و عبارت‌های فیلتر. این ابزار از معناشناسی jsonpath-plus پیروی می‌کند؛ پیاده‌سازی‌های JSONPath متفاوت‌اند، بنابراین اگر عبارت شما جای دیگری کار می‌کند اما اینجا نه، ممکن است تفاوتِ گویش باشد. این ابزار هم مقادیر منطبق و هم مسیرهای JSONPath را نمایش می‌دهد و فهمیدن اینکه عبارت‌ها چگونه در ساختارهای JSON حرکت می‌کنند را آسان می‌کند.

موارد استفادهٔ رایج برای توسعه‌دهندگان

توسعه‌دهندگان هنگام کار با پاسخ‌های API، فایل‌های پیکربندی یا ساختارهای دادهٔ JSON پیچیده و تو‌در‌تو از آزمونگرهای JSONPath استفاده می‌کنند. یک تست‌کنندهٔ عبارت JSONPath کمک می‌کند فیلدهای مشخصی را از آبجکت‌های عمیقاً تو‌در‌تو استخراج کنید، آرایه‌ها را بر اساس شرط فیلتر کنید یا همهٔ رخدادهای یک کلید خاص را پیدا کنید. بسیاری از توسعه‌دهندگان از آزمونگرهای JSONPath برای پرس‌وجوی دادهٔ JSON از REST APIها، تجزیهٔ فایل‌های لاگ یا پیمایش آبجکت‌های پیکربندی پیچیده استفاده می‌کنند. این ابزار هنگام دیباگ کردن تبدیل‌های داده، اعتبارسنجی پاسخ‌های API یا درک شِمای پیچیدهٔ JSON ارزشمند است. پیش از اجرای پرس‌وجوهای JSONPath، ممکن است بخواهید برای خوانایی بهتر JSON خود را با قالب‌بند JSON فرمت کنید. برای فایل‌های پیکربندی، مبدل JSON ↔ YAML می‌تواند به تبدیل بین قالب‌ها کمک کند. هنگام بررسی داده‌های آرایه‌ای، ابزار تبدیل آرایهٔ JSON به جدول می‌تواند نتایج را به قالب جدولی برای تحلیل آسان‌تر خروجی بگیرد.

قالب‌ها، نوع‌ها یا گونه‌های داده

JSONPath چندین روش برای پیمایش ساختارهای JSON فراهم می‌کند. این ابزار از انتخاب‌گر ریشه ($)، انتخاب‌گرهای فرزند (. یا [])، انتخاب‌گرهای نواده ( ..)، اندیس‌گذاری آرایه ([0]، [-1]) و برش آرایه ( [0:3]) پشتیبانی می‌کند. عبارت‌های رایج JSONPath که توسعه‌دهندگان استفاده می‌کنند:

$.items[*].id — استخراج همهٔ فیلدهای id از آرایهٔ items
$..id— یافتن همهٔ فیلدهای id در هر سطح تو‌در‌تویی
$['key-with-dash'] — دسترسی به کلیدهایی با کاراکترهای ویژه
$..book[?(@.price < 10)].title — فیلتر کردن کتاب‌ها بر اساس قیمت و استخراج عنوان‌ها

این عبارت‌ها نشان می‌دهند JSONPath چگونه می‌تواند آرایه‌های تو‌در‌تو را پرس‌وجو کند، آبجکت‌ها را بر اساس شرط فیلتر کند و فیلدهای مشخصی را از ساختارهای پیچیده استخراج کند.

دام‌های رایج و حالت‌های لبه‌ای

یکی از اشتباهات رایج، اشتباه گرفتن JSONPath با دسترسی به ویژگی‌های آبجکت در جاوااسکریپت است، چون JSONPath برای فیلتر کردن آرایه و وایلدکارت‌ها از نحو متفاوتی استفاده می‌کند. مسئلهٔ دیگر این است که چه زمانی از نشانه‌گذاری نقطه‌ای در برابر نشانه‌گذاری براکت استفاده شود: نشانه‌گذاری نقطه‌ای برای کلیدهای ساده کار می‌کند، اما برای کلیدهایی با کاراکترهای ویژه یا هنگام استفاده از عبارت‌ها، نشانه‌گذاری براکت لازم است. اندیس‌گذاری آرایه می‌تواند دشوار باشد: اندیس‌های منفی مثل [-1] به آخرین عنصر اشاره می‌کنند، اما همهٔ پیاده‌سازی‌های JSONPath از این مورد پشتیبانی نمی‌کنند. عبارت‌های فیلتر باید از عملگرهای مقایسهٔ درست استفاده کنند و آیتم جاری را با @ ارجاع دهند. انتخاب‌گرهای نواده (..) اگر عناصر بیشتری از حد انتظار را منطبق کنند، می‌توانند نتایج غیرمنتظره برگردانند. توسعه‌دهندگان باید عبارت‌های JSONPath را با ساختارهای مختلف JSON، از جمله حالت‌های لبه مانند آرایه‌های خالی، مقادیر null و آبجکت‌های عمیقاً تو‌در‌تو، آزمایش کنند. برخی پیاده‌سازی‌های JSONPath تفاوت‌های ظریفی در نحوهٔ رسیدگی به حالت‌های لبه دارند، بنابراین تست کردن ضروری است.

خطاها و اعتبارسنجی

هنگام کار با JSONPath، چندین وضعیت خطا ممکن است رخ دهد. ورودی JSON نامعتبر پیش از ارزیابی عبارت JSONPath باعث خطای تجزیه می‌شود. عبارت‌های JSONPath نامعتبر یک پیام خطا برمی‌گردانند که نشان می‌دهد مشکلِ نحو چیست. وقتی عبارت با هیچ مقداری در ساختار JSON منطبق نشود، نتیجهٔ خالی به‌صورت یک آرایهٔ خالی برگردانده می‌شود—این رفتار عادی است، نه خطا. این ابزار هم نحو JSON و هم نحو عبارت JSONPath را اعتبارسنجی می‌کند و برای ورودیِ بدشکل پیام‌های خطای واضح ارائه می‌دهد. اگر عبارت JSONPath شما معتبر است اما هیچ نتیجه‌ای برنمی‌گرداند، ممکن است عبارت با ساختار دادهٔ JSON شما منطبق نباشد یا داده شامل فیلدهای مورد انتظار نباشد.

چه زمانی از این ابزار استفاده کنیم در برابر کُد

از این آزمونگر JSONPath برای توسعهٔ سریع پرس‌وجو، دیباگ کردن عبارت‌های پیچیده یا کاوش ساختارهای دادهٔ JSON استفاده کنید. این ابزار برای تست عبارت‌های JSONPath پیش از پیاده‌سازی در کد ایده‌آل است، به‌خصوص هنگام کار با APIهای ناآشنا یا داده‌های تو‌در‌تو و پیچیده. بازخورد بصری کمک می‌کند مشخص شود چرا عبارت‌ها با دادهٔ خاصی منطبق می‌شوند یا نمی‌شوند. برای کد تولیدی، از کتابخانه‌های JSONPath که در برنامهٔ شما یکپارچه شده‌اند استفاده کنید تا دادهٔ JSON را به‌صورت کارآمد پردازش کنند. ابزارهای مرورگر در توسعه و کاوش تعاملی عالی هستند، در حالی که راهکارهای مبتنی بر کد کارایی، ایمنی نوع و یکپارچگی با پایپ‌لاین‌های پردازش داده را فراهم می‌کنند. برای مجموعه‌داده‌های بزرگ یا برنامه‌های با کارایی بالا، پیاده‌سازی‌های بومی JSONPath در زبان برنامه‌نویسی شما عملکرد بهتری نسبت به ابزارهای مبتنی بر مرورگر ارائه می‌دهند.