JSON Formatter چیست و چگونه JSON را خوانا کنیم؟

JSON Formatter ابزاری برای مرتب‌سازی و خواناسازی متن JSON است. وقتی یک پاسخ API در یک خط طولانی قرار دارد، فاصله‌ها نامنظم‌اند یا ساختار تو‌در‌تو به‌سختی دیده می‌شود، Formatter با افزودن تورفتگی و شکست خط، همان داده را به شکلی قابل‌خواندن نمایش می‌دهد. هدف اصلی آن تغییر معنای داده نیست؛ فقط نمایش متن را بهتر می‌کند.

بااین‌حال، استفاده درست از JSON Formatter فقط فشردن یک دکمه نیست. باید بدانیم Formatter چه کاری انجام می‌دهد، چه کاری انجام نمی‌دهد، تفاوت آن با Validator، Viewer و Minifier چیست، چرا بعضی JSONها فرمت نمی‌شوند، تورفتگی مناسب چگونه انتخاب می‌شود، آیا ترتیب کلیدها تغییر می‌کند، داده‌های حساس چه خطری دارند و چگونه خروجی را بدون ایجاد تفاوت معنایی در پروژه استفاده کنیم.

پاسخ سریع: JSON Formatter متن JSON معتبر را Parse می‌کند و با فاصله، تورفتگی و خط‌شکنی استاندارد دوباره می‌نویسد. Formatter معمولاً مقدارها و ساختار داده را تغییر نمی‌دهد، اما جای JSON Validator یا Schema Validator نیست.

JSON Formatter چیست؟

JSON Formatter که با نام‌های JSON Beautifier، JSON Prettifier یا Pretty Printer نیز شناخته می‌شود، داده JSON را از حالت فشرده یا نامنظم به ساختاری خوانا تبدیل می‌کند.

ورودی فشرده:

{"id":42,"name":"Sara","roles":["editor","author"],"profile":{"city":"Tehran","active":true}}

خروجی فرمت‌شده:

{
  "id": 42,
  "name": "Sara",
  "roles": [
    "editor",
    "author"
  ],
  "profile": {
    "city": "Tehran",
    "active": true
  }
}

در هر دو نمونه، داده یکسان است. تفاوت فقط در فاصله‌ها، شکست خط و تورفتگی است.

JSON Formatter چگونه کار می‌کند؟

یک Formatter قابل‌اعتماد معمولاً سه مرحله انجام می‌دهد:

1. متن ورودی را به Parser می‌دهد.
2. اگر Syntax معتبر باشد، آن را به ساختار داده تبدیل می‌کند.
3. ساختار را با قواعد تورفتگی مشخص دوباره Serialize می‌کند.

نمای ساده فرایند:

JSON text
   ↓ Parse
Object / Array / primitive value
   ↓ Pretty serialization
Formatted JSON text

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

تفاوت JSON Formatter و JSON Validator

ویژگی	JSON Formatter	JSON Validator
هدف اصلی	خواناسازی نمایش	بررسی معتبر بودن Syntax
نیاز به Parse	معمولاً بله	بله
تغییر فاصله‌ها	بله	معمولاً خیر
گزارش محل خطا	ممکن است	باید انجام دهد
بررسی Schema	خیر	فقط اگر Schema Validator باشد
تضمین درست بودن داده کسب‌وکاری	خیر	خیر، مگر قواعد معنایی جدا تعریف شده باشند

Formatter معمولاً برای تولید خروجی به Parse موفق نیاز دارد؛ بنابراین ممکن است Syntax نامعتبر را تشخیص دهد. اما تشخیص Syntax تنها بخشی از Validation است. JSON زیر از نظر Syntax معتبر است:

{
  "email": 123,
  "age": "unknown"
}

Formatter آن را مرتب می‌کند، ولی نمی‌داند طبق قرارداد API، email باید String و age باید Integer باشد. این وظیفه Schema Validation یا Validation برنامه است.

نکته مهم: خروجی زیبا لزوماً داده درست نیست. Formatter ظاهر را اصلاح می‌کند، نه منطق یا قرارداد داده را.

تفاوت JSON Formatter و JSON Viewer

