JSON Toolkit

نحوه نوشتن آرایه و شیء JSON: ساختار و تودرتویی برای مبتدیان

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

مقدماتیحدود 6 دقیقه مطالعهانتشار 2026-11-20به‌روزرسانی 2026-11-20
جلد معرفی ساختارهای آرایه و شیء JSON

JSON فقط دو ظرف به شما می‌دهد: شیء فیلدهای نام‌دار را حمل می‌کند، آرایه فهرست‌های ترتیبی را — و تقریباً هر payload خراب با گیومه، ویرگول یا فهرستی که به شکل شیء قلابی نوشته شده توضیح داده می‌شود.

یک: JSON فقط دو ظرف دارد

هر چقدر هم پاسخ API پیچیده باشد، همه به دو ظرف و شش نوع مقدار فرو می‌کاهد. شیء مجموعه‌ای از جفت‌های کلید/مقدار درون آکولاد {} است؛ آرایه فهرستی ترتیبی از مقادیر درون براکت [] است. یک مقدار می‌تواند رشته، عدد، true، false، null باشد — یا باز هم شیء یا آرایه. شیء درون آرایه، آرایه درون شیء: همین بازگشت، تمام توان بیان JSON است.

{
  "user": { "name": "Ada", "active": true },
  "roles": ["admin", "editor"],
  "lastLogin": null,
  "loginCount": 42
}

