چرا این جهت تبدیل با بقیه فرق دارد
JSON داده را به شکل درخت نگه میدارد: شیء درون شیء، آرایه درون آرایه، و هر مقدار نوع مشخص خودش را دارد — عدد، رشته، بولی یا null. CSV دقیقاً نقطه مقابل آن است؛ یک جدول تخت از سطر و ستون، بدون نوع داده، بدون تودرتویی و بدون مفهوم برگه. به همین دلیل رفتن از JSON به CSV با تبدیلهایی مثل CSV به Excel یا Excel به JSON یکی نیست. آن تبدیلها بیشتر تعویض پوستهاند، ولی این یکی مسطحسازی است و ذاتاً همراه با از دست رفتن اطلاعات.
سه چیز در این مسیر باقی نمیماند: نوع دادهها، ساختار سلسلهمراتبی و هر چیزی که به قالببندی مربوط است. برای اینکه شیءهای تودرتو بتوانند در یک جدول تخت جا شوند، ابزار کلیدها را با نقطه به هم میچسباند و مسیر کامل را نام ستون قرار میدهد؛ مثلاً کلید city که درون address نشسته است به ستونی به نام address.city تبدیل میشود. آرایهای از شیءها به سطرهای جدول تبدیل میشود و در آرایهای از آرایهها هم هر آرایه داخلی یک سطر میسازد. چون CSV مقدارها را با یک نویسه جداکننده از هم جدا میکند، هر مقداری که خودش ویرگول یا شکست خط دارد باید داخل نقلقول برود؛ این کار خودکار انجام میشود، اما صفرهای ابتدایی اعداد ممکن است از دست بروند.
یک تصمیم هم هست که ابزار نمیتواند به جای شما بگیرد: اینکه فیلدهای تودرتو در جدول نهایی چطور نمایش داده شوند. پیشفرض، همان مسیر نقطهای است؛ اگر چیز دیگری میخواهید باید JSON را پیش از تبدیل خودتان بازچینی کنید. تمام پردازش هم داخل مرورگر انجام میشود و فایل شما به هیچ سروری فرستاده نمیشود.
شکلی از JSON که ابزار میپذیرد
ورودی باید «جدولشکل» باشد، یعنی یکی از این دو حالت. حالت اول، آرایهای از شیءها:
[
{ "id": 1, "name": "مریم", "address": { "city": "تهران", "zip": "01234" } },
{ "id": 2, "name": "کاوه", "address": { "city": "شیراز", "zip": "71345" } }
]
هر شیء یک سطر میشود و کلیدها نام ستونها را میسازند. خروجی با جداکننده ویرگول چنین چیزی است:
id,name,address.city,address.zip
1,مریم,تهران,01234
2,کاوه,شیراز,71345
حالت دوم، آرایهای از آرایهها:
[["الف", 1, true], ["ب", 2, false]]
اینجا هیچ کلیدی وجود ندارد، پس هیچ سرستونی هم ساخته نمیشود؛ هر آرایه داخلی یک سطر است و عضوهایش به همان ترتیب ستونها را پر میکنند.
اگر فایل با یک شیء تنها شروع شود، یا آرایه اصلی چند لایه پایینتر و درون شیءهای دیگر پنهان شده باشد، یا اصلاً JSON معتبری نباشد، ابزار تبدیل را انجام نمیدهد و پیامی نشان میدهد که این JSON نامعتبر یا غیرجدولی است. رایجترین علتش پاسخهای API است که آرایه واقعی را داخل یک پوشش مثل {"status": "ok", "data": [...]} میگذارند. راهحل ساده است: مقدار data را بردارید و همان را بهتنهایی به فایل بدهید.
مسیر نقطهای و جایی که به دردسر میخورد
مسیر نقطهای قرارداد رایج ابزارهای مسطحساز است، ولی چند رفتار دارد که بهتر است از قبل بدانید. اول اینکه عمق تودرتویی مستقیماً به طول نام ستون تبدیل میشود؛ سه لایه تودرتویی نامی مثل contact.phone.home میسازد و در JSONهای عمیقتر سرستونها بهسرعت طولانی و ناخوانا میشوند. اگر قرار است خروجی را آدمی بخواند، منطقیتر است پیش از تبدیل فقط فیلدهای لازم را نگه دارید.
دوم اینکه شیءهای شما لازم نیست کلیدهای یکسان داشته باشند؛ ستونهای جدول از اجتماع همه کلیدهای دیدهشده ساخته میشود و سلولهایی که در شیء مبدأ کلیدشان وجود نداشته خالی میمانند. این یعنی خالی بودن یک سلول در CSV دو معنی متفاوت دارد — «کلید نبود» و «مقدار تهی بود» — و بعد از تبدیل دیگر نمیشود این دو را از هم تشخیص داد. اگر این تفاوت برایتان مهم است، پیش از تبدیل مقدار جانشین صریحی بگذارید.
سوم اینکه اگر در JSON اصلی هم کلیدی دقیقاً به نام address.city داشته باشید و هم شیء address با کلید city، هر دو بعد از مسطحسازی به یک ستون میرسند. پیشنمایش جدول و شمار ستونی که ابزار نشان میدهد ارزانترین راه گرفتن چنین خطاهاست؛ اگر عدد ستونها با انتظارتان نخواند، همانجا برگردید و JSON را بررسی کنید.
جداکننده، نقلقول و کدگذاری
ابزار سه جداکننده در اختیارتان میگذارد: ویرگول، نقطهویرگول و تب. انتخاب درست به نرمافزاری بستگی دارد که قرار است فایل را باز کند، نه به سلیقه. اکسل هنگام باز کردن مستقیم یک فایل CSV از جداکننده فهرست سیستمعامل پیروی میکند؛ در تنظیمات محلیای که ویرگول نقش جداکننده اعشار را دارد، این جداکننده نقطهویرگول است و فایلی که با ویرگول ساخته شده تماماً در یک ستون فرو میریزد. تب هم وقتی به کار میآید که دادهها پر از ویرگول و نقطهویرگول باشند و بخواهید نقلقولگذاری را به حداقل برسانید.
قاعده نقلقولگذاری همان است که RFC 4180 توصیف میکند و ابزار خودش اعمالش میکند: مقداری که جداکننده، شکست خط یا خود نویسه نقلقول را در بر دارد، داخل یک جفت " قرار میگیرد و هر " درونی با دو تا " نوشته میشود. برای نمونه، رشته سلام, "دنیا" در فایل به این شکل ذخیره میشود:
"سلام, ""دنیا"""
کدگذاری نکتهای است که هیچجای خود فایل CSV اعلام نمیشود. متن JSON طبق استاندارد با UTF-8 تبادل میشود، اما CSV هیچ فیلدی برای معرفی کدگذاری ندارد و برنامهای که فایل را میخواند باید حدس بزند. برای متن فارسی همین حدس زدن است که به حروف درهمریخته منجر میشود. اگر خروجی را در اکسل باز میکنید، بهجای دوبار کلیک روی فایل از مسیر وارد کردن داده استفاده کنید و کدگذاری را صراحتاً روی UTF-8 بگذارید؛ همین یک قدم بیشتر خرابیهای نمایش فارسی و عربی را حل میکند.
آنچه از نوع داده باقی میماند
CSV فقط متن دارد. عدد 42 میشود متن 42، مقدارهای true و false میشوند متن، و null که در JSON یک مقدار مستقل و معنادار است در جدول هیچ معادل رسمی ندارد. اگر تفاوت میان تهی، رشته خالی و متن null در کار بعدی شما اهمیت دارد، پیشنمایش را نگاه کنید و ببینید این سلولها چطور درآمدهاند، بعد بر آن اساس تصمیم بگیرید.
دردسر واقعی وقتی شروع میشود که فایل CSV را به یک صفحهگسترده میدهید. صفحهگستردهها متن هر سلول را از نو تفسیر میکنند: کد پستی 01234 به عدد ۱۲۳۴ تبدیل میشود و صفر ابتداییاش میرود، شناسههای عددی طولانی به نماد علمی میافتند و رشتههایی که شبیه تاریخاند به تاریخ ترجمه میشوند. هیچکدام از اینها را تبدیل JSON به CSV انجام نداده؛ همه در مرحله باز کردن فایل رخ میدهد. دو راه دارید: در JSON مبدأ چنین فیلدهایی را بهجای عدد، رشته بنویسید ("01234" نه 01234)، و هنگام وارد کردن فایل در صفحهگسترده نوع آن ستونها را دستی روی متن بگذارید.
نکته آخر اینکه ابزار فقط مقدارهای موجود را مینویسد و چیزی را محاسبه نمیکند؛ اگر در دادهتان متنی شبیه فرمول یا کد دارید، همان متن به خروجی میرود.
محدودیتها و پیامهای خطا
چون کار در مرورگر انجام میشود، سقفهایی وجود دارد. فایل بیش از حد بزرگ رد میشود و پیام خطا خودش حداکثر اندازه مجاز را میگوید. برای تعداد سطر و تعداد ستون هم سقف جداگانهای هست و در صورت عبور، همان پیام حد مجاز را نشان میدهد. تبدیلی که خیلی طول بکشد متوقف میشود و پیشنهاد میکند فایل کوچکتری امتحان کنید، و تبدیل در حال اجرا را میتوانید خودتان لغو کنید.
خطاهای دیگر مربوط به انتخاب فایلاند: نبود فایل، فایلی با پسوندی خارج از CSV و JSON و XLSX، یا انتخاب قالب خروجیای که با قالب ورودی یکی است. اگر فایل درست باشد ولی تبدیل به هر دلیلی شکست بخورد، پیام کلی «تبدیل انجام نشد» نمایش داده میشود؛ در این حالت اولین چیزی که باید بررسی کنید اعتبار خود JSON است. پیش از دانلود هم پیشنمایش جدول، تعداد سطرها و ستونها و اندازه فایل خروجی در اختیارتان است.
پرسشهای پرتکرار
آیا فایل من جایی آپلود میشود؟
خیر. خواندن فایل، مسطحسازی و ساخت CSV همگی در مرورگر شما انجام میشود و دادهای از دستگاهتان خارج نمیشود. برای دادههای حساس مثل فهرست مشتریان یا خروجی پایگاه داده، همین ویژگی تفاوت اصلی با سرویسهایی است که فایل را به سرور میفرستند.
چرا JSON من «جدولشکل» شناخته نمیشود؟
معمولاً چون سطح بالای فایل یک آرایه نیست. پاسخهای API اغلب آرایه را داخل یک شیء پوششی میگذارند. مطمئن شوید محتوای فایل با [ شروع میشود و اولین عضو آن یک شیء یا یک آرایه است. اگر فایل با { شروع میشود، باید آرایه درونی را بیرون بکشید.
کدام جداکننده را انتخاب کنم؟
اگر خروجی را به یک برنامه یا اسکریپت میدهید، ویرگول انتخاب پیشفرض و امن است. اگر قرار است کسی فایل را در اکسل با تنظیمات محلیای باز کند که ویرگول را جداکننده اعشار میداند، نقطهویرگول را بردارید. اگر دادهها خودشان پر از ویرگولاند، تب خروجی تمیزتری میدهد.
چطور صفر ابتدایی کد پستی را حفظ کنم؟
مقدار را در JSON مبدأ بهصورت رشته بنویسید، یعنی "01234" نه 01234. عدد در JSON صفرهای ابتدایی را اصلاً نگه نمیدارد. حتی با رشته هم، هنگام باز کردن CSV در صفحهگسترده باید نوع آن ستون را روی متن تنظیم کنید تا دوباره به عدد تبدیل نشود.
آیا میتوانم بعداً از CSV به JSON برگردم؟
میتوانید دوباره جدولی از داده بسازید، اما همان JSON اولیه را پس نمیگیرید. ساختار تودرتو و نوع دادهها در مرحله مسطحسازی رفتهاند و از روی متن CSV قابل بازسازی نیستند؛ ستون address.city هنگام بازگشت یک کلید تخت با همین نام است، نه شیء address. اگر به نسخه اصلی نیاز دارید، فایل JSON را نگه دارید.