Formatter معمولاً متن JSON را با تورفتگی نمایش می‌دهد و امکان کپی خروجی می‌دهد. Viewer ممکن است امکانات بیشتری ارائه کند:

• نمایش درختی Object و Array
• باز و بسته کردن شاخه‌ها
• جستجو میان کلیدها و مقدارها
• نمایش مسیر هر مقدار
• پنهان‌کردن بخش‌های بزرگ
• نمایش نوع داده

برای JSON کوچک، Formatter کافی است. برای JSON بسیار تو‌در‌تو یا بزرگ، Tree Viewer معمولاً درک ساختار را آسان‌تر می‌کند.

تفاوت JSON Formatter و JSON Minifier

Formatter و Minifier دو عملیات معکوس در نمایش متن هستند:

عملیات	هدف	نمونه کاربرد
Format / Beautify	افزایش خوانایی	Debug، Review، آموزش
Minify	کاهش فاصله و خط جدید	انتقال، ذخیره و Payload کوچک‌تر

JSON فرمت‌شده:

{
  "id": 42,
  "name": "Sara"
}

JSON Minifyشده:

{"id":42,"name":"Sara"}

در حالت صحیح، هر دو باید پس از Parse، ساختار داده یکسانی تولید کنند.

تورفتگی در JSON Formatter

تورفتگی مشخص می‌کند هر سطح تو‌در‌تویی چند فاصله یا Tab جلوتر نمایش داده شود. گزینه‌های رایج عبارت‌اند از:

• ۲ فاصله
• ۴ فاصله
• Tab

دو فاصله

{
  "user": {
    "name": "Sara"
  }
}

چهار فاصله

{
    "user": {
        "name": "Sara"
    }
}

هیچ مقدار جهانی اجباری نیست. دو فاصله خروجی فشرده‌تر تولید می‌کند و چهار فاصله برای بعضی تیم‌ها خواناتر است. مهم‌ترین اصل، ثبات در پروژه است.

Space یا Tab؟

در JSON نهایی، فاصله و Tab خارج از String معنای داده را تغییر نمی‌دهند. بااین‌حال خروجی با Space معمولاً در محیط‌های مختلف ظاهر پایدار‌تری دارد. اگر تیم Style Guide مشخصی دارد، Formatter باید همان را رعایت کند.

آیا Formatter ترتیب کلیدها را تغییر می‌دهد؟

یک Formatter ساده باید فقط نمایش را تغییر دهد و ترتیب اعضای Object را حفظ کند. اما برخی ابزارها گزینه Sort Keys دارند یا هنگام Parse و Serialize ترتیب خاصی اعمال می‌کنند.

ورودی:

{
  "z": 1,
  "a": 2,
  "m": 3
}

خروجی Formatter معمولی:

{
  "z": 1,
  "a": 2,
  "m": 3
}

خروجی Sort Keys:

{
  "a": 2,
  "m": 3,
  "z": 1
}

مرتب‌سازی کلیدها عملی جدا از Formatting است. اگر ترتیب فعلی برای Diff یا خروجی قراردادی مهم است، گزینه Sort Keys نباید ناخواسته فعال شود.

آیا Formatter مقدارها را تغییر می‌دهد؟

در حالت ایده‌آل، Formatter نباید مقدارهای String، Number، Boolean و null را تغییر دهد. بااین‌حال چند نقطه حساس وجود دارد.

عددهای بسیار بزرگ

اگر ابزار JSON را در محیطی Parse کند که Number دقت محدودی دارد، ممکن است شناسه عددی بسیار بزرگ تغییر کند:

{
  "id": 9223372036854775807
}

اگر این مقدار شناسه است، ارسال به‌صورت String ایمن‌تر است:

{
  "id": "9223372036854775807"
}

نمایش عدد

Parser ممکن است نمایش عدد را Normalize کند. برای مثال، 1.0 ممکن است در خروجی به 1 تبدیل شود، با اینکه مقدار عددی یکسان است. اگر نمایش دقیق عدد برای امضا، حسابداری یا Diff متنی اهمیت دارد، Formatting مبتنی بر Parse باید با احتیاط استفاده شود.

Unicode Escape

