JSON و ساختار داده

JSON را بخوان و بنویس، مسیر رسیدن به یک فیلد تودرتو را پیدا کن، ایرادهای نحوی و معنایی را تشخیص بده و داده تودرتو را به ردیف جدول تبدیل کن.

بعد از این درس می‌توانی

  • شش نوع مقدار JSON را بشناسد و برای یک داده کسب‌وکاری نوع مناسب هر فیلد را انتخاب کند.
  • مسیر رسیدن به یک فیلد در JSON تودرتو را بنویسد (مثل data[0].items[0].title).
  • ایرادهای نحوی (ویرگول اضافه، نقل‌قول تکی) و معنایی (عدد به‌شکل رشته، شیء به‌جای آرایه، کلید تکراری) را تشخیص بدهد.
  • داده تودرتو را با قاعده روشن به ردیف‌های جدول تبدیل کند و خطر شمارش دوباره را ببیند.

چرا این درس مهم است

همکار برگ سبز گزارش فروش هفته را از API سفارش‌ها گرفت و در صفحه‌گسترده جمع زد: فروش هفته دو برابر شده بود. جشن کوتاهی بود. سفارش‌هایی که چند کتاب داشتند، برای هر کتاب یک ردیف گرفته بودند و مبلغ کل سفارش در هر ردیف تکرار شده بود؛ جمع ستون، هر سفارش چندکتابی را چند بار شمرده بود.

داده‌ای که بین API‌ها، n8n و مدل‌های زبانی جابه‌جا می‌شود، تقریباً همیشه JSON است. خواندنش ساده به نظر می‌رسد؛ اما بیشتر خطاهای ورک‌فلو نه از قطع شبکه، که از «فکر می‌کردم این فیلد عدد است» و «فکر می‌کردم این یک فهرست است» می‌آیند. این درس دقیق‌خواندن JSON و تبدیل درستش به جدول را تمرین می‌کند.

مفاهیم کلیدی

یادآوری: در دوره پایه JSON Schema را برای قرارداد خروجی مدل دیدی؛ اینجا خود JSON را دقیق‌تر می‌بینی.

  • JSON (جی‌سان): قالب متنی استاندارد برای تبادل داده با شیء، آرایه، رشته، عدد، بولی و null.
  • JSON Object (شیء JSON): مجموعه‌ای از جفت‌های نام و مقدار داخل {}.
  • JSON Array (آرایه JSON): فهرست مرتب مقدارها داخل [].
  • Nested Data (داده تودرتو): شیء یا آرایه‌ای داخل شیء یا آرایه دیگر.
  • Field Path (مسیر فیلد): نشانی رسیدن به یک مقدار تودرتو؛ مثل data[0].items[0].title.
  • Flattening (مسطح‌سازی): تبدیل داده تودرتو به ردیف‌های یک جدول با قاعده مشخص.

مدل ذهنی

JSON را مثل پوشه‌های تودرتوی بایگانی ببین. شیء یک پوشه با برچسب‌هاست (هر برچسب یک نام، هر محتوا یک مقدار). آرایه یک قفسه با جای شماره‌دار است که از صفر شمرده می‌شود. مسیر فیلد، آدرس برگه در بایگانی است: «پوشه data، جای صفرم، پوشه items، جای صفرم، برگه title».

ساختار تودرتوی پاسخ فهرست سفارش‌ها: شیء ریشه سه فیلد دارد؛ data یک آرایه از سفارش‌هاست؛ هر سفارش شیئی با شناسه، وضعیت و آرایه items است؛ هر قلم شیئی با عنوان و تعداد است.

ساختار تودرتوی پاسخ فهرست سفارش‌ها

این تشبیه کجا غلط است؟ در بایگانی واقعی، برچسب تکراری در یک پوشه اتفاق نمی‌افتد. در JSON ممکن است بیفتد: RFC 8259 می‌گوید نام‌ها در یک شیء «باید» یکتا باشند، ولی آن را اجبار نحوی نمی‌کند و رفتار نرم‌افزار گیرنده در نام تکراری قابل پیش‌بینی نیستsrc-rfc8259-json. یعنی بایگانی JSON ممکن است دو برگه با یک برچسب داشته باشد و هر خواننده یکی را بردارد.

