JSON یکی از پایهایترین قالبهای تبادل داده در وب و نرمافزارهای امروزی است. وقتی یک برنامه فرانتاند اطلاعات کاربر را از API میگیرد، وقتی تنظیمات یک ابزار در فایل ذخیره میشود، وقتی یک سرویس اطلاعات سفارش را برای سرویس دیگر میفرستد یا حتی وقتی دادهای داخل مرورگر نگهداری میشود، احتمال زیادی وجود دارد که JSON در میانه این فرایند حضور داشته باشد.
سادگی ظاهری JSON باعث شده بعضی توسعهدهندگان آن را فقط مجموعهای از آکولاد، کوتیشن و ویرگول بدانند. اما برای استفاده حرفهای باید علاوه بر Syntax، تفاوت Object و Array، نوع دادهها، Encoding، محدودیت عددها، طراحی قرارداد API، اعتبارسنجی، امنیت و عملکرد را نیز شناخت. این راهنما از تعریف اولیه شروع میکند و تا نکات مهم طراحی و استفاده در پروژه واقعی پیش میرود.
پاسخ سریع: JSON یک قالب متنی و مستقل از زبان برای نمایش و انتقال داده ساختاریافته است. داده در JSON با Object، Array، String، Number، Boolean و null ساخته میشود. JSON رمزنگاری، پایگاه داده یا زبان برنامهنویسی نیست؛ فقط یک روش استاندارد برای نمایش داده است.
JSON مخفف چیست؟
JSON مخفف JavaScript Object Notation است. نام آن از شکل نوشتاری Objectها در JavaScript گرفته شده، اما JSON به JavaScript محدود نیست. تقریباً همه زبانهای برنامهنویسی پرکاربرد کتابخانه یا قابلیت داخلی برای خواندن و تولید JSON دارند.
یک سند JSON در اصل یک متن است. این متن براساس قواعد مشخصی نوشته میشود و Parser آن را به ساختار داده زبان مقصد تبدیل میکند. برای نمونه، یک Object در JSON ممکن است در JavaScript به Object، در Python به Dictionary، در C# به یک کلاس یا Dictionary و در Java به Map یا یک مدل داده تبدیل شود.
یک نمونه ساده از JSON
{
"id": 42,
"name": "Sara",
"isActive": true,
"roles": ["editor", "author"],
"profile": {
"city": "Tehran",
"website": null
}
}
این نمونه چند ویژگی مهم JSON را نشان میدهد:
- داده اصلی یک Object است و با آکولاد باز و بسته میشود.
- هر عضو Object یک کلید و یک مقدار دارد.
- کلیدها رشته هستند و داخل کوتیشن دوتایی قرار میگیرند.
- مقدار میتواند رشته، عدد، Boolean، null، Array یا Object دیگری باشد.
- اعضای Object و Array با ویرگول از یکدیگر جدا میشوند.
چرا JSON اینقدر پرکاربرد شد؟
خوانایی مناسب برای انسان
یک فایل JSON خوشفرمت معمولاً بدون ابزار خاص قابل خواندن است. نام ویژگیها در کنار مقدارها قرار میگیرند و ساختار تودرتو با تورفتگی قابل تشخیص است.
پردازش ساده برای ماشین
قواعد JSON محدود و مشخصاند. Parser لازم نیست با قابلیتهای پیچیده یک زبان برنامهنویسی روبهرو شود. به همین دلیل خواندن و تولید JSON در زبانهای مختلف ساده و قابل اعتماد است.
استقلال از زبان برنامهنویسی
اگرچه نام JSON از JavaScript آمده، داده JSON به یک Runtime خاص وابسته نیست. سرور میتواند با C# نوشته شده باشد، کلاینت JavaScript باشد و یک سرویس پردازش داده با Python کار کند؛ هر سه میتوانند همان پیام JSON را بفهمند.
مناسب بودن برای APIهای وب
JSON با مدل درخواست و پاسخ HTTP بهخوبی هماهنگ است. داده متنی است، در ابزارهای توسعه مرورگر دیده میشود و با مدل Object و Array در برنامههای وب تناسب دارد.
اجزای اصلی JSON
هر سند JSON از مقدارها ساخته میشود. JSON شش نوع اصلی مقدار دارد:
| نوع | نمونه | کاربرد رایج |
|---|---|---|
| String | "xDFlow" | متن، شناسه، تاریخ قراردادی |
| Number | 19.95 | تعداد، قیمت، اندازه |
| Boolean | true | وضعیت دوحالته |
| null | null | نبودن مقدار براساس قرارداد |
| Object | {"id": 1} | مجموعه ویژگیهای نامدار |
| Array | [1, 2, 3] | فهرست مرتب مقدارها |
Object در JSON چیست؟
Object مجموعهای از جفتهای کلید و مقدار است. Object با { شروع و با } تمام میشود.
{
"productId": 1001,
"title": "Wireless Keyboard",
"price": 89.5,
"available": true
}
کلیدهای Object باید رشته باشند. این یعنی نمونه زیر JSON معتبر نیست:
{
productId: 1001
}
این شکل ممکن است در JavaScript بهعنوان Object Literal معتبر باشد، اما JSON نیست. نسخه صحیح باید کلید را داخل کوتیشن دوتایی قرار دهد:
{
"productId": 1001
}
آیا ترتیب کلیدهای Object مهم است؟
نباید منطق برنامه را به ترتیب اعضای Object وابسته کرد. بعضی Parserها ترتیب ورودی را حفظ میکنند، اما معنای Object براساس نام کلیدهاست، نه موقعیت آنها. اگر ترتیب بخشی از معنای داده است، Array معمولاً انتخاب مناسبتری است.
آیا کلید تکراری مجاز است؟
{
"status": "draft",
"status": "published"
}
این ساختار قابل اعتماد نیست. Parserها ممکن است آخرین مقدار را نگه دارند، اولین مقدار را نگه دارند یا رفتار دیگری داشته باشند. در قرارداد حرفهای، نام اعضای یک Object باید یکتا باشد.
بهترین روش: حتی اگر ابزار شما JSON دارای کلید تکراری را قبول میکند، آن را معتبر و قابل حمل فرض نکنید.
Array در JSON چیست؟
Array یک فهرست مرتب از مقدارهاست و با براکت نوشته میشود:
[
"json",
"api",
"web"
]
اعضای Array میتوانند هر نوع JSON باشند:
[
"text",
12,
true,
null,
{"id": 1},
["nested", "array"]
]
این ترکیب از نظر Syntax معتبر است، اما همیشه طراحی خوبی نیست. اگر Array مجموعهای از رکوردهاست، بهتر است اعضا ساختار مشابهی داشته باشند تا مصرفکننده مجبور به تشخیص نوع هر عضو نشود.
Array از Objectها
[
{
"id": 1,
"name": "Keyboard"
},
{
"id": 2,
"name": "Mouse"
}
]
این الگو برای فهرست محصولات، کاربران، سفارشها و نتایج جستجو بسیار رایج است.
String در JSON و قواعد Escape
رشته JSON باید داخل کوتیشن دوتایی قرار بگیرد. کوتیشن تکی بخشی از Syntax استاندارد JSON نیست.
{
"message": "Hello",
"language": "fa"
}
اگر داخل رشته نیاز به کوتیشن، Backslash یا نویسه کنترلی باشد، باید Escape استفاده شود:
| Escape | معنی |
|---|---|
\" | کوتیشن دوتایی داخل رشته |
\\ | Backslash |
\n | خط جدید |
\r | بازگشت به ابتدای خط |
\t | Tab |
\uXXXX | نمایش نویسه با کد Unicode |
{
"quote": "She said: \"Hello\"",
"path": "C:\\Projects\\xDFlow",
"multiline": "First line\nSecond line"
}
Unicode و متن فارسی در JSON
JSON میتواند متن فارسی، عربی، چینی، ایموجی و سایر نویسههای Unicode را نگه دارد. در بیشتر پروژههای امروزی، UTF-8 انتخاب استاندارد و قابل انتظار برای انتقال و ذخیره JSON است.
{
"title": "راهنمای کامل JSON",
"emoji": "✅"
}
گاهی Serializer نویسههای فارسی را به شکل Escapeشده نمایش میدهد. هر دو شکل میتوانند همان متن را نمایش دهند. شکل مستقیم معمولاً برای انسان خواناتر است، اما انتخاب نهایی به Serializer و نیاز سیستم بستگی دارد.
Number در JSON و محدودیت دقت
JSON یک نوع کلی Number دارد و میان Integer، Decimal، Float یا Double تفاوتی در Syntax قائل نمیشود.
{
"count": 12,
"price": 19.95,
"temperature": -4.5,
"distance": 1.2e6
}
این سادگی هنگام تبادل داده میان زبانها میتواند مشکل ایجاد کند. بعضی زبانها عددها را با دقت محدود نگه میدارند. برای مثال، یک شناسه عددی بسیار بزرگ ممکن است در JavaScript دقت خود را از دست بدهد.
چه زمانی عدد را بهصورت String ارسال کنیم؟
اگر مقدار فقط نقش شناسه دارد و عملیات ریاضی روی آن انجام نمیشود، ارسال بهصورت String میتواند امنتر باشد:
{
"orderId": "9223372036854775807"
}
همچنین مقدارهای پولی حساس بهتر است با قرارداد دقیق منتقل شوند؛ برای نمونه مبلغ به کوچکترین واحد پول بهصورت Integer یا Decimal قراردادی، نه Float مبهم.
عددهای نامعتبر در JSON
NaNInfinity-Infinity- عدد دارای صفر ابتدایی مانند
01 - عدد ناقص مانند
.5یا5.
Boolean در JSON
JSON فقط دو مقدار Boolean دارد و هر دو با حروف کوچک نوشته میشوند:
{
"enabled": true,
"deleted": false
}
True، False و رشتههای "true" و "false" معادل Boolean نیستند. رشته "false" هنوز یک متن است و در برخی زبانها ممکن است بهاشتباه Truthy در نظر گرفته شود.
null در JSON چه معنایی دارد؟
null یک مقدار واقعی در JSON است، اما معنای کسبوکاری آن باید در قرارداد مشخص شود.
{
"middleName": null
}
| حالت | نمونه | تفسیر احتمالی |
|---|---|---|
| مقدار null | "name": null | ویژگی وجود دارد اما مقدار ندارد |
| رشته خالی | "name": "" | مقدار متنی موجود ولی خالی است |
| حذف ویژگی | کلید وجود ندارد | ارسال نشده یا پشتیبانی نمیشود |
اگر این تفاوت در API مستند نشود، کلاینتها برداشتهای متفاوتی خواهند داشت.
ریشه سند JSON چه چیزی میتواند باشد؟
در استفاده روزمره، ریشه JSON معمولاً Object یا Array است. از نظر مدل JSON، مقدار ریشه میتواند String، Number، Boolean یا null نیز باشد. بااینحال بسیاری از APIها برای توسعهپذیری و وضوح، Object را در ریشه ترجیح میدهند.
چرا Object ریشه برای API انعطاف بیشتری دارد؟
اگر پاسخ اولیه فقط یک Array باشد، افزودن صفحهبندی و Metadata در آینده نیازمند تغییر شکل پاسخ است. طراحی Envelope از ابتدا انعطاف بیشتری دارد:
{
"items": [
{"id": 1},
{"id": 2}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 2
}
}
JSON معتبر و JSON خوشساخت یکسان نیستند
Validator فقط میتواند بگوید متن از نظر Syntax JSON معتبر است. اما معتبر بودن به معنی مناسب بودن طراحی نیست.
{
"data1": "Sara",
"data2": 27,
"data3": true
}
این JSON معتبر است، اما نامهای مبهم، تغییر نوع ویژگیها، تودرتویی بیدلیل و استفاده ناهماهنگ از null میتوانند نگهداری آن را دشوار کنند.
JSON با Object جاوااسکریپت چه تفاوتی دارد؟
| ویژگی | JSON | JavaScript Object |
|---|---|---|
| کلید بدون کوتیشن | مجاز نیست | در بسیاری موارد مجاز است |
| کوتیشن تکی | مجاز نیست | برای String مجاز است |
| تابع | نوع معتبر نیست | میتواند مقدار ویژگی باشد |
| undefined | وجود ندارد | وجود دارد |
| Comment | مجاز نیست | در کد مجاز است |
| Trailing Comma | مجاز نیست | در JavaScript مدرن اغلب مجاز است |
قواعد Syntax که بیشتر باعث خطا میشوند
کوتیشن تکی
{'name': 'Sara'}
نسخه صحیح:
{"name": "Sara"}
ویرگول پایانی
{
"id": 1,
"name": "Sara",
}
ویرگول بعد از آخرین عضو در JSON استاندارد مجاز نیست.
Comment
{
// user identifier
"id": 1
}
JSON استاندارد از Comment پشتیبانی نمیکند.
بسته نشدن کوتیشن یا براکت
خطای پایان ناگهانی JSON معمولاً از کوتیشن، آکولاد یا براکت بستهنشده ایجاد میشود. محل گزارششده همیشه دقیقاً محل واقعی اشتباه نیست؛ Parser ممکن است چند خط بعد متوجه مشکل شود.
Format، Minify و Validate چه تفاوتی دارند؟
| عملیات | هدف | آیا داده را تغییر میدهد؟ |
|---|---|---|
| Format یا Beautify | افزایش خوانایی با تورفتگی | معنای داده نباید تغییر کند |
| Minify | حذف فاصله و خط جدید غیرضروری | معنای داده نباید تغییر کند |
| Validate | بررسی Syntax و گاهی Schema | خیر |
| Transform | تغییر ساختار یا مقدارها | بله |
نکته حرفهای: Formatter جای Validator را نمیگیرد. بعضی Formatterها فقط زمانی کار میکنند که ورودی از قبل قابل Parse باشد.
Parse کردن JSON چیست؟
Parse یعنی تبدیل متن JSON به ساختار داده زبان برنامهنویسی.
JavaScript
const text = '{"name":"Sara","active":true}';
try {
const user = JSON.parse(text);
console.log(user.name);
} catch (error) {
console.error("Invalid JSON", error);
}
Python
import json
text = '{"name":"Sara","active":true}'
try:
user = json.loads(text)
print(user["name"])
except json.JSONDecodeError as error:
print("Invalid JSON:", error)
C#
using System.Text.Json;
var text = "{\"name\":\"Sara\",\"active\":true}";
try
{
var user = JsonSerializer.Deserialize<User>(text);
Console.WriteLine(user?.Name);
}
catch (JsonException exception)
{
Console.WriteLine($"Invalid JSON: {exception.Message}");
}
ورودی JSON از شبکه یا کاربر باید نامعتبر فرض شود تا زمانی که Parse و Validate شود.
Serialize یا Stringify کردن چیست؟
Serialize فرایند تبدیل ساختار داده برنامه به متن یا بایت قابل انتقال است. در JavaScript معمولاً از JSON.stringify استفاده میشود.
const user = {
id: 42,
name: "Sara",
active: true
};
const json = JSON.stringify(user);
console.log(json);
در پروژه واقعی بهتر است JSON را با Serializer استاندارد تولید کنید، نه با اتصال دستی رشتهها. اتصال دستی کوتیشن و Escape را آسیبپذیر و خطاپذیر میکند.
JSON در APIهای HTTP
وقتی بدنه درخواست یا پاسخ JSON است، نوع محتوا معمولاً با Header مشخص میشود:
Content-Type: application/json; charset=utf-8
یک پاسخ ساده API:
{
"data": {
"id": 42,
"name": "Sara"
},
"errors": []
}
طراحی پاسخ خطا
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed.",
"fields": {
"email": ["Email format is invalid."]
}
}
}
ارسال Stack Trace، Query دیتابیس یا جزئیات داخلی در پاسخ JSON میتواند اطلاعات حساس سیستم را افشا کند.
JSON Schema چه نقشی دارد؟
Syntax Validation فقط بررسی میکند متن JSON معتبر است. Schema Validation بررسی میکند ساختار مورد انتظار رعایت شده است یا نه.
{
"email": 123,
"age": "unknown"
}
این نمونه از نظر Syntax معتبر است، اما اگر قرارداد بگوید email باید String و age باید Integer باشد، از نظر Schema نامعتبر خواهد بود.
Schema میتواند نوع هر ویژگی، فیلدهای اجباری، محدوده عدد، طول رشته، Pattern، Enum و ساختار Object و Array را مشخص کند.
تاریخ و زمان در JSON
JSON نوع بومی Date ندارد. تاریخ معمولاً بهصورت String با قرارداد مشخص ارسال میشود:
{
"createdAt": "2026-08-06T10:30:00Z"
}
قرارداد باید منطقه زمانی و Format را دقیق تعریف کند. رشتهای مانند 06/08/2026 میتواند در فرهنگهای مختلف معنی متفاوتی داشته باشد.
ارسال فایل باینری با JSON
JSON نوع باینری ندارد. برای انتقال فایل، Upload مستقیم با Multipart، ارسال URL یا شناسه فایل و در موارد خاص Base64 استفاده میشود. Base64 حجم داده را افزایش میدهد و برای فایلهای بزرگ داخل JSON معمولاً انتخاب کارآمدی نیست.
امنیت JSON
ورودی را قابل اعتماد فرض نکنید
حتی اگر JSON از کلاینت رسمی برنامه میآید، مهاجم میتواند درخواست را تغییر دهد. همه ویژگیها، نوعها، طولها و مجوزها باید در سمت سرور بررسی شوند.
Mass Assignment
{
"displayName": "Sara",
"isAdmin": true
}
اگر JSON مستقیماً روی مدل دیتابیس Bind شود، کاربر ممکن است ویژگیهایی را تغییر دهد که نباید قابل ویرایش باشند. DTO ورودی باید فقط فیلدهای مجاز را تعریف کند.
محدودیت اندازه و عمق
JSON بسیار بزرگ یا بیش از حد تودرتو میتواند منابع سرور را مصرف کند. محدودیت اندازه Body، عمق Parse، تعداد اعضا و زمان پردازش باید متناسب با کاربرد تنظیم شود.
Log کردن داده حساس
ممکن است JSON شامل Token، ایمیل، شماره تلفن یا اطلاعات پرداخت باشد. ثبت کامل Request و Response در Log میتواند باعث افشای داده شود. Mask کردن و سیاست نگهداری Log ضروری است.
عملکرد JSON در دادههای بزرگ
برای Payloadهای کوچک و متوسط، JSON معمولاً انتخاب مناسبی است. اما در حجم بالا باید اندازه متن، مصرف حافظه هنگام Parse، زمان Serialize و تکرار نام کلیدها را در نظر گرفت.
راهکارهای بهبود
- فقط فیلدهای مورد نیاز را ارسال کنید.
- برای فهرستهای بزرگ از Pagination استفاده کنید.
- فشردهسازی HTTP را فعال کنید.
- از ساختارهای بسیار عمیق اجتناب کنید.
- برای پردازش جریان بزرگ از Streaming Parser استفاده کنید.
- در صورت نیاز واقعی، قالبهای جایگزین را Benchmark کنید.
JSON Lines یا NDJSON چیست؟
در JSON Lines هر خط یک مقدار JSON مستقل است:
{"id":1,"name":"A"}
{"id":2,"name":"B"}
{"id":3,"name":"C"}
این شکل برای Log، پردازش جریان و فایلهای بسیار بزرگ مفید است؛ زیرا لازم نیست کل سند یکباره در حافظه Parse شود.
JSON در فایل تنظیمات
- مقدارهای حساس را در فایل Commitشده نگه ندارید.
- Schema یا Validation برای تنظیمات داشته باشید.
- مقدار پیشفرض و رفتار فیلد حذفشده را مشخص کنید.
- نسخه ساختار تنظیمات را در نظر بگیرید.
- خطای Parse را با پیام قابل فهم گزارش کنید.
JSON با XML، YAML و CSV چه تفاوتی دارد؟
| قالب | نقطه قوت | محدودیت رایج |
|---|---|---|
| JSON | مناسب API و ساختارهای Object/Array | Comment ندارد و برای داده حجیم همیشه بهینه نیست |
| XML | Namespace، Attribute و ابزارهای قدیمی قدرتمند | Verboseتر و پیچیدهتر برای کاربرد ساده |
| YAML | خوانایی بالا برای تنظیمات انسانی | Parser و قواعد پیچیدهتر، حساسیت به تورفتگی |
| CSV | ساده و مناسب داده جدولی | ساختار تودرتو و نوع داده محدود |
بهترین روشهای طراحی JSON
یک قرارداد نامگذاری ثابت انتخاب کنید
camelCase و snake_case هر دو قابل استفادهاند. مهمتر از انتخاب، ثبات در تمام API است.
نوع ویژگی را تغییر ندهید
{"roles": "admin"}
{"roles": ["admin", "editor"]}
اگر ویژگی چندمقداری است، حتی برای یک عضو نیز Array ارسال کنید.
معنای null و فیلد حذفشده را مستند کنید
کلاینت باید بداند null به معنی «نامشخص»، «حذفشده»، «قابل اعمال نیست» یا وضعیت دیگری است.
Payload را بیش از حد تودرتو نکنید
هر سطح تودرتویی باید دلیل معنایی داشته باشد. عمق زیاد Query، تست و تغییر مدل را سخت میکند.
API را برای توسعه آینده طراحی کنید
Envelope مناسب برای فهرستها، Error Model ثابت و Versioning میتواند تغییرات آینده را کمهزینهتر کند.
اشتباهات رایج در پروژههای واقعی
- ساخت JSON با اتصال دستی رشتهها
- پذیرفتن Payload بدون Schema یا DTO
- ارسال عدد بسیار بزرگ بدون توجه به دقت کلاینت
- استفاده از تاریخ محلی مبهم
- ارسال فایل بزرگ بهصورت Base64 در JSON
- ثبت کامل داده حساس در Log
- تغییر نوع فیلد میان نسخهها
- اعتماد به ترتیب کلیدهای Object
- استفاده از کلیدهای تکراری
- انتظار پشتیبانی از Comment یا Trailing Comma
چکلیست بررسی JSON قبل از انتشار API
- آیا Syntax با Validator بررسی شده است؟
- آیا Schema یا DTO نوع فیلدها را محدود میکند؟
- آیا نامگذاری کلیدها ثابت است؟
- آیا تاریخ و منطقه زمانی قرارداد مشخص دارند؟
- آیا عددهای بزرگ در همه مصرفکنندهها دقیق میمانند؟
- آیا null، رشته خالی و فیلد حذفشده تعریف شدهاند؟
- آیا Payload محدودیت اندازه و عمق دارد؟
- آیا داده حساس از Log و خطا حذف شده است؟
- آیا پاسخ فهرست برای Pagination و Metadata آماده است؟
- آیا تغییرات نسخه جدید با کلاینت قدیمی سازگارند؟
چه زمانی از JSON استفاده کنیم؟
- داده ساختار Object و Array دارد.
- کلاینت و سرور با زبانهای مختلف نوشته شدهاند.
- خوانایی انسانی ارزشمند است.
- API وب یا تنظیمات نسبتاً ساده دارید.
- اکوسیستم ابزار و کتابخانه گسترده میخواهید.
چه زمانی JSON بهترین انتخاب نیست؟
- حجم و سرعت در مقیاس بسیار بالا حیاتی است.
- داده عمدتاً جدولی و تخت است.
- نیاز جدی به Comment در فایل تنظیمات دارید.
- Streaming رکوردهای مستقل هدف اصلی است.
- قرارداد باینری بسیار فشرده و دارای Schema لازم است.
جمعبندی
JSON یک قالب متنی ساده اما قدرتمند برای نمایش داده ساختاریافته است. Object و Array هسته ساختار آن هستند و String، Number، Boolean و null مقدارهای پایه را تشکیل میدهند. استفاده حرفهای از JSON فقط به رعایت آکولاد و ویرگول محدود نمیشود؛ باید درباره Encoding، دقت عدد، تاریخ، null، Schema، امنیت، اندازه Payload و سازگاری نسخهها نیز تصمیم روشن داشت.
برای پروژههای وب و API، JSON اغلب انتخاب پیشفرض خوبی است؛ به شرطی که با Serializer استاندارد تولید شود، ورودی آن اعتبارسنجی شود و قرارداد داده ثابت و مستند باقی بماند.