بعضی Serializerها متن فارسی را مستقیم و بعضی به شکل Unicode Escape می‌نویسند:

{
  "title": "سلام"
}

{
  "title": "\u0633\u0644\u0627\u0645"
}

هر دو می‌توانند همان String را نمایش دهند، اما Diff متنی آن‌ها متفاوت است.

چرا بعضی JSONها فرمت نمی‌شوند؟

علت اصلی، نامعتبر بودن Syntax است. رایج‌ترین مشکلات:

• کلید بدون کوتیشن دوتایی
• استفاده از کوتیشن تکی
• ویرگول پایانی
• کوتیشن بسته‌نشده
• براکت یا آکولاد ناقص
• Comment داخل JSON
• مقادیر undefined، NaN یا Infinity
• Escape نامعتبر داخل String

کلید بدون کوتیشن

{
  name: "Sara"
}

نسخه صحیح:

{
  "name": "Sara"
}

کوتیشن تکی

{
  'name': 'Sara'
}

نسخه صحیح:

{
  "name": "Sara"
}

ویرگول پایانی

{
  "id": 42,
  "name": "Sara",
}

نسخه صحیح:

{
  "id": 42,
  "name": "Sara"
}

Comment

{
  // user name
  "name": "Sara"
}

JSON استاندارد Comment ندارد. Formatter نباید Comment را به‌عنوان JSON معتبر قبول کند، مگر اینکه صریحاً حالت JSON-like یا JSONC داشته باشد.

رفع خطای JSON قبل از Formatting

وقتی Formatter خطا می‌دهد، این روند مفید است:

1. شماره خط و ستون گزارش‌شده را بررسی کنید.
2. چند کاراکتر قبل از محل خطا را نیز ببینید؛ خطا ممکن است زودتر شروع شده باشد.
3. کوتیشن‌ها، براکت‌ها و آکولادها را جفت کنید.
4. ویرگول قبل و بعد از عضو را بررسی کنید.
5. Comment و مقدارهای غیر JSON را حذف کنید.
6. پس از رفع Syntax، دوباره Validate و سپس Format کنید.

پیام «Unexpected token» معمولاً یعنی Parser با کاراکتری روبه‌رو شده که در آن موقعیت مجاز نیست. «Unexpected end of JSON input» معمولاً به String یا ساختار بسته‌نشده اشاره دارد.

Format کردن JSON در JavaScript

در JavaScript می‌توان از JSON.parse و JSON.stringify استفاده کرد:

function formatJson(input, spaces = 2) {
  try {
    const value = JSON.parse(input);
    return {
      ok: true,
      output: JSON.stringify(value, null, spaces),
      error: null
    };
  } catch (error) {
    return {
      ok: false,
      output: null,
      error:
        error instanceof Error
          ? error.message
          : "Invalid JSON"
    };
  }
}

const result = formatJson(
  '{"id":42,"name":"Sara"}',
  2
);

if (result.ok) {
  console.log(result.output);
} else {
  console.error(result.error);
}

پارامتر سوم JSON.stringify تورفتگی را تعیین می‌کند. مقدار عددی معمولاً تعداد فاصله‌هاست.

Format کردن JSON در Python

import json
from typing import Any

def format_json(text: str, indent: int = 2) -> str:
    try:
        value: Any = json.loads(text)
    except json.JSONDecodeError as error:
        raise ValueError(
            f"Invalid JSON at line {error.lineno}, "
            f"column {error.colno}: {error.msg}"
        ) from error

    return json.dumps(
        value,
        ensure_ascii=False,
        indent=indent
    )

print(format_json(
    '{"title":"سلام","items":[1,2,3]}'
))

ensure_ascii=False باعث می‌شود متن فارسی به‌صورت خوانا باقی بماند.

Format کردن JSON در C#

using System.Text.Json;

static string FormatJson(string input)
{
    using var document = JsonDocument.Parse(input);

    return JsonSerializer.Serialize(
        document.RootElement,
        new JsonSerializerOptions
        {
            WriteIndented = true
        });
}

try
{
    var output = FormatJson(
        "{\"id\":42,\"name\":\"Sara\"}"
    );

    Console.WriteLine(output);
}
catch (JsonException exception)
{
    Console.WriteLine(
        $"Invalid JSON: {exception.Message}"
    );
}