گام‌به‌گام

گام ۱: شش نوع مقدار

JSON چهار نوع ساده (رشته، عدد، بولی، null) و دو نوع ساختاری (شیء و آرایه) دارد؛ true، false و null باید با حروف کوچک نوشته شوندsrc-rfc8259-json.

نوعنمونهبرای چه فیلدی
رشته"BS-1001"شناسه، متن، تاریخ (به‌شکل "2026-10-10T09:30:00Z")
عدد420000مبلغ، تعداد (بدون نقل‌قول، با رقم لاتین)
بولیtrueبله یا نه: فوری است؟
nullnull«مقدار معلوم نیست»؛ متفاوت با رشته خالی
شیء{"title": "...", "qty": 1}یک چیز با چند ویژگی
آرایه[{...}, {...}]چند چیز هم‌جنس

دو نکته که در ورک‌فلوهای فارسی زیاد پیش می‌آید:

  • شماره تلفن و کد پستی رشته‌اند، نه عدد. با آن‌ها حساب نمی‌کنی و صفر اولشان مهم است.
  • عدد با رقم فارسی داخل نقل‌قول، عدد نیست. "۱۸۵۰۰۰" یک رشته است؛ جمع‌زدنش یا خطا می‌دهد یا رشته‌ها را کنار هم می‌چسباند.

گام ۲: مسیر فیلد

در assets/orders-page-1.json:

  • data آرایه سفارش‌هاست.
  • data[0].id می‌شود BS-1001.
  • data[0].items[0].title می‌شود «کتاب نمونه یک».
  • data[1].carrier می‌شود null.

شمارش آرایه از صفر است. در n8n همین مسیرها را داخل Expression می‌نویسی؛ در Python با doc["data"][0]["items"][0]["title"].

گام ۳: دو نوع ایراد

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

دقت عدد هم نکته‌ای معنایی است: RFC 8259 فقط اعداد صحیح در بازه حدود منفی تا مثبت ۹ کوادریلیون (2^53 منهای یک) را به‌طور قابل اعتماد بین سامانه‌ها هم‌خوان می‌داندsrc-rfc8259-json. شناسه‌های عددی خیلی بلند را رشته بفرست.

گام ۴: فارسی در JSON

JSON بین سامانه‌های جدا باید با UTF-8 کدگذاری شودsrc-rfc8259-json. متن فارسی را می‌شود مستقیم نوشت ("کتاب") یا به‌شکل کد ("کتاب")؛ هر دو یک رشته‌اند. اگر در خروجی فقط کدهای \u دیدی، داده خراب نیست؛ فقط نمایش آن به‌شکل کد است (در Python با ensure_ascii=False متن فارسی نمایش داده می‌شود).

گام ۵: از درخت به جدول

صفحه‌گسترده خانه‌ای برای فهرست ندارد. وقتی سفارش چند قلم دارد، باید قاعده بگذاری:

قاعدههر ردیفخطر
یک ردیف برای هر سفارشسفارش؛ اقلام در یک خانه به‌هم‌چسبیدهجزئیات اقلام قابل محاسبه نیست
یک ردیف برای هر قلمسفارش + یک قلمفیلدهای سطح سفارش (مبلغ کل) تکرار می‌شوند؛ جمع‌زدنشان غلط است
دو جدولجدول سفارش‌ها و جدول اقلام با شناسه سفارشپیچیده‌تر، ولی درست‌ترین

قاعده را بنویس، و برای هر ستون بگو در سطح سفارش است یا سطح قلم. داستان آغاز درس همین بود.

مثال‌ها

پیاده‌سازی عملی

خواندن، اصلاح و تبدیل JSON سفارش‌ها. حدود ۲۰ دقیقه.

  1. assets/orders-page-1.json را باز کن و مسیر این‌ها را بنویس: شناسه سفارش دوم؛ عنوان قلم اول سفارش سوم؛ شماره صفحه بعد.
  2. شش نمونه assets/broken-json-samples.md را بخوان و برای هرکدام بگو ایراد نحوی است یا معنایی، و اصلاحش چیست. بعد پاسخ‌های پایین فایل را ببین.
  3. قاعده مسطح‌سازی را برای گزارش «فروش هر کتاب» و گزارش «مبلغ کل هفته» جدا انتخاب کن.