از این، یک نتیجه عملی به دست می‌آید: وقتی payload گیج‌کننده است، آن را حرف به حرف نخوانید. اول ببینید بیرونی‌ترین کاراکتر { است یا [. اگر شیء است، آن را به‌عنوان فیلدهای نام‌دار بخوانید؛ اگر آرایه است، آن را به‌عنوان فهرست بخوانید و بعد سطح به سطح پایین بروید. نمودار دستوری json.org دقیقاً به همین دلیل در یک صفحه جا می‌شود که دو ساختار به‌علاوه بازگشت همه چیز را می‌پوشانند.

دو: نوشتن شیء، چهار قاعده سفت و سخت

شیءها جایی هستند که مبتدیان بیشترین اشتباه را می‌کنند، اما قواعد به چهار مورد فرو می‌کاهند:

  1. کلیدها باید رشته‌هایی در گیومه دوتایی باشند. {name: "Ada"} و {'name': 'Ada'} هر دو نامعتبرند؛ باید بنویسید {"name": "Ada"}. لیترال‌های شیء در JavaScript کلید برهنه و تک‌گیومه را مجاز می‌دانند، JSON نه — این رایج‌ترین اشتباه بین این دو است.
  2. جفت‌ها را با ویرگول جدا کنید و هرگز بعد از آخرین جفت ویرگول باقی نگذارید. {"a": 1, "b": 2,} با خطای Unexpected token } در آکولاد بسته شکست می‌خورد.
  3. کلیدها باید یکتا باشند. RFC 8259 این را SHOULD می‌گوید، نه MUST: کلیدهای تکراری خطا ایجاد نمی‌کنند، اما نگه داشتن مقدار اول یا آخر به پیاده‌سازی بستگی دارد و زبان‌ها اختلاف دارند. هرگز به آن تکیه نکنید.
  4. ترتیب کلیدها معنایی ندارد. {"a":1,"b":2} و {"b":2,"a":1} یک شیء واحدند؛ ابزارهای diff و توابع مقایسه ترتیب کلیدها را نادیده می‌گیرند. اگر ترتیب مهم است، داده‌ها به آرایه تعلق دارند.

سه: نوشتن آرایه، ترتیب خودش داده است

آرایه‌ها مقادیر را بر اساس موقعیت ذخیره می‌کنند و اندیس‌گذاری از 0 شروع می‌شود: در ["admin", "editor"] رشته "editor" همان [1] است. این ترتیب معنادار است — تفاوت اساسی آرایه و شیء همین‌جاست. نتایج جست‌وجوی مرتب‌شده بر اساس relevans، لاگ‌های مرتب بر اساس تاریخ: این اطلاعات فقط در توالی زندگی می‌کنند و تبدیل به شیء آن‌ها را نابود می‌کند.

دو توصیه عملی. اول، عناصر را همگن نگه دارید: [{"id":1},{"id":2}] بسیار آسان‌تر از [1, "text", true] مصرف می‌شود — آن دومی قانونی است اما هر مصرف‌کننده را وادار می‌کند در هر گام تایپ‌ها را آزمایش کند. دوم، آرایه خالی [] کاملاً مقدار معتبری است — وقتی فیلد فهرست هنوز محتوایی ندارد، به‌جای null مقدار [] صادر کنید تا مصرف‌کننده لازم نباشد اول وجود و بعد خالی بودن را بررسی کند.

[
  { "city": "Tokyo", "population": 13960000 },
  { "city": "Delhi", "population": 16780000 }
]

چهار: تودرتویی، چهار شکل payloadهای واقعی

داده‌های واقعی چیزی نیستند جز همین دو ظرف که درون یکدیگر تودرتو شده‌اند، و الگوها به چهار شکل فرو می‌کاهند:

شکل ظاهر کاربرد معمول
شیء شامل آرایه {"tags": ["a","b"]} فیلد فهرستی یک موجودیت
آرایه‌ای از شیءها [{"id":1},{"id":2}] فهرست رکوردها، نتایج صفحه‌بندی‌شده
شیء شامل شیء {"db": {"host": "..."}} پیکربندی گروه‌بندی‌شده، بلوک‌های نشانی
آرایه‌ای از آرایه‌ها [[1,2],[3,4]] ماتریس‌ها، ردیف‌های جدول

یک پاسخ معمول API شیء را به‌عنوان پوسته و آرایه را به‌عنوان محتوا به کار می‌گیرد:

{
  "code": 0,
  "data": {
    "items": [
      { "id": 1, "title": "first" },
      { "id": 2, "title": "second" }
    ],
    "page": 1,
    "total": 2
  }
}

بی‌دلیل تودرتو نکنید. بعد از سه یا چهار سطح، مسیرهای دسترسی ناخوانا می‌شوند و کد مصرف‌کننده به موازات آن باد می‌کند. فیلدهایی که همیشه با هم سفر می‌کنند به یک زیرشیء تعلق دارند: addrCity و addrZip را با address: {city, zip} جایگزین کنید.

پنج: شیء یا آرایه؟ یک جدول تصمیم

پرسش پاسخ چرا
هر مقدار نامی دارد؟ شیء دسترسی با کلید؛ افزودن یا حذف فیلد چیزی را نمی‌شکند
فهرستی از رکوردهای مشابه است؟ آرایه ترتیب مهم است؛ می‌توان map و filter کرد
جست‌وجوی سریع با کلید لازم است؟ شیء نمایه‌شده با شناسه دسترسی O(1) به‌جای پیمایش
چند ویژگی از یک موجودیت؟ شیء ویژگی‌ها ترتیب ذاتی ندارند
مجموعه در حال رشدِ موارد مشابه؟ آرایه طول آزادانه کش می‌آید

یک ضدمسیر شایان ذکر ویژه است: تقلید آرایه با شیئی که کلیدهایش "0"، "1"، "2" هستند. بدون خطا پارس می‌شود، اما شما معنای طول و ابزارهای پیمایش یک آرایه واقعی را از دست می‌دهید و مصرف‌کننده‌ها باید قبل از خواندن هر چیزی Object.keys را مرتب کنند. اگر کلیدها شماره‌های پیاپی هستند، یک آرایه واقعی بنویسید. برعکسش هم درست است: فهرستی از جفت‌های کلید/مقدار مثل [{"key":"theme","value":"dark"}] پایین‌تر از شیء {"theme": "dark"} است — مگر آنکه کلیدها واقعاً پویا باشند و نتوان از پیش اعلامشان کرد.

شش: سه خطای پرتکرار و پیام‌هایشان

شکل غلط خطای معمول اصلاح
ویرگول پایانی {"a":1,} Unexpected token } حذف آخرین ویرگول
تک‌گیومه / کلید برهنه {name:'Ada'} Unexpected token ' / Expected property name همیشه گیومه دوتایی برای کلید و رشته
لیترال‌های Python True / None Unexpected token T جایگزینی با true / null
آرایه قلابی با کلیدهای عددی بدون خطا، معنا غلط بازنویسی به آرایه واقعی

