JSON چیست؟ راهنمای ساده با مثال

JSON (JavaScript Object Notation) یک قالب متنی ساده برای نوشتن داده ساختارمند است، مثل یک مشتری، یک سفارش یا فهرست محصولات، به‌صورت نام‌هایی که به مقدار وصل شده‌اند. خواندنش برای انسان آسان است و برای برنامه‌ها تولید و تجزیه‌اش راحت. وقتی اپ‌ها و سرویس‌ها روی وب داده رد و بدل می‌کنند، JSON با فاصله رایج‌ترین قالب است.

چرا JSON وقتی با هوش مصنوعی می‌سازید مهم است

حتی اگر هرگز کد ننویسید، مدام با JSON روبه‌رو می‌شوید:

• APIها. وقتی صفحه‌های اپ داده را از بک‌اند می‌گیرند، یا بک‌اند شما یک سرویس پرداخت، ایمیل یا هوش مصنوعی را صدا می‌زند، داده معمولاً به‌صورت JSON جابه‌جا می‌شود. ببینید API چیست.
• فایل‌های تنظیمات. بسیاری از فایل‌های پیکربندی پروژه JSON هستند؛ مثلاً package.json که وابستگی‌های یک پروژه JavaScript را فهرست می‌کند.
• پایگاه داده. Postgres می‌تواند JSON را در یک ستون (نوع jsonb) ذخیره کند، برای داده‌هایی که در سطر و ستون مرتب جا نمی‌شوند. ببینید Postgres چیست.
• خروجی هوش مصنوعی. وقتی می‌خواهید یک مدل هوش مصنوعی چیزی برگرداند که برنامه بتواند از آن استفاده کند، مثل فهرست برچسب‌ها یا فیلدهای استخراج‌شده از فاکتور، معمولاً JSON درخواست می‌کنید.
• پیام‌های خطا و لاگ‌ها. بسیاری از خطاها به‌صورت JSON می‌رسند و خواندنشان اغلب سریع‌ترین راه برای فهمیدن مشکل است.

خواندن JSON به شما امکان می‌دهد ببینید اپ واقعاً چه داده‌ای دریافت کرده، فیلد جاافتاده را پیدا کنید و مشکل را دقیق برای ابزار ساختتان توضیح دهید.

یک مثال روزمره

به یک فرم کاغذی فکر کنید: نام: ____، تلفن: ____، خبرنامه: ☐ بله ☐ خیر. هر ورودی یک برچسب است که کنارش یک مقدار نوشته شده. JSON همان فرم است که به‌صورت متن و در یک چیدمان سخت‌گیرانه نوشته شده تا کامپیوتر بدون حدس زدن بخواندش. و مثل فرم‌ها، JSON می‌تواند بخش‌هایی داخل بخش‌ها داشته باشد (یک بلوک آدرس با خیابان، شهر و کد پستی) و فهرست‌ها (چند شماره تلفن).

JSON چه شکلی است

این یک رزرو در JSON است:

{
  "id": 5001,
  "customer": "Lena Park",
  "service": "Haircut",
  "startsAt": "2026-10-03T14:00:00Z",
  "price": 35.5,
  "paid": false,
  "notes": null,
  "extras": ["beard trim", "hot towel"],
  "contact": {
    "email": "lena@example.com",
    "phone": "+44 20 7946 0000"
  }
}

خواندنش:

• آکولادهای { } یک شیء را دربرمی‌گیرند؛ مجموعه‌ای از جفت‌های نام و مقدار.
• هر جفت به شکل "name": value است و با ویرگول از هم جدا می‌شوند.
• براکت‌های [ ] یک آرایه را دربرمی‌گیرند؛ فهرستی مرتب.
• شیء‌ها و آرایه‌ها می‌توانند داخل هم قرار بگیرند، مثل contact و extras.

شش نوع مقدار

JSON فقط شش نوع مقدار دارد. همین فهرست کوتاه بخش بزرگی از دلیل کار کردنش در همه جاست.

نوع تاریخ وجود ندارد. تاریخ‌ها به‌صورت رشته نوشته می‌شوند، معمولاً در قالب ISO 8601 که بالاتر دیدید (2026-10-03T14:00:00Z، که Z یعنی UTC). توافق روی این قالب از یک دسته کامل باگ‌های منطقه زمانی جلوگیری می‌کند.

قواعد سخت‌گیرانه (خطاها از اینجا می‌آیند)

JSON از آنچه به نظر می‌رسد سخت‌گیرتر است. همه این‌ها نامعتبرند:

{ name: "Lena" }            ← کلید بدون نقل قول دوتایی
{ 'name': 'Lena' }          ← نقل قول تکی
{ "a": 1, "b": 2, }         ← ویرگول اضافی
{ "a": 1 "b": 2 }           ← ویرگول جاافتاده
{ "a": 1 // comment }       ← کامنت مجاز نیست

بیشتر خطاهای «Unexpected token» که می‌بینید یکی از این‌هاست. یک اعتبارساز یا فرمت‌کننده JSON خط دقیق را نشان می‌دهد.

یک مثال کامل: JSON در مسیر یک اپ

یک مشتری در یک اپ آرایشگاه نوبت یک اصلاح مو رزرو می‌کند. این‌جاست که JSON ظاهر می‌شود:

1. فرم رزرو این را به بک‌اند اپ می‌فرستد:

{ "service": "Haircut", "startsAt": "2026-10-03T14:00:00Z", "name": "Lena Park" }

1. بک‌اند رزرو را در پایگاه داده ذخیره می‌کند و با وضعیت 201 Created و این پاسخ جواب می‌دهد:

{ "id": 5001, "status": "confirmed" }

1. اگر آن زمان قبلاً گرفته شده بود، ممکن است با وضعیت 409 Conflict و این پاسخ جواب دهد:

{ "error": "slot_taken", "message": "That time was just booked. Please pick another." }

صفحه فیلد status یا error را می‌خواند و پیام درست را نشان می‌دهد. اگر به جای آن صفحه خالی نشان داده می‌شد، باز کردن ابزارهای توسعه‌دهنده مرورگر (تب Network) همین JSON را نشانتان می‌داد، که اغلب سریع‌ترین سرنخ برای فهمیدن مشکل است.

اصطلاحات کلیدی

تصورات غلط رایج

• «JSON همان JavaScript است.» از نحو JavaScript آمده، اما مستقل از زبان است؛ Python، Java، C#، Go و بقیه همه آن را می‌خوانند.
• «عددهای داخل نقل قول اشکالی ندارند.» "35" یک رشته است، نه عدد. ترکیب آن‌ها باعث باگ می‌شود، مثلاً "35" + "5" می‌شود "355". پول اغلب بهتر است به‌صورت سنت صحیح (3550) ذخیره شود تا مشکلات گرد کردن پیش نیاید.
• «JSON امن است چون فقط داده است.» JSON می‌تواند هر چیزی از جمله رمز را حمل کند. کلید API را در JSON‌ای که به مرورگر فرستاده می‌شود نگذارید.
• «همه چیز را در یک ستون JSON بریزید.» برای فیلدهای انعطاف‌پذیر اضافی خوب است، اما داده‌ای که قرار است جستجو، فیلتر یا join شود معمولاً باید در ستون‌های واقعی باشد.
• «هوش مصنوعی همیشه JSON معتبر برمی‌گرداند.» مدل‌ها ممکن است متن اضافه کنند یا قالب را خراب کنند. بسیاری از ارائه‌دهندگان حالت خروجی ساختارمند دارند، اما کد شما باید باز هم آنچه برمی‌گردد را بررسی کند.

از ابزار ساخت با هوش مصنوعی‌تان چه بخواهید

• «نمونه JSONی که این endpoint برمی‌گرداند را نشانم بده.»
• «خطاها را به‌صورت JSON با یک کد error و یک message قابل خواندن برای انسان برگردان.»
• «تاریخ‌ها را به‌صورت رشته ISO 8601 در UTC ذخیره کن و فقط روی صفحه به وقت محلی تبدیل کن.»
• «قیمت‌ها را به‌صورت سنت صحیح ذخیره کن.»
• «JSON ورودی را در سرور اعتبارسنجی کن و درخواست‌هایی با فیلد جاافتاده یا نوع اشتباه را رد کن.»
• «وقتی مدل هوش مصنوعی را صدا می‌زنی، JSON را با این شکل دقیق درخواست کن و قبل از استفاده بررسی‌اش کن.»

JSON در Mythex

لازم نیست در Mythex JSON را دستی بنویسید؛ آنچه می‌خواهید را توصیف می‌کنید و عامل کدی می‌نویسد که آن را ارسال و دریافت می‌کند. با این حال شناختن آن کمک می‌کند: وقتی چیزی خراب می‌شود، چسباندن خطای JSON در چت سرنخ دقیقی به عامل می‌دهد. دستور REST API backend در مستندات از همان ابتدا «خطاهای JSON واضح» را درخواست می‌کند، و دستور integrate any API به فراخوانی سرویس‌های بیرونی می‌پردازد. برای تصویر بزرگ‌تر، ببینید REST در برابر GraphQL و چطور یک اپ ساخته‌شده با هوش مصنوعی را دیباگ کنیم.

پرسش‌ها