JSON5 và JSONC sang JSON chuẩn: gỡ chú thích, dấu phẩy thừa và cú pháp nới lỏng
Công cụ đọc nội dung viết theo cú pháp nới lỏng của JSON5 hoặc JSONC rồi ghi ra JSON đúng đặc tả. Nó xử lý chú thích hai kiểu, dấu phẩy thừa cuối khối, khóa không nháy, chuỗi nháy đơn, chuỗi nối dòng, số hệ mười sáu, số có dấu cộng đầu cùng ba literal Infinity và NaN, đồng thời báo lỗi kèm số dòng và số cột.
Tính năng nổi bật
- Bỏ chú thích một dòng bắt đầu bằng hai gạch chéo và chú thích khối đặt giữa gạch chéo với dấu sao
- Chấp nhận dấu phẩy thừa sau phần tử cuối của mảng và sau cặp khóa giá trị cuối của đối tượng
- Đọc được khóa viết trần không nháy và chuỗi bọc bằng nháy đơn
- Nối chuỗi trải nhiều dòng khi cuối dòng có dấu gạch chéo ngược
- Hiểu số hệ mười sáu, số có dấu cộng ở đầu, số thiếu phần nguyên hoặc thiếu phần thập phân
- Nhận ba literal Infinity, âm Infinity và NaN, kèm cảnh báo khi ghi ra JSON chuẩn
- Chiều ngược lại sinh JSON5 gọn hơn: khóa bỏ nháy khi được, nháy đơn và dấu phẩy cuối tùy chọn
- Thông báo lỗi chỉ đúng dòng và cột, kèm mô tả cụ thể thay vì một câu chung chung
Vì sao dán tệp cấu hình có chú thích vào công cụ JSON thường thất bại
Đặc tả JSON cố tình rất hẹp. Nó không có chú thích, không cho dấu phẩy thừa, bắt mọi khóa phải bọc nháy kép, và chỉ chấp nhận nháy kép cho chuỗi. Sự khắt khe đó là ưu điểm khi máy trao đổi với máy, nhưng thành phiền toái khi con người viết tay tệp cấu hình. Vì vậy nhiều công cụ quen thuộc đã lặng lẽ nới cú pháp: tệp cấu hình trình biên dịch TypeScript và tệp thiết lập của trình soạn thảo Visual Studio Code đều cho phép chú thích và dấu phẩy thừa. Hậu quả là khi bạn chép nội dung đó dán vào một công cụ JSON thông thường, nó báo lỗi ngay ký tự đầu tiên của dòng chú thích, và bạn phải ngồi xóa tay từng dòng. Trang này làm đúng việc đó bằng máy: đọc bằng bộ phân tích chấp nhận cú pháp nới lỏng, rồi ghi ra JSON đúng đặc tả để dán tiếp vào bất kỳ chỗ nào yêu cầu JSON chuẩn.
Lợi ích khi sử dụng
- Không phải xóa tay từng dòng chú thích trước khi dán vào công cụ khác
- Lỗi cú pháp được chỉ tận dòng và cột nên sửa nhanh hơn nhiều so với thông báo mặc định của trình duyệt
- Chiều ngược lại giúp làm gọn tệp cấu hình dài, bớt hàng loạt dấu nháy thừa quanh tên khóa
- Biết trước những giá trị nào sẽ bị đổi nghĩa thay vì phát hiện lúc chạy
- Dán được tệp thiết lập cá nhân mà không lo lộ đường dẫn hay khóa nội bộ
Cách chuyển JSON5 sang JSON chuẩn
- 1Chọn chiều chuyển đổi, mặc định là từ JSON5 hoặc JSONC sang JSON chuẩn.
- 2Dán nguyên nội dung vào ô bên trái, giữ nguyên chú thích và dấu phẩy thừa, không cần dọn trước.
- 3Chọn mức thụt lề cho kết quả, hai dấu cách, bốn dấu cách hoặc nén về một dòng.
- 4Bấm chuyển đổi. Nếu báo lỗi, mở đúng dòng và cột ghi trong thông báo, phần lớn là thiếu dấu phẩy hoặc chuỗi chưa đóng.
- 5Đọc dòng cảnh báo màu vàng nếu có, nó cho biết những giá trị không tồn tại trong JSON chuẩn đã bị xử lý thế nào.
JSON5 và JSONC không phải một thứ, dù trông rất giống
Hai cái tên này hay bị dùng lẫn nhưng chúng khác nhau về phạm vi. JSONC nghĩa là JSON có chú thích, và về cơ bản nó chỉ thêm đúng hai thứ so với JSON chuẩn: chú thích, và ở đa số bộ đọc là dấu phẩy thừa. Mọi quy tắc còn lại vẫn giữ nguyên, khóa vẫn phải bọc nháy kép, chuỗi vẫn phải dùng nháy kép, số vẫn viết theo luật cũ. Đây là dạng bạn gặp trong tệp cấu hình trình biên dịch TypeScript và tệp thiết lập của một số trình soạn thảo. JSON5 thì tham vọng hơn nhiều, nó cố kéo cú pháp JSON về gần với cú pháp viết đối tượng trong JavaScript hiện đại. Ngoài chú thích và dấu phẩy thừa, nó cho phép khóa viết trần khi là định danh hợp lệ, cho phép chuỗi bọc nháy đơn, cho phép chuỗi trải nhiều dòng bằng dấu gạch chéo ngược cuối dòng, cho phép số hệ mười sáu, số có dấu cộng ở đầu, số thiếu phần nguyên hoặc thiếu phần thập phân, và thêm ba literal đặc biệt là Infinity, âm Infinity cùng NaN. Bộ đọc trong công cụ này chấp nhận toàn bộ tập rộng của JSON5, nên tệp JSONC hiển nhiên cũng đọc được. Điều cần nhớ theo chiều ngược lại: một tệp JSON5 hợp lệ chưa chắc là tệp JSONC hợp lệ, nên đừng cho rằng công cụ nào đọc được JSONC thì cũng đọc được JSON5.
Ba literal không có chỗ đứng trong JSON chuẩn
Đặc tả JSON chỉ có sáu loại giá trị: chuỗi, số, đúng sai, rỗng, mảng và đối tượng. Trong đó số được định nghĩa là một dãy chữ số theo khuôn thập phân, và khuôn đó không bao gồm ba giá trị đặc biệt mà phép tính dấu chấm động sinh ra được, tức vô cực dương, vô cực âm và giá trị không phải số. JSON5 thì có, vì nó bám theo JavaScript. Khi bạn chuyển một tệp JSON5 chứa những giá trị này sang JSON chuẩn, không có cách nào biểu diễn đúng, và cách hành xử phổ biến nhất trong hệ sinh thái JavaScript là ghi chúng thành giá trị rỗng. Công cụ này làm đúng như vậy nhưng không im lặng: nó đếm số giá trị bị đổi và hiện một dòng cảnh báo màu vàng cho biết đã có bao nhiêu chỗ bị thay. Nếu những con số đó mang ý nghĩa trong ứng dụng của bạn, chẳng hạn vô cực dùng để nói không giới hạn, hãy tự chọn một quy ước trước khi chuyển: đổi thành chuỗi mang đúng chữ, đổi thành một số cực lớn có ý nghĩa thực tế, hoặc bỏ hẳn khóa đó và để phía nhận tự hiểu là không giới hạn. Việc quyết định phải là của bạn chứ không nên để bộ chuyển đổi âm thầm quyết hộ, vì giá trị rỗng và vô cực nói hai chuyện hoàn toàn khác nhau.
Chú thích chỉ đi được một chiều, và điều đó ảnh hưởng tới cách bạn quản lý tệp
Chú thích là lý do lớn nhất khiến người ta dùng JSON5 hoặc JSONC, và cũng là thứ không bao giờ sống sót qua chuyến đi. Khi đọc, chú thích bị bỏ qua ngay ở bước phân tích, nó không được lưu vào cây dữ liệu vì cây dữ liệu chỉ chứa khóa và giá trị. Vì vậy chiều từ JSON chuẩn sang JSON5 không thể sinh lại chú thích, dù bản JSON đó vốn được tạo ra từ một tệp JSON5 đầy chú thích năm phút trước. Hệ quả thực tế rất rõ ràng: đừng lấy bản JSON đã chuyển ghi đè lên tệp cấu hình gốc. Cách làm đúng là coi tệp có chú thích là bản chính do người viết và giữ trong hệ thống quản lý mã nguồn, còn bản JSON chuẩn chỉ là bản sinh ra để nạp vào công cụ khác, giống như quan hệ giữa mã nguồn và bản dịch. Nếu quy trình của bạn bắt buộc phải sinh JSON chuẩn ở mỗi lần dựng, hãy đưa bước chuyển đổi vào quy trình đó thay vì làm tay, và ghi rõ trong kho mã rằng tệp JSON là kết quả sinh tự động để người sau không sửa nhầm vào bản sinh. Chiều ngược lại của công cụ vẫn có ích ở chỗ khác: nó làm gọn một khối JSON dài bằng cách bỏ nháy quanh tên khóa, dùng nháy đơn và thêm dấu phẩy cuối, cho bạn một khung sạch để bắt đầu viết chú thích lên đó.
Đọc thông báo lỗi cú pháp cho đúng chỗ
Thông báo lỗi mặc định khi phân tích JSON trong trình duyệt thường chỉ nói không đọc được ký tự nào đó tại một vị trí tính theo số ký tự tính từ đầu chuỗi, một con số gần như vô dụng khi tệp dài vài trăm dòng. Bộ đọc ở đây quy đổi vị trí đó thành dòng và cột, đồng thời mô tả chuyện đang xảy ra bằng lời cụ thể. Có bốn nhóm lỗi hay gặp. Nhóm thứ nhất là thiếu dấu phẩy giữa hai cặp khóa giá trị, thường xuất hiện sau khi bạn chép thêm một dòng từ chỗ khác vào; thông báo sẽ chỉ vào đầu dòng tiếp theo chứ không phải cuối dòng thiếu phẩy, nên hãy nhìn lên dòng ngay trên. Nhóm thứ hai là chuỗi chưa đóng, thường do một dấu nháy bị xóa nhầm; vị trí báo lỗi rơi vào cuối tệp hoặc cuối dòng chứ không phải chỗ mở nháy, vì bộ đọc phải chạy tới đó mới biết là thiếu. Nhóm thứ ba là chú thích khối mở bằng gạch chéo với dấu sao mà không có cặp đóng, khi đó toàn bộ phần còn lại của tệp bị nuốt và thông báo sẽ chỉ về đúng vị trí mở chú thích. Nhóm thứ tư là tên khóa không hợp lệ, xảy ra khi khóa viết trần bắt đầu bằng chữ số hoặc chứa dấu gạch nối; muốn dùng những tên đó thì bắt buộc phải bọc nháy, kể cả trong JSON5.
Trang này làm gì và không làm gì, so với các công cụ JSON khác
Ranh giới ở đây rất hẹp và cố ý như vậy: trang này chỉ dịch giữa cú pháp nới lỏng và cú pháp chặt, trong cùng một mô hình dữ liệu. Nó không kiểm tra dữ liệu có hợp lý hay không, không so sánh hai tệp, không truy vấn giá trị theo đường dẫn và không sinh mã. Nếu việc bạn cần là làm đẹp, thu gọn hay kiểm tra tính hợp lệ của một khối JSON vốn đã đúng cú pháp, hãy dùng /vi/tools/json-formatter. Nếu bạn cần biết hai phiên bản của một tệp khác nhau ở đâu, dùng /vi/tools/json-diff hoặc /vi/tools/json-compare. Nếu bạn cần lấy ra một giá trị nằm sâu trong cấu trúc, dùng /vi/tools/json-path-finder. Nếu bạn muốn dựng lược đồ mô tả cấu trúc để kiểm định về sau, dùng /vi/tools/json-schema-generator. Nếu tệp cấu hình bạn đang xử lý không phải họ JSON mà là TOML hoặc YAML, trang tương ứng là /vi/tools/toml-converter và /vi/tools/json-yaml. Còn khi bạn đã có JSON chuẩn và muốn sinh khai báo kiểu cho mã nguồn, ba trang chuyên biệt là /vi/tools/json-to-typescript, /vi/tools/json-to-go-struct và /vi/tools/json-to-python-dataclass. Cách phối hợp hợp lý là bắt đầu ở trang này để có JSON sạch, rồi mới chuyển sang trang chuyên cho việc tiếp theo.
Câu hỏi thường gặp (FAQ)
JSON5 và JSONC khác nhau thế nào?
JSONC chỉ thêm chú thích và thường là dấu phẩy thừa, mọi quy tắc còn lại giữ nguyên như JSON chuẩn. JSON5 mở rộng hơn nhiều: khóa không nháy, chuỗi nháy đơn, chuỗi nối dòng, số hệ mười sáu, số có dấu cộng đầu và ba literal đặc biệt. Bộ đọc ở đây chấp nhận tập rộng của JSON5 nên đọc được cả hai.
Tệp cấu hình trình biên dịch TypeScript có dán thẳng vào được không?
Được, đó là trường hợp điển hình. Tệp đó là JSONC nên có chú thích và thường có dấu phẩy thừa, cả hai đều nằm trong phạm vi bộ đọc. Kết quả trả về là JSON đúng đặc tả, dán tiếp vào chỗ nào cũng được, chỉ nhớ là toàn bộ chú thích giải thích từng tùy chọn sẽ không còn.
Giá trị Infinity và NaN bị xử lý ra sao khi ghi ra JSON chuẩn?
Chúng bị ghi thành giá trị rỗng vì JSON chuẩn không định nghĩa ba literal này. Công cụ đếm và hiện cảnh báo cho biết có bao nhiêu chỗ bị đổi. Nếu chúng mang ý nghĩa trong ứng dụng của bạn, hãy tự chọn quy ước thay thế trước khi chuyển, ví dụ đổi thành chuỗi hoặc bỏ hẳn khóa đó.
Chiều từ JSON sang JSON5 có tự sinh chú thích không?
Không thể, vì chú thích không tồn tại trong cây dữ liệu. Chiều này chỉ làm gọn phần cú pháp: bỏ nháy quanh tên khóa khi tên đó là định danh hợp lệ, đổi sang nháy đơn và thêm dấu phẩy cuối nếu bạn bật tùy chọn. Phần giải thích vẫn phải bạn tự viết vào.
Vì sao khóa của tôi báo lỗi tên không hợp lệ dù không bọc nháy vẫn thấy nhiều nơi làm vậy?
Khóa viết trần chỉ hợp lệ khi nó là định danh, tức bắt đầu bằng chữ cái, dấu gạch dưới hoặc ký hiệu đô la, và các ký tự sau là chữ cái, chữ số hoặc hai dấu đó. Khóa bắt đầu bằng chữ số, chứa dấu gạch nối hay dấu cách đều phải bọc nháy, kể cả trong JSON5.
Chuỗi trải nhiều dòng viết thế nào cho đúng?
Đặt một dấu gạch chéo ngược ở ngay cuối dòng rồi xuống dòng viết tiếp. Khi đọc, phần xuống dòng bị nuốt và hai phần chuỗi nối liền nhau thành một dòng duy nhất. Nếu bạn thật sự muốn có ký tự xuống dòng trong giá trị, hãy dùng mã thoát chữ n thay vì cách nối dòng này.
Dấu phẩy thừa có phải luôn được chấp nhận không?
Ở đầu vào của công cụ thì có, cả trong mảng lẫn trong đối tượng. Nhưng ở đầu ra JSON chuẩn thì không bao giờ, vì đặc tả cấm. Đây cũng là lý do một tệp chạy tốt trong trình soạn thảo lại làm hỏng bước phân tích ở máy chủ, nơi người ta dùng bộ đọc JSON chặt.
Số viết hệ mười sáu chuyển sang JSON chuẩn thì thành gì?
Thành số thập phân tương ứng, vì JSON chuẩn không có cách viết hệ mười sáu. Giá trị không đổi, chỉ cách viết đổi. Nếu con số đó là mặt nạ bit hay mã màu mà bạn muốn giữ nguyên hình dạng cho dễ đọc, hãy chuyển nó thành chuỗi trước khi đổi.
Thông báo lỗi chỉ vào dòng ngay dưới chỗ tôi nghĩ là sai, vì sao?
Vì bộ đọc chỉ biết thiếu dấu phẩy khi nó đã đọc xong giá trị trước và gặp thứ không mong đợi ở phần tử kế tiếp. Khi thông báo chỉ vào đầu một dòng, hãy nhìn lên dòng ngay trên đó trước. Với lỗi chuỗi chưa đóng thì ngược lại, vị trí báo lỗi thường ở tận cuối vì bộ đọc phải chạy hết mới biết thiếu nháy đóng.
Công cụ có kiểm tra dữ liệu đúng cấu trúc mong muốn không?
Không, nó chỉ kiểm tra cú pháp. Việc kiểm tra trường nào bắt buộc, kiểu nào hợp lệ, giá trị nằm trong khoảng nào thuộc về lược đồ. Hãy dựng lược đồ tại /vi/tools/json-schema-generator rồi dùng nó để kiểm định trong quy trình của bạn.
Nén về một dòng có làm hỏng chuỗi có ký tự xuống dòng không?
Không. Ký tự xuống dòng nằm trong giá trị chuỗi được ghi lại bằng mã thoát chữ n chứ không phải bằng dấu xuống dòng thật, nên nội dung giữ nguyên. Chế độ nén chỉ bỏ khoảng trắng dùng để trình bày giữa các khóa, giá trị và dấu ngoặc.
Nội dung dán vào có bị gửi đi đâu không?
Không. Bộ phân tích và bộ ghi đều chạy bằng JavaScript ngay trong trình duyệt. Nhờ vậy bạn dán được tệp thiết lập cá nhân hay tệp cấu hình dự án nội bộ, kể cả khi trong đó có đường dẫn máy trạm hay tên máy chủ riêng.
Từ khóa liên quan
- json5 converter
- chuyển json5 sang json
- jsonc là gì
- json có chú thích
- xóa comment trong json
- dấu phẩy thừa json
- tsconfig json có comment
- lỗi json unexpected token
- json5 là gì
- khóa không cần nháy json
- chuỗi nháy đơn json
- số hex trong json
- infinity nan trong json
- json chuẩn khác json5
- sửa lỗi cú pháp json
- làm sạch file json
- json parse báo lỗi dòng nào
- chuyển json sang json5
- công cụ json cho lập trình viên
- định dạng cấu hình cho phép chú thích