دو عادت دیباگ: پارسرها معمولاً موقعیتی بعد از کاراکتر مقصر را گزارش می‌کنند، پس وقتی position 42 می‌بینید، یک یا دو کاراکتر عقب‌تر را ببینید؛ و JSON عظیم تک‌خطی را اول فرمت کنید — شماره سطر و ستون همیشه بر آفست کاراکتر می‌برد. کاتالوگ کامل خطاها در جدول جست‌وجوی خطاهای JSON و فرایند گام‌به‌گام رسیدگی در چگونه خطاهای پارس JSON را رفع کنیم است.

هفت: بعد از نوشتن، ساختار را راستی‌آزمایی کنید

JSON دست‌نویس باید پیش از تحویل همیشه از پارسر عبور کند. سبک‌ترین بررسی یک خط دستور است:

python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK

آنلاین، محتوا را در صفحه قالب‌دهنده و اعتبارسنج JSON بچسبانید — خطاهای سینتکس با سطر و ستون برمی‌گردند. به نمای درختی بروید تا تایپ هر سطح را یک‌نگاهی ببینید: آیا عددی به‌عنوان رشته تفسیر شده، آیا طول آرایه‌ها می‌خواند. و وقتی مخاطب فنی نیست، payload آرایه-از-شیءها را می‌توان در صفحه JSON به جدول به ردیف و ستون گسترد — که ضمنش بررسی می‌شود داده‌هایتان واقعاً فهرستی منظم از رکوردهاست.

پرسش‌هایی درباره فیلدی که باید آرایه می‌شد، یا بازسازی تودرتویی بیش از حد عمیق، به مدل‌سازی تایپ‌ها مربوط‌اند — خواندن بعدی: شش تایپ، دقت عددی و دام‌های انکودینگ.

آیا آرایه و شیء JSON را می‌توان به یکدیگر تبدیل کرد؟

می‌توان، اما بدون اتلاف نه. تبدیل شیء به آرایه معمولاً یعنی تبدیل کلیدها به مقادیر و از دست دادن دسترسی با کلید؛ تبدیل آرایه به شیء می‌طلبد برای هر عنصر کلیدی بسازید، و خاستگاه آن کلیدها خودش مسئله طراحی تازه‌ای است. بر اساس اینکه مصرف‌کننده داده‌ها را چگونه می‌خواند تصمیم بگیرید، نه بر اساس راحتی سینتکسی.

آیا کلیدهای شیء می‌توانند تکراری باشند؟

از نظر سینتکسی بله — RFC 8259 فقط می‌گوید کلیدها SHOULD یکتا باشند. اما JavaScript مقدار آخر را نگه می‌دارد حال آنکه برخی کتابخانه‌های خانواده C اولی را نگه می‌دارند: رفتار بین پارسرها فرق می‌کند. در امضا، diff یا هش، کلیدهای تکراری اختلاف مستقیم می‌سازند. در سمت تولیدکننده از آن‌ها بپرهیزید و تکراری‌های منبع ناشناخته را ریسک سمت مصرف‌کننده بدانید.

آیا آرایه می‌تواند مقادیری از تایپ‌های مختلف داشته باشد؟

از نظر سینتکسی بله: [1, "a", true] یک JSON معتبر است. اما آرایه‌های ناهمگن مصرف‌کننده را در هر موقعیت به بررسی تایپ وادار می‌کنند و بیانشان در اسکیما دشوار است. جز ماتریس و تاپل — که در آن‌ها موقعیت همان معناست — آرایه‌ها را همگن نگه دارید.

چرا {name:'json'} در اعتبارسنجی شکست می‌خورد؟

چون JSON گیومه دوتایی دور هر کلید و هر مقدار رشته‌ای الزامی می‌داند. {name:'json'} یک لیترال شیء JavaScript است، نه JSON. آن را با {"name": "json"} جایگزین کنید تا اعتبارسنجی پاس شود. تک‌گیومه، کلید برهنه و کامنت مال گویش‌هایی مثل JSON5/JSONC هستند که به‌جای JSON.parse استاندارد پارسر خودشان را می‌طلبند.