برای Payload بزرگ، باید محدودیت عمق و اندازه نیز متناسب با کاربرد تنظیم شود.

Format کردن JSON در خط فرمان

در محیط‌های توسعه، Formatter خط فرمان برای Pipeline و بررسی سریع مفید است. اصل مهم این است که خطای Parse با Exit Code مناسب گزارش شود و فایل اصلی بدون تأیید بازنویسی نشود.

یک Workflow امن:

read input
→ parse
→ if invalid: stop and report error
→ format to temporary output
→ compare
→ replace original only after success

JSON Formatter در فرایند توسعه

Debug پاسخ API

پاسخ Minifyشده شبکه را می‌توان Format کرد تا مسیر Objectها، Arrayها و مقدارهای null سریع‌تر دیده شوند.

Code Review

JSON فرمت‌شده Diff خواناتری دارد. هر کلید معمولاً در خط جدا قرار می‌گیرد و تغییر مقدارها آسان‌تر دیده می‌شود.

فایل تنظیمات

فرمت ثابت از تغییرات بی‌دلیل فاصله جلوگیری می‌کند. بهتر است Formatter در Editor یا Pre-commit اجرا شود تا تیم خروجی یکنواختی داشته باشد.

آموزش و مستندسازی

مثال JSON در مقاله یا مستند باید تورفتگی منطقی داشته باشد تا رابطه Object و Array دیده شود.

آیا JSON فرمت‌شده برای Production مناسب است؟

از نظر معنایی بله، اما همیشه از نظر حجم بهترین انتخاب نیست. فاصله‌ها و خط‌های جدید حجم Payload را افزایش می‌دهند. برای API عمومی Production معمولاً JSON Minifyشده ارسال می‌شود و ابزارهای مرورگر یا Log Viewer در صورت نیاز آن را Format می‌کنند.

محیط	انتخاب رایج
فایل قابل ویرایش انسان	Formatted
مستندات	Formatted
پاسخ API Production	Minified + Compression
Log توسعه	Formatted با کنترل داده حساس
Cache یا امضا	فرمت قراردادی و پایدار

Formatter و Git Diff

فرمت ثابت می‌تواند کیفیت Diff را بالا ببرد، اما تغییر Style Formatter در میانه پروژه ممکن است کل فایل را تغییر‌داده نشان دهد. برای جلوگیری از این مشکل:

• Style تورفتگی را از ابتدا مشخص کنید.
• Formatter و Version آن را در پروژه ثابت نگه دارید.
• تغییر Format عمومی را در Commit جدا انجام دهید.
• تغییر داده و تغییر Style را در یک Commit ترکیب نکنید.
• Sort Keys را فقط با تصمیم تیمی فعال کنید.

Format کردن JSON بزرگ

JSON بزرگ می‌تواند هنگام Parse کامل حافظه زیادی مصرف کند. اگر یک فایل چندصد مگابایتی باشد، Formatter مبتنی بر DOM معمولاً کل ساختار را در حافظه نگه می‌دارد.

مشکلات رایج

• مصرف حافظه چندبرابر اندازه فایل
• کندی Parse و Serialize
• Freeze شدن رابط مرورگر
• Crash در موبایل یا سیستم ضعیف
• زمان زیاد برای Copy و Render

راهکارها

• محدودیت اندازه ورودی تعیین کنید.
• برای فایل بزرگ از Streaming Parser استفاده کنید.
• نمایش را Virtualize کنید.
• شاخه‌ها را در Tree Viewer به‌صورت Lazy باز کنید.
• برای داده خطی، NDJSON را بررسی کنید.
• فرمت را روی سرور یا ابزار محلی مناسب انجام دهید.

امنیت و حریم خصوصی در JSON Formatter آنلاین

JSON ممکن است حاوی اطلاعات حساس باشد:

• Access Token و Refresh Token
• Cookie و Session ID
• ایمیل و شماره تلفن
• اطلاعات مالی
• کلید API
• آدرس و اطلاعات شخصی
• پاسخ داخلی سرویس‌ها