اجرای محلی

API آزمایشی (shared/barg-sabz-mock-api.py) را مثل درس قبل اجرا کن و صفحه دوم را بگیر: GET /orders?page=2&limit=3 با هدر Authorization: Bearer local-demo-token. بررسی کن next_page چه می‌گوید و صفحه آخر کدام است. درس پنجم دوره n8n همین «رفتن تا صفحه آخر» را خودکار می‌کند.

بدون اجرا / شبیه‌ساز

بدون اجرا: از روی assets/orders-page-1.json بنویس صفحه بعد را با چه نشانی‌ای می‌خواستی و از کجا می‌فهمیدی صفحه آخر رسیده است (next_page برابر null).

بدون کد

orders-page-1.json را در کلاینت HTTP یا یک نمایشگر JSON به‌شکل درختی باز کن. مسیرها را با باز و بسته کردن گره‌ها پیدا کن. برای مسطح‌سازی، جدول «یک ردیف برای هر قلم» را دستی در صفحه‌گسترده بساز و کنار هر ستون بنویس «سطح سفارش» یا «سطح قلم».

با کد

مسیرها را در Python امتحان کن و فایل را به CSV تبدیل کن:

import json
doc = json.load(open("orders-page-1.json", encoding="utf-8"))
print(doc["data"][1]["id"], doc["data"][2]["items"][0]["title"], doc["next_page"])
print(json.dumps(doc["data"][0], ensure_ascii=False))
python flatten_orders.py orders-page-1.json > orders.csv

اسکریپت برای هر قلم یک ردیف می‌سازد و سفارش بدون قلم را حذف نمی‌کند. ستون order_total را جمع نزن؛ چرا؟

اشتباه‌های رایج

اشتباهنتیجهکار درست
عدد را داخل نقل‌قول بفرستیجمع و مقایسه غلطعدد بدون نقل‌قول با رقم لاتین
شماره تلفن را عدد ذخیره کنیصفر اول حذف می‌شودشناسه و تلفن رشته‌اند
شمارش آرایه از یکقلم دوم را به‌جای اول می‌خوانیاز صفر بشمار
رشته خالی و null را یکی بدانیشرط‌ها در جاهای مختلف رفتار متفاوت دارندطبق قرارداد، یکی را انتخاب کن
جمع ستونی که در مسطح‌سازی تکرار شدهگزارش بیش از واقعسطح هر ستون را بنویس
کامنت یا ویرگول آخر در JSONتجزیه شکست می‌خوردJSON کامنت ندارد

اشکال‌زدایی

تجزیه JSON با پیامی مثل «Expecting property name enclosed in double quotes» شکست می‌خورد.

ایراد نحوی؛ معمولاً نقل‌قول تکی یا ویرگول اضافه.

شماره ستون در پیام خطا را دنبال کن؛ ایراد درست پیش از آن است.

متن را درست کن؛ اگر از مدل آمده، به‌جای اصلاح دستی، خروجی ساختاریافته با Schema بخواه.

مجموع یک ستون بیش از واقعیت است.

فیلد سطح بالاتر در مسطح‌سازی تکرار شده است.

تعداد شناسه‌های یکتا را با تعداد ردیف‌ها مقایسه کن.

جمع را در سطح درست بگیر یا داده را به دو جدول جدا کن.

کد روی items حلقه می‌زند و برای یک سفارش خطای نوع می‌دهد یا حرف‌به‌حرف جلو می‌رود.

در آن سفارش items شیء یا رشته است، نه آرایه.

نوع مقدار را پیش از حلقه بررسی کن.

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

تمرین کوتاه

تمرین · 10 دقیقه

هدف: انتخاب نوع درست برای هر فیلد.

گام‌ها: برای ثبت یک «درخواست خرید سازمانی» ساختگی، JSON بنویس با: نام سازمان، شماره تماس، تعداد کل، فوری است یا نه، تاریخ موعد، فهرست کتاب‌ها (هر کتاب: عنوان و تعداد)، و یادداشت که ممکن است نباشد.

