JSON là cách ghi dữ liệu thành những cặp tên và giá trị, đặt trong dấu ngoặc nhọn, có thể lồng vào nhau nhiều tầng; gần như mọi API và mọi gói webhook bạn gặp đều nói bằng định dạng này. Nó trông rối mắt lúc đầu vì toàn dấu ngoặc, dấu hai chấm và dấu phẩy, nhưng cấu trúc thì chỉ có vài loại, đọc quen sau một buổi.
Bài này giải thích JSON qua ví dụ đơn hàng giả định, chỉ cách đọc khối lồng nhau và danh sách, những bẫy như giá trị rỗng, số lưu dạng chữ, ngày giờ múi giờ, và cách ánh xạ dữ liệu vào cột bảng tính sao cho không lệch.
Đọc JSON qua một đơn hàng giả định
Hình dung một đơn hàng được mô tả bằng lời: mã đơn là DH1024, trạng thái đã thanh toán, tổng tiền là một số, khách hàng có tên và số điện thoại, đơn gồm hai sản phẩm, mỗi sản phẩm có tên và số lượng. Trong JSON, mỗi ý đó thành một cặp: tên trường đặt trong nháy kép, dấu hai chấm, rồi giá trị. Các cặp cách nhau bằng dấu phẩy, cả đơn hàng bọc trong một cặp ngoặc nhọn.
Phần khách hàng không phải một giá trị đơn mà là một khối nhỏ có tên và số điện thoại riêng, nên nó được bọc trong ngoặc nhọn thứ hai, nằm bên trong khối đơn hàng. Đây gọi là đối tượng lồng nhau. Phần sản phẩm là một danh sách nhiều món, nên được bọc trong ngoặc vuông, mỗi món bên trong lại là một khối ngoặc nhọn. Đây gọi là mảng.
Như vậy chỉ có sáu loại giá trị bạn sẽ gặp: chữ đặt trong nháy kép, số không có nháy, đúng hoặc sai, giá trị rỗng viết là null, khối ngoặc nhọn và danh sách ngoặc vuông. Biết sáu loại đó là đọc được mọi JSON, chỉ khác nhau ở độ dài và độ sâu. Nhiều trình duyệt và công cụ kéo thả hiển thị JSON dạng cây có thể bấm mở từng nhánh, dễ nhìn hơn khối chữ liền.
Khoảng trắng và xuống dòng trong JSON chỉ để người đọc dễ nhìn, máy không quan tâm. Cùng một đơn hàng có thể được trả về trên một dòng dài liền mạch hoặc dàn ra nhiều dòng thụt lề; hai cách là một. Nếu nhận về một dòng dài khó đọc, dán vào công cụ định dạng JSON hoặc bật chế độ xem dạng cây của công cụ kéo thả để thấy rõ tầng nào nằm trong tầng nào.
Sáu loại giá trị và cách công cụ kéo thả xử lý
Khi ánh xạ sang bảng tính hay ứng dụng khác, mỗi loại giá trị cần một cách đối xử riêng.
| Loại | Nhận diện | Khi đưa vào bảng tính |
|---|---|---|
| Chữ | Nằm trong nháy kép | Đưa thẳng vào ô; cẩn thận chuỗi trông như số, ví dụ mã có số 0 ở đầu |
| Số | Không có nháy | Đưa vào ô số; kiểm dấu thập phân là chấm hay phẩy theo cài đặt vùng của bảng tính |
| Đúng hoặc sai | Chữ true hoặc false không có nháy | Nên đổi thành chữ dễ hiểu như Có, Không trước khi ghi |
| Rỗng | Chữ null | Ô sẽ trống; quyết định có cần điền giá trị mặc định không |
| Đối tượng | Ngoặc nhọn | Không ghi cả khối vào một ô; chọn từng trường con cần dùng |
| Mảng | Ngoặc vuông | Cần bước lặp để mỗi phần tử thành một dòng, hoặc bước gộp để nối thành một chuỗi |
Hai loại cuối là nơi người mới hay vấp nhất. Đổ nguyên một mảng vào một ô bảng tính sẽ ra một chuỗi dài khó đọc, không lọc được, không cộng được.
Đường dẫn tới một trường nằm sâu
Đi từ ngoài vào trong. Muốn lấy số điện thoại khách, bạn đi từ khối đơn hàng vào khối khách hàng rồi lấy trường số điện thoại. Nhiều công cụ ghi đường dẫn này bằng dấu chấm hoặc dấu mũi tên giữa các tên, nhìn vào là biết trường nằm ở tầng nào.
Phần tử trong mảng có số thứ tự. Sản phẩm đầu tiên trong danh sách thường có số thứ tự 0 chứ không phải 1, thói quen của dân lập trình. Lấy nhầm số thứ tự là lấy nhầm sản phẩm thứ hai.
Tên trường phân biệt hoa thường. Một trường tên customer khác hẳn Customer. Khi gõ tay đường dẫn, sai một chữ hoa là nhận về rỗng mà không báo lỗi rõ ràng.
Cùng tên ở nhiều tầng. Trường name có thể xuất hiện ở khách hàng, ở sản phẩm, ở cửa hàng. Khi chọn trong công cụ, nhìn kỹ nhánh cha để chắc mình lấy tên khách chứ không phải tên sản phẩm.
Trường không phải lúc nào cũng có mặt. Đơn không có mã giảm giá có thể thiếu hẳn trường giảm giá chứ không phải để rỗng. Luồng tham chiếu tới trường vắng mặt có thể báo lỗi hoặc ghi trống tuỳ công cụ; thử với cả đơn có và không có giảm giá.
Ánh xạ JSON vào bảng tính không lệch cột
Ánh xạ là việc nói cho công cụ biết trường nào trong JSON đổ vào cột nào trong bảng. Làm cẩn thận một lần thì luồng chạy ổn lâu dài.
- Lấy một mẫu JSON thật từ lần gọi thử hoặc webhook thử, tốt nhất là mẫu đầy đủ nhất có thể, có đủ các trường tuỳ chọn.
- Lập bảng tính với hàng tiêu đề trước, mỗi cột một ý rõ ràng, đặt tên cột bằng tiếng Việt cho người dùng bảng dễ đọc.
- Trong bước ghi dòng của công cụ, chọn từng cột rồi chọn trường tương ứng từ mẫu JSON, đi theo đường dẫn tới đúng tầng.
- Với mảng sản phẩm, quyết định một dòng một đơn với danh sách sản phẩm gộp thành chữ, hay một dòng một sản phẩm kèm mã đơn lặp lại. Cách sau dễ thống kê hơn.
- Thêm bước định dạng cho ngày giờ và tiền trước khi ghi, để bảng tính hiểu đúng kiểu dữ liệu.
- Chạy thử với ba mẫu khác nhau: đơn đầy đủ, đơn thiếu trường tuỳ chọn, đơn nhiều sản phẩm. Kiểm từng cột bằng mắt.
Đừng thêm hay đổi thứ tự cột của bảng tính sau khi luồng đã chạy mà không kiểm lại ánh xạ. Có công cụ ánh xạ theo vị trí cột chứ không theo tên, chèn một cột vào giữa là mọi dữ liệu dịch sang phải một ô.
Ba bẫy dữ liệu hay gặp: số dạng chữ, ngày giờ, tiền tệ
Bẫy thứ nhất là mã hay số điện thoại bắt đầu bằng số 0. Nếu bảng tính tự đổi chúng thành số, số 0 đầu biến mất. Định dạng cột đó là văn bản trước khi luồng ghi vào, hoặc dùng tuỳ chọn ghi giữ nguyên giá trị của công cụ.
Bẫy thứ hai là ngày giờ. API thường trả ngày giờ theo chuẩn quốc tế, nhiều khi theo giờ UTC, chậm hơn giờ Việt Nam bảy tiếng. Một đơn đặt lúc sáu giờ sáng ngày mười lăm theo giờ Việt Nam sẽ hiện là hai mươi ba giờ ngày mười bốn theo UTC. Nếu báo cáo theo ngày mà không đổi múi giờ, đơn sáng sớm sẽ rơi vào ngày hôm trước. Thêm bước chuyển múi giờ trong công cụ trước khi ghi.
Bẫy thứ ba là tiền. Có API trả tiền dưới dạng số nguyên theo đơn vị nhỏ nhất, có API trả số thập phân, có API trả chữ kèm ký hiệu tiền tệ. Đọc kỹ phần mô tả trường trong tài liệu, và so một đơn với số tiền bạn biết chắc để xác nhận đơn vị trước khi đổ hàng nghìn dòng vào bảng.
Đọc khối JSON báo lỗi
Khi một lần gọi API thất bại, phần lớn API không chỉ trả mã trạng thái mà còn kèm một khối JSON giải thích. Khối này thường có vài trường quen thuộc: một mã lỗi dạng chữ ngắn do bên cung cấp đặt, một câu mô tả lỗi bằng tiếng Anh, và đôi khi một danh sách chi tiết chỉ đúng trường nào trong yêu cầu của bạn có vấn đề. Tên trường cụ thể khác nhau giữa các hãng, nhưng nhìn qua là nhận ra vì chúng hay có chữ error, message, code hoặc details.
Người mới hay bỏ qua khối này vì công cụ kéo thả chỉ hiện một dòng đỏ chung chung là bước thất bại. Hãy mở chi tiết lần chạy, tìm phần nội dung phản hồi, đọc câu mô tả. Những câu như trường email không hợp lệ, thiếu trường bắt buộc, giá trị vượt độ dài cho phép chỉ thẳng vào chỗ cần sửa, nhanh hơn nhiều so với đoán mò. Nếu danh sách chi tiết có đường dẫn tới trường, đó chính là đường dẫn trong khối JSON bạn đã gửi.
Một lưu ý: khối lỗi đôi khi lặp lại nguyên dữ liệu bạn gửi, kể cả thông tin của khách. Khi chụp màn hình lỗi để hỏi đồng nghiệp hay dán cho chatbot, che phần đó và mọi khoá xuất hiện trong tiêu đề. Lời mô tả lỗi là đủ để người khác giúp bạn.
Nhờ AI đọc JSON giúp và giới hạn của cách này
Khi gặp một khối JSON dài vài trăm dòng, chatbot AI có thể giúp bạn nắm cấu trúc nhanh. Câu lệnh mẫu: Dưới đây là một mẫu JSON đơn hàng. Hãy liệt kê các trường cấp đầu, các khối lồng nhau, các mảng, và chỉ ra đường dẫn tới mã đơn, tên người nhận, danh sách sản phẩm và tổng tiền. Trả lời dạng bảng hai cột gồm ý nghĩa và đường dẫn.
Trước khi dán, thay dữ liệu thật của khách bằng giá trị giả: tên thành Khách A, số điện thoại thành chuỗi số giả, địa chỉ thành Phường X. AI chỉ cần cấu trúc, không cần nội dung thật. Nếu mẫu JSON quá dài, cắt bớt các phần tử lặp trong mảng, giữ lại một hai phần tử là đủ thể hiện cấu trúc.
AI cũng có thể sai, ví dụ đoán một trường là tổng tiền trong khi đó là tạm tính chưa gồm phí giao hàng. Dùng câu trả lời của AI làm bản đồ ban đầu, rồi xác nhận lại với tài liệu API và với một đơn thật bạn biết rõ số liệu. Khi luồng có bước AI xử lý JSON ngay trong lúc chạy, ví dụ trích thông tin từ một trường ghi chú tự do, hãy yêu cầu AI trả kết quả cũng ở dạng JSON với tên trường cố định, và thêm bước kiểm kết quả có đúng cấu trúc không trước khi ghi.
Câu hỏi thường gặp
JSON khác bảng tính thế nào?
Bảng tính là lưới phẳng hàng và cột. JSON cho phép lồng nhiều tầng, một đơn hàng chứa khách hàng, chứa danh sách sản phẩm. Khi chuyển JSON sang bảng tính, bạn phải quyết định làm phẳng các tầng đó ra sao.
Có cần học cú pháp JSON để tự viết không?
Phần lớn thời gian bạn chỉ đọc JSON và chọn trường trong công cụ. Khi cần tự viết nội dung gửi đi, nên chép mẫu từ tài liệu API rồi thay giá trị, và dùng công cụ kiểm JSON trực tuyến hoặc chế độ nhập từng cặp tên giá trị để tránh sai dấu.
Vì sao trường đã chọn luôn ra trống?
Thường do đường dẫn sai tầng, sai hoa thường, hoặc trường không có mặt trong lần chạy đó. So mẫu JSON của lần chạy thật với mẫu dùng khi ánh xạ, chúng có thể khác nhau nếu đơn thiếu thông tin tuỳ chọn.
JSON có chứa dữ liệu khách hàng không cần thiết không?
Thường là có, vì API trả cả khối đầy đủ. Chỉ ánh xạ những trường cần dùng và chỉ chuyển cho bước sau, đặc biệt bước AI, những trường thật sự cần, để giảm số nơi dữ liệu cá nhân đi qua.
Ngày giờ trong bảng bị lệch một ngày là do đâu?
Rất có thể do API trả giờ UTC trong khi bạn báo cáo theo giờ Việt Nam. Thêm bước chuyển múi giờ trước khi ghi, rồi kiểm lại bằng một đơn đặt lúc sáng sớm.
AI có thể tự sửa JSON bị lỗi không?
AI sửa được lỗi thiếu dấu phẩy hay ngoặc khá tốt khi bạn dán vào hỏi. Nhưng nếu JSON lỗi đến từ ứng dụng nguồn, sửa tay một lần không giải quyết được gốc; cần tìm vì sao ứng dụng gửi dữ liệu hỏng hoặc vì sao bước chèn biến làm vỡ cấu trúc.