قبل از قرار دادن داده در هر ابزار آنلاین باید بدانید پردازش در مرورگر انجام می‌شود یا داده به سرور ارسال می‌شود. برای داده حساس، پردازش محلی یا ابزاری که صریحاً Client-side است انتخاب امن‌تری است.

هشدار: Formatter داده را محرمانه نمی‌کند. JSON فرمت‌شده همان اطلاعات ورودی را دارد و حتی ممکن است خواندن آن آسان‌تر شود.

پاک‌سازی داده قبل از Formatting

می‌توان مقدارهای حساس را با داده آزمایشی جایگزین کرد:

{
  "accessToken": "[REDACTED]",
  "email": "user@example.test",
  "cardNumber": "[MASKED]"
}

کلیدهای تکراری و Formatter

JSON با کلید تکراری مبهم است:

{
  "status": "draft",
  "status": "published"
}

اگر Formatter ابتدا Parse کند، ممکن است یکی از مقدارها از بین برود و فقط خروجی زیر باقی بماند:

{
  "status": "published"
}

به همین دلیل Formatter حرفه‌ای بهتر است کلید تکراری را قبل از تبدیل به Object زبان مقصد تشخیص دهد یا حداقل هشدار دهد. صرف Pretty Print نباید باعث حذف بی‌صدای داده شود.

Formatting بدون Parse چه مزایا و خطرهایی دارد؟

برخی ابزارها تلاش می‌کنند فقط براساس کاراکترها فاصله و خط اضافه کنند. این روش ممکن است نمایش بخشی از JSON خراب را بهتر کند، اما خطر دارد:

• براکت داخل String را با ساختار اشتباه بگیرد.
• Escapeها را نادرست تفسیر کند.
• خروجی ظاهراً مرتب ولی همچنان نامعتبر بسازد.
• خطا را پنهان کند.

برای خروجی قابل اعتماد، Parse واقعی و سپس Serialize روش مناسب‌تری است.

آیا Formatter می‌تواند JSON خراب را خودکار تعمیر کند؟

بعضی ابزارها قابلیت Repair دارند، اما Repair با Format فرق دارد. تعمیر خودکار ممکن است:

• کوتیشن اضافه کند.
• ویرگول اضافی حذف کند.
• براکت بسته اضافه کند.
• Comment را حذف کند.
• کوتیشن تکی را تبدیل کند.

این تغییرها ممکن است قصد نویسنده را اشتباه حدس بزنند. خروجی Repair باید قبل از استفاده بررسی و دوباره Validate شود. Formatter نباید بدون اعلام، داده را تعمیر کند.

Formatter و Canonical JSON

Pretty Formatting برای خوانایی است؛ Canonicalization برای تولید نمایش پایدار و دقیق استفاده می‌شود. در Canonical JSON معمولاً ترتیب کلیدها، نمایش Number، Escape و فاصله‌ها طبق قرارداد مشخص می‌شوند.

اگر JSON برای امضا، Hash، Cache Key یا مقایسه بایت‌به‌بایت استفاده می‌شود، Formatter معمولی کافی نیست. دو متن فرمت‌شده ممکن است همان داده را داشته باشند اما بایت‌های متفاوت تولید کنند.

مقایسه خروجی قبل و بعد از Formatting

برای اطمینان از حفظ معنا، می‌توان هر دو نسخه را Parse و ساختار آن‌ها را مقایسه کرد:

function deepEqualJson(leftText, rightText) {
  const left = JSON.parse(leftText);
  const right = JSON.parse(rightText);

  return JSON.stringify(left) === JSON.stringify(right);
}

این نمونه برای شرایط ساده است. اگر ترتیب کلیدها متفاوت باشد یا Numberهای خاص وجود داشته باشند، Deep Equality مستقل از Serialization مناسب‌تر است.

طراحی یک JSON Formatter خوب

اگر در حال ساخت ابزار Formatter هستید، این قابلیت‌ها ارزشمندند:

• گزارش دقیق Line و Column خطا
• انتخاب ۲ یا ۴ فاصله و Tab
• حفظ Unicode خوانا
• عدم تغییر ترتیب کلیدها به‌صورت پیش‌فرض
• گزینه جداگانه Sort Keys
• Copy و Download خروجی
• محدودیت اندازه ورودی
• پردازش Client-side برای حریم خصوصی
• نمایش تفاوت قبل و بعد
• هشدار کلید تکراری
• پشتیبانی از Minify به‌عنوان عملیات جدا
• عدم ذخیره History بدون رضایت کاربر

خطاهای رایج هنگام استفاده از Formatter

• فرض اینکه Formatter همه خطاها را تعمیر می‌کند.
• استفاده از خروجی زیبا به‌جای Schema Validation.
• قرار دادن Token واقعی در ابزار ناشناس.
• فعال کردن Sort Keys بدون نیاز.
• فرمت کردن فایل بزرگ در مرورگر ضعیف.
• بازنویسی فایل اصلی قبل از Parse موفق.
• نادیده گرفتن تغییر دقت عدد بزرگ.
• مقایسه متنی دو Object بدون Normalize.
• فرمت کردن پاسخ Production برای همه کاربران بدون نیاز.
• قبول کلید تکراری بدون هشدار.

بهترین روش‌های JSON Formatting

1. ابتدا Syntax را Validate کنید.
2. برای تیم یک Style ثابت انتخاب کنید.
3. Formatting و Sort Keys را عملیات جدا بدانید.
4. برای داده حساس از ابزار محلی یا Client-side استفاده کنید.
5. عددهای بسیار بزرگ را بررسی کنید.
6. فایل اصلی را فقط بعد از موفقیت کامل بازنویسی کنید.
7. برای JSON بزرگ محدودیت اندازه داشته باشید.
8. Formatter را جای Schema Validator قرار ندهید.
9. تغییرات Formatter را در Git جدا از تغییر داده نگه دارید.
10. پس از Repair خودکار، خروجی را دستی بررسی کنید.

چک‌لیست انتخاب JSON Formatter

• آیا پردازش در مرورگر انجام می‌شود؟
• آیا داده به سرور ارسال می‌شود؟
• آیا محل خطا دقیق نمایش داده می‌شود؟
• آیا تورفتگی قابل تنظیم است؟
• آیا Unicode فارسی حفظ می‌شود؟
• آیا Sort Keys اختیاری است؟
• آیا کلیدهای تکراری تشخیص داده می‌شوند؟
• آیا محدودیت اندازه مشخص است؟
• آیا Copy و Download دارد؟
• آیا History بدون رضایت ذخیره نمی‌شود؟

چه زمانی از JSON Formatter استفاده کنیم؟

• خواندن پاسخ Minifyشده API
• بررسی ساختار Object و Array
• آماده‌سازی مثال برای مستندات
• مرتب‌کردن فایل تنظیمات
• ساخت Diff خواناتر
• پیدا کردن سطح تو‌در‌تویی
• آماده‌سازی داده برای Debug

چه زمانی Formatter کافی نیست؟

• وقتی باید نوع و فیلدهای اجباری بررسی شوند.
• وقتی داده باید با JSON Schema اعتبارسنجی شود.
• وقتی JSON خراب نیاز به Repair دارد.
• وقتی داده برای امضا به Canonicalization نیاز دارد.
• وقتی فایل بسیار بزرگ و نیازمند Streaming است.
• وقتی باید اختلاف معنایی دو JSON پیدا شود.

جمع‌بندی

JSON Formatter داده JSON معتبر را به شکل خوانا بازنویسی می‌کند. با افزودن تورفتگی و شکست خط، ساختار Objectها و Arrayها بهتر دیده می‌شود و Debug، Review و مستندسازی آسان‌تر می‌شود. بااین‌حال Formatter ابزار اعتبارسنجی معنایی، Schema Validator، Repair Tool یا ابزار امنیتی نیست.

برای استفاده حرفه‌ای، Syntax را پیش از Formatting بررسی کنید، Style ثابتی داشته باشید، داده حساس را در ابزار نامطمئن وارد نکنید، Sort Keys را جدا مدیریت کنید و برای فایل‌های بزرگ محدودیت و روش پردازش مناسب در نظر بگیرید. یک Formatter خوب باید خوانایی را افزایش دهد بدون اینکه مقدار، ترتیب یا معنای داده را بی‌اطلاع کاربر تغییر دهد.