معیار پذیرش: JSON معتبر؛ شماره تماس رشته؛ تعدادها عدد؛ فوری بولی؛ تاریخ رشته با قالب ثابت؛ کتاب‌ها آرایه‌ای از شیء؛ یادداشت null وقتی نیست.

راه‌حل نمونه
{
  "organization": "مدرسه نمونه",
  "phone": "021-00000000",
  "total_qty": 40,
  "urgent": false,
  "due_date": "2026-11-01",
  "books": [
    {"title": "کتاب نمونه یک", "qty": 25},
    {"title": "کتاب نمونه دو", "qty": 15}
  ],
  "note": null
}

چالش

تمرین · 30 دقیقه

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

  1. یک نمونه JSON کامل با دست‌کم یک آرایه و یک شیء تودرتو بنویس.
  2. برای هر فیلد جدولی بنویس: نوع، اجباری یا اختیاری، معنی null، و نمونه.
  3. دو نمونه «معتبر نحوی ولی غلط معنایی» برای داده خودت بنویس و بگو کجای ورک‌فلو خرابشان می‌کند.
  4. اگر این داده به جدول می‌رود، قاعده مسطح‌سازی و سطح هر ستون را بنویس.

خروجی مورد انتظار: نمونه JSON، جدول فیلدها، دو نمونه معنایی غلط با اثرشان، و قاعده مسطح‌سازی.

معیار پذیرش:

  • JSON معتبر است و نوع هر فیلد با کاربردش جور است (شناسه و تلفن رشته، مبلغ عدد).
  • تفاوت null، رشته خالی و نبودن فیلد روشن است.
  • نمونه‌های معنایی واقعاً از تجزیه‌گر رد می‌شوند و جای دیگری خطا می‌سازند.
  • ستون‌های تکرارشونده در مسطح‌سازی مشخص شده‌اند.

پرسش‌های سنجش

جمع‌بندی

  • JSON شش نوع مقدار دارد: رشته، عدد، بولی، null، شیء و آرایه؛ true، false و null با حروف کوچک.
  • شناسه و تلفن رشته‌اند؛ مبلغ و تعداد عدد بدون نقل‌قول با رقم لاتین.
  • مسیر فیلد آدرس مقدار تودرتوست و شمارش آرایه از صفر است.
  • ایراد نحوی را تجزیه‌گر می‌گیرد؛ ایراد معنایی را فقط قرارداد و Schema.
  • نام تکراری در شیء رفتار نامعلوم دارد؛ عدد خیلی بلند را رشته بفرست؛ تبادل با UTF-8.
  • در مسطح‌سازی سطح هر ستون را بنویس تا مقدار تکراری جمع نشود.

پرسش‌های سنجش

برای این فیلدهای یک «ثبت‌نام کارگاه» نوع JSON مناسب را بنویس و برای دو مورد دلیل بیاور: کد ملی ساختگی شرکت‌کننده، تعداد نفرات، مبلغ پرداختی، آیا هزینه پرداخت شده، توضیحات اختیاری، فهرست جلسه‌های انتخابی.

پاسخ نمونه و معیار ارزیابی

کد: رشته (عدد نیست و صفر اول مهم است). تعداد: عدد. مبلغ: عدد بدون نقل‌قول. پرداخت شده: بولی. توضیحات: رشته یا null وقتی نیست. جلسه‌ها: آرایه (از رشته یا شیء).

  • کد شناسایی را رشته می‌داند (1 امتیاز)
  • بولی و آرایه را درست به کار می‌برد (1 امتیاز)
  • null را برای نبودن مقدار پیشنهاد می‌کند (1 امتیاز)
  • کد عدد ← صفر اول حذف می‌شود و حساب‌کردن با آن معنی ندارد.

در JSON زیر، مسیر رسیدن به (الف) عنوان قلم دوم سفارش اول و (ب) شرکت حمل سفارش دوم را بنویس. مقدار (ب) چیست؟

پاسخ ساختگی API.

{"data": [
  {"id": "BS-2001", "carrier": "post",
   "items": [{"title": "الف", "qty": 1}, {"title": "ب", "qty": 2}]},
  {"id": "BS-2002", "carrier": null, "items": []}
], "next_page": null}
پاسخ نمونه و معیار ارزیابی

(الف) data[0].items[1].title که مقدارش «ب» است. (ب) data[1].carrier که مقدارش null است (شرکت حمل معلوم نیست).

  • مسیر الف با شمارش از صفر (1 امتیاز)
  • مسیر ب و مقدار null (1 امتیاز)
  • data[1].items[2].title ← شمارش آرایه از صفر است: سفارش اول data[0] و قلم دوم items[1].

ورک‌فلو مبلغ سه سفارش را جمع می‌زند و به‌جای ۱٬۲۹۵٬۰۰۰ نتیجه «420000690000185000» می‌گیرد. هیچ خطایی هم ثبت نشده است. علت و اصلاح چیست؟

پاسخ نمونه و معیار ارزیابی

مبلغ‌ها رشته‌اند، نه عدد (مثلاً "total": "420000")؛ جمع رشته‌ها آن‌ها را کنار هم چسبانده است. ایراد معنایی است و تجزیه‌گر آن را نمی‌گیرد. اصلاح: منبع داده عدد بفرستد، یا پیش از جمع تبدیل نوع و اعتبارسنجی با Schema (total از نوع number) انجام شود و مورد ناسازگار به مسیر خطا برود.

  • علت را رشته‌بودن مبلغ می‌داند (1 امتیاز)
  • آن را ایراد معنایی می‌داند که بی‌صدا رد شده (1 امتیاز)
  • اعتبارسنجی نوع یا تبدیل پیش از محاسبه (1 امتیاز)
  • سرور خراب است ← عددها درست آمده‌اند، فقط نوعشان رشته است.

کدام JSON از نظر نحوی معتبر است ولی با قرارداد «items آرایه است» نمی‌خواند؟

  • {"items": [{"title": "الف"}],}
  • {'items': []}
  • {"items": {"title": "الف"}}
  • {"items": [ ]}
پاسخ نمونه و معیار ارزیابی
  • a ← ویرگول اضافه؛ نحوی نامعتبر است.
  • b ← نقل‌قول تکی؛ نحوی نامعتبر است.
  • d ← آرایه خالی هم معتبر است و هم با قرارداد می‌خواند.

مدیر دو گزارش می‌خواهد: «فروش هر کتاب» و «مجموع مبلغ سفارش‌های هفته». داده هر سفارش آرایه‌ای از اقلام دارد. برای هر گزارش قاعده تبدیل به جدول را بنویس و بگو کجا خطر شمارش دوباره هست.

پاسخ نمونه و معیار ارزیابی

فروش هر کتاب: یک ردیف برای هر قلم (شناسه سفارش، عنوان، تعداد)؛ جمع تعداد بر اساس عنوان. مجموع مبلغ: یک ردیف برای هر سفارش و جمع مبلغ کل. خطر: اگر از جدول «هر قلم یک ردیف» مبلغ کل سفارش را جمع بزنی، سفارش‌های چندقلمی چند بار شمرده می‌شوند.

  • قاعده هر قلم برای گزارش اول (1 امتیاز)
  • قاعده هر سفارش برای گزارش دوم (1 امتیاز)
  • خطر تکرار مبلغ کل را می‌گوید (1 امتیاز)
  • یک جدول برای هر دو ← ممکن است، ولی باید جمع مبلغ را فقط روی شناسه‌های یکتا گرفت.

فایل‌های درس

API آزمایشی محلی با داده ساختگی

barg-sabz-mock-api.py

صفحه اول فهرست سفارش‌ها از API آزمایشی

orders-page-1.json

شش JSON مشکل‌دار با پاسخ

broken-json-samples.md

تبدیل سفارش‌های تودرتو به CSV

flatten_orders.py

ابزارها و جایگزین‌ها

  • ویرایشگر متن — خواندن و نوشتن JSON

منابع

RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format IETF December 2017 (STD 90)

دوره

زبان مشترک نرم‌افزارها: HTTP، JSON و API