Chuyển đổi JSON sang TOML (JSON to TOML Converter)

Giới thiệu về Chuyển đổi JSON sang TOML (JSON to TOML Converter)

Chuyển đổi JSON sang TOML (JSON to TOML Converter) là công cụ web giúp biến dữ liệu JSON thành văn bản cấu hình TOML ngay trong trình duyệt. Thay vì sửa từng dấu ngoặc, dấu phẩy và cách khai báo thuộc tính, công cụ đọc cấu trúc dữ liệu đầu vào rồi tạo đầu ra bằng thư viện chuyên xử lý TOML.

JSON phổ biến trong API, ứng dụng web và trao đổi dữ liệu giữa các hệ thống. TOML thường được dùng cho tệp cấu hình nhờ cách trình bày rõ ràng bằng các cặp khóa – giá trị và nhóm cấu hình. Khi một ứng dụng yêu cầu TOML nhưng dữ liệu hiện có lại ở dạng JSON, việc chuyển đổi tự động giúp giảm thao tác lặp lại và hạn chế lỗi cú pháp.

Ngoài chế độ mặc định JSON → TOML, mã nguồn còn có cơ chế xử lý TOML → JSON, TOML → YAML và YAML → TOML. Các chế độ được xác định theo địa chỉ trang; nút đảo chiều cho phép chuyển ngược cặp định dạng hiện tại.

Điểm đáng chú ý là việc phân tích và chuyển đổi dữ liệu diễn ra phía trình duyệt. Trong phần mã được cung cấp, không có thao tác gửi nội dung cấu hình lên máy chủ để xử lý.

Giải thích các thuật ngữ và thông số

JSON, TOML và YAML là gì?

• JSON — JavaScript Object Notation: định dạng dữ liệu gồm đối tượng, mảng, chuỗi, số, giá trị boolean và null. JSON chuẩn yêu cầu tên thuộc tính và chuỗi dùng dấu nháy kép, không chấp nhận chú thích hoặc dấu phẩy thừa.
• TOML — Tom’s Obvious, Minimal Language: định dạng thường dùng cho cấu hình, biểu diễn dữ liệu bằng cú pháp như port = 8080 và các bảng như [database]. TOML có kiểu ngày giờ riêng nhưng không có giá trị null tương đương JSON.
• YAML — YAML Ain’t Markup Language: định dạng dữ liệu có thể biểu diễn ánh xạ, danh sách và giá trị đơn. YAML thường dùng thụt lề để thể hiện cấu trúc lồng nhau.

Các trường đầu vào, đầu ra và trạng thái

Các trường này là văn bản và lựa chọn định dạng, không phải đại lượng có đơn vị đo như giây, mét hay byte. Mã nguồn không đặt giới hạn số ký tự cụ thể; khả năng xử lý thực tế phụ thuộc dung lượng dữ liệu, bộ nhớ và hiệu năng của trình duyệt.

Yêu cầu đối với cấu trúc dữ liệu

Ở cấp gốc, công cụ chỉ chấp nhận dạng đối tượng, chẳng hạn {"name": "demo", "port": 8080}. Các giá trị như 123, "demo", null hoặc [1, 2, 3] có thể là JSON hợp lệ, nhưng không đáp ứng điều kiện đầu vào của công cụ.

Mảng vẫn có thể nằm bên trong đối tượng, ví dụ {"ports": [8080, 8081]}. Tương tự, các đối tượng lồng nhau có thể được chuyển thành bảng TOML. Tuy nhiên, dữ liệu còn phải biểu diễn được trong định dạng đích: một thuộc tính chứa null không có giá trị TOML tương ứng trực tiếp.

Các thông số định dạng đầu ra

• JSON: đầu ra được định dạng với mức thụt lề 2 dấu cách thông qua JSON.stringify(parsedObj, null, 2).
• YAML: mức thụt lề được đặt là 2; lineWidth: -1 không áp dụng giới hạn độ rộng dòng cho việc tự ngắt dòng theo tùy chọn này.
• TOML: cách trình bày do hàm stringify của thư viện smol-toml quyết định; giao diện không có tùy chọn chỉnh thụt lề hoặc phong cách xuất.

Mối quan hệ cốt lõi là: định dạng nguồn quyết định cách đọc, cấu trúc dữ liệu quyết định khả năng chuyển đổi, còn định dạng đích quyết định cách trình bày kết quả.

Mục đích và lợi ích

Giảm công việc chỉnh sửa cấu hình thủ công

Chuyển JSON sang TOML không chỉ là thay dấu hai chấm bằng dấu bằng. Đối tượng lồng nhau cần được biểu diễn thành bảng, chuỗi cần được xử lý ký tự đặc biệt, còn mảng và giá trị boolean phải giữ đúng kiểu dữ liệu. Công cụ tự động hóa các thao tác này thông qua bộ phân tích và bộ xuất dữ liệu.

Giá trị thực tế thể hiện rõ khi chuyển cấu hình ứng dụng, thiết lập môi trường phát triển hoặc dữ liệu mẫu từ hệ thống dùng JSON sang hệ thống dùng TOML.

Phản hồi nhanh trong quá trình chỉnh sửa

Mỗi lần nội dung đầu vào thay đổi, công cụ thực hiện lại quá trình chuyển đổi. Với các tệp cấu hình thông thường, người dùng có thể nhìn thấy kết quả hoặc lỗi ngay trong quá trình soạn thảo, không cần gửi biểu mẫu đến máy chủ.

Tốc độ thực tế phụ thuộc kích thước dữ liệu và thiết bị. Công cụ không dùng cơ chế trì hoãn xử lý sau khi gõ, nên dữ liệu lớn sẽ cần nhiều tài nguyên hơn khi được phân tích lại liên tục.

Hạn chế lỗi cú pháp, nhưng không thay thế kiểm tra nghiệp vụ

So với chuyển đổi bằng cách tìm và thay thế văn bản, việc phân tích cấu trúc giúp xử lý chính xác hơn các đối tượng lồng nhau, chuỗi có ký tự thoát và mảng dữ liệu.

Tuy nhiên, trạng thái “Hợp lệ” chỉ cho biết dữ liệu đã được đọc và xuất thành công. Nó không xác nhận rằng tên tham số, số cổng, đường dẫn hay thông tin kết nối phù hợp với ứng dụng sử dụng cấu hình.

Các tính năng nổi bật

• Chuyển đổi tự động theo nội dung: kết quả được cập nhật khi có sự kiện nhập liệu, không cần nút chuyển đổi riêng.
• Hỗ trợ JSON, TOML và YAML: bộ xử lý tích hợp JSON.parse, js-yaml và smol-toml.
• Đảo chiều cặp định dạng: nút Swap đổi định dạng nguồn và đích, đồng thời đưa kết quả hiện tại sang ô đầu vào để chuyển đổi ngược.
• Kiểm tra cú pháp và khả năng chuyển đổi: lỗi được hiển thị trong khung riêng, kèm trạng thái cảnh báo và nội dung giải thích.
• Sao chép kết quả: sử dụng Clipboard API và hiển thị xác nhận khi sao chép thành công.
• Xóa nội dung nhanh: làm trống đầu vào, xóa kết quả và đưa trạng thái về chờ nhập liệu.
• Đầu ra chỉ đọc: giúp phân biệt rõ dữ liệu nguồn với kết quả được tạo tự động.
• Bố cục thích ứng: hai vùng dữ liệu nằm cạnh nhau từ độ rộng 768 px; ở màn hình hẹp hơn, chúng được xếp theo chiều dọc.

Các ô định dạng trong giao diện bị khóa, vì vậy đây không phải menu tự do để chọn mọi cặp chuyển đổi. Chế độ ban đầu được xác định từ URL, còn Swap đảo ngược cặp đang hoạt động. Không có tùy chọn tính toán số học, lọc thuộc tính hay kiểm tra cấu hình theo schema trong phần mã này.

Một hành vi cần lưu ý là Swap lấy nội dung từ ô kết quả. Nếu kết quả đang rỗng do lỗi, nội dung được đưa sang đầu vào khi đảo chiều cũng sẽ rỗng.

Đối tượng sử dụng

• Lập trình viên ứng dụng: chuyển dữ liệu cấu hình JSON sang TOML cho dự án, thư viện hoặc công cụ phát triển.
• Kỹ sư DevOps và quản trị hệ thống: chuẩn hóa cấu hình giữa các thành phần sử dụng những định dạng khác nhau.
• Kỹ sư kiểm thử: tạo dữ liệu cấu hình mẫu, kiểm tra cú pháp và đối chiếu cấu trúc sau chuyển đổi.
• Người viết tài liệu kỹ thuật: tạo ví dụ JSON, TOML hoặc YAML từ cùng một cấu trúc dữ liệu.
• Sinh viên và người học lập trình: quan sát cách đối tượng, mảng và kiểu dữ liệu được biểu diễn ở từng định dạng.

Công cụ phù hợp với người mới nhờ phản hồi trực quan, nhưng kiến thức cơ bản về khóa – giá trị, đối tượng lồng nhau và mảng sẽ giúp đánh giá kết quả tốt hơn. Với cấu hình triển khai thực tế, người dùng vẫn cần hiểu yêu cầu riêng của phần mềm đích.

Nguyên lý hoạt động và công thức

Mô hình chuyển đổi: đọc cấu trúc rồi xuất lại

Công cụ không thay thế ký tự trực tiếp trên chuỗi JSON. Nó chuyển văn bản nguồn thành một đối tượng JavaScript trung gian, sau đó tuần tự hóa đối tượng này sang định dạng đích.

Văn bản đích = Bộ xuất đích(Bộ phân tích nguồn(Văn bản đầu vào))

Đây là phép biến đổi cấu trúc dữ liệu, không phải công thức toán học hay vật lý. Mục tiêu là giữ ý nghĩa dữ liệu trong phạm vi các kiểu mà hai định dạng và thư viện có thể biểu diễn.

Logic xử lý từng bước

1. Chuẩn bị thư viện: trình duyệt tải js-yaml và nhập module smol-toml để có các hàm đọc, xuất TOML.
2. Xác định chế độ: địa chỉ trang được kiểm tra để thiết lập cặp định dạng. Nếu không khớp các chế độ được khai báo, công cụ dùng JSON → TOML.
3. Chuẩn hóa đầu vào: nội dung được xử lý bằng trim() để bỏ khoảng trắng ở hai đầu toàn bộ văn bản. Nếu không còn nội dung, kết quả được xóa.
4. Phân tích văn bản: JSON dùng JSON.parse, YAML dùng jsyaml.load, TOML dùng hàm parse của smol-toml.
5. Kiểm tra cấp gốc: dữ liệu phải có kiểu object, khác null và không phải mảng.
6. Xuất định dạng đích: đối tượng trung gian được đưa vào bộ xuất JSON, YAML hoặc TOML tương ứng.
7. Cập nhật giao diện: nếu thành công, hiển thị kết quả và trạng thái hợp lệ; nếu có ngoại lệ, xóa kết quả và hiển thị thông báo lỗi.

Điều kiện cấp gốc có thể biểu diễn như sau:

Đầu vào được chấp nhận khi: kiểu dữ liệu = object ∧ dữ liệu ≠ null ∧ dữ liệu không phải mảng.

Phạm vi của kiểm tra thời gian thực

Chức năng được giới thiệu là linting thực chất dựa vào việc thử phân tích và xuất dữ liệu mỗi khi nội dung thay đổi. Nó không phải bộ kiểm tra phong cách mã hay trình xác thực theo schema.

Nhãn chung “Lỗi cú pháp” có thể xuất hiện cho nhiều tình huống: JSON sai cú pháp, cấp gốc không phải đối tượng, thư viện TOML chưa sẵn sàng hoặc dữ liệu không thể xuất sang TOML. Vì vậy, phần thông báo chi tiết có ý nghĩa hơn nhãn trạng thái trong việc xác định nguyên nhân.

Ví dụ thực tế

Chuyển cấu hình dịch vụ từ JSON sang TOML

Một dịch vụ có cấu hình JSON gồm tên ứng dụng, cờ bật tính năng, danh sách cổng và thông tin cơ sở dữ liệu:

{
  "app_name": "inventory-service",
  "enabled": true,
  "ports": [8080, 8081],
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "inventory"
  }
}

Kết quả TOML có thể được biểu diễn như sau:

app_name = "inventory-service"
enabled = true
ports = [8080, 8081]

[database]
host = "localhost"
port = 5432
name = "inventory"

Đối tượng database trở thành bảng [database]. Các số vẫn là số, true vẫn là boolean và danh sách cổng vẫn là mảng. Cách bố trí khoảng trắng cụ thể do thư viện xuất TOML quyết định.

Trong tình huống này, công cụ giúp tái sử dụng cấu hình khi chuyển sang phần mềm nhận TOML. Nó không tự xác minh rằng localhost có thể kết nối hay cổng 5432 đang hoạt động.

Chuyển một nhóm máy chủ thành mảng bảng TOML

{
  "servers": [
    {
      "name": "api",
      "port": 3000
    },
    {
      "name": "worker",
      "port": 3001
    }
  ]
}

Dạng TOML tương ứng:

[[servers]]
name = "api"
port = 3000

[[servers]]
name = "worker"
port = 3001

Cú pháp [[servers]] biểu thị từng phần tử trong mảng bảng. Đây là trường hợp chuyển thủ công dễ nhầm giữa một bảng đơn và nhiều đối tượng cùng thuộc một danh sách.

Phân biệt JSON hợp lệ với dữ liệu phù hợp để chuyển đổi

Đầu vào sau đúng cú pháp JSON nhưng bị công cụ từ chối vì là mảng ở cấp gốc:

[8080, 8081]

Thông báo kiểm tra là: “Dữ liệu gốc phải là một Object (Dictionary) hợp lệ.” Nếu các giá trị này thực sự là danh sách cổng trong cấu hình, cấu trúc có tên thuộc tính như dưới đây phù hợp hơn:

{
  "ports": [8080, 8081]
}

Một tình huống khác là {"token": null}: dữ liệu vượt qua điều kiện đối tượng cấp gốc nhưng null không có biểu diễn trực tiếp trong TOML. Việc bỏ thuộc tính hay thay bằng giá trị khác phải dựa trên ý nghĩa cấu hình, không nên coi chuỗi "null" là giá trị tương đương.

Những thông tin thú vị xung quanh chủ đề này

TOML gần với cấu hình, JSON gần với trao đổi dữ liệu

Cùng một cấu trúc có thể viết bằng nhiều định dạng, nhưng trải nghiệm đọc khác nhau. TOML nhóm các thiết lập bằng tên bảng, trong khi JSON mô tả cấu trúc bằng dấu ngoặc. Vì thế, chuyển đổi định dạng không nhất thiết làm dữ liệu “tốt hơn”; nó giúp dữ liệu phù hợp hơn với hệ sinh thái đích.

Chuyển đổi hai chiều không đồng nghĩa khôi phục nguyên văn

JSON → TOML → JSON có thể giữ cấu trúc dữ liệu tương đương đối với các kiểu tương thích, nhưng không bảo đảm giữ khoảng trắng hay cách trình bày ban đầu. Chú thích trong TOML hoặc YAML cũng không được bảo toàn qua quy trình phân tích thành đối tượng rồi xuất lại.

Các kiểu đặc thù như ngày giờ TOML, hoặc số nguyên rất lớn, cần được kiểm tra cẩn thận. Đặc biệt, JSON được đọc bằng JavaScript nên số nguyên ngoài khoảng an toàn từ −(2⁵³ − 1) đến 2⁵³ − 1 có nguy cơ mất độ chính xác.

Xử lý tại trình duyệt khác với hoạt động hoàn toàn ngoại tuyến

Nội dung cấu hình được xử lý cục bộ trong mã chuyển đổi, nhưng thư viện được tải từ CDN: js-yaml từ cdnjs và smol-toml từ jsDelivr. Vì vậy, lần tải trang cần truy cập được các tài nguyên này, trừ khi chúng đã có trong bộ nhớ đệm phù hợp.

Không có yêu cầu mạng gửi dữ liệu cấu hình trong đoạn mã được cung cấp, nhưng điều đó không đủ để cam kết toàn bộ website tuyệt đối không thể làm lộ dữ liệu. Với API key hoặc secrets thật, cần cân nhắc mức độ tin cậy của trang, mã bên thứ ba và tiện ích trình duyệt.

Những câu hỏi thường gặp

Công cụ có chuyển được mọi JSON hợp lệ sang TOML không?

Không. Công cụ yêu cầu cấp gốc là đối tượng, không chấp nhận mảng hoặc giá trị đơn ở cấp gốc. Ngoài ra, dữ liệu phải tương thích với TOML; null là ví dụ điển hình về kiểu không có biểu diễn trực tiếp.

Có hỗ trợ đối tượng lồng nhau và mảng không?

Có. Đối tượng lồng nhau có thể được xuất thành bảng TOML, mảng giá trị có thể thành mảng TOML và mảng đối tượng có thể thành mảng bảng. Khả năng xuất cụ thể phụ thuộc cấu trúc dữ liệu và thư viện smol-toml.

Tại sao dữ liệu JSON đúng cú pháp vẫn báo lỗi?

Đúng cú pháp chưa đủ để chuyển đổi thành công. Đầu vào có thể không đáp ứng điều kiện đối tượng cấp gốc hoặc chứa giá trị không phù hợp với định dạng đích. Thông báo chi tiết trong khung lỗi sẽ giúp phân biệt các trường hợp này.

Dữ liệu có được gửi lên máy chủ không?

Trong mã chuyển đổi được cung cấp, nội dung được xử lý bằng JavaScript trong trình duyệt và không được gửi đến máy chủ để chuyển đổi. Tuy nhiên, trang vẫn tải thư viện bên ngoài; nhận định này không phải bảo đảm an toàn tuyệt đối cho mọi mã khác trên website.

Công cụ có dùng được khi không có Internet không?

Không nên mặc định như vậy. Việc xử lý dữ liệu là cục bộ, nhưng thư viện phụ thuộc CDN. Khả năng hoạt động khi mất mạng còn phụ thuộc việc trang và các thư viện đã được tải, lưu đệm thành công hay chưa.

Vì sao nút sao chép không hoạt động trên một số trình duyệt?

Tính năng dùng navigator.clipboard.writeText, vốn phụ thuộc hỗ trợ trình duyệt, quyền truy cập và thường yêu cầu ngữ cảnh an toàn như HTTPS. Công cụ cũng không thực hiện sao chép khi kết quả rỗng hoặc đang hiển thị lỗi.

Công cụ có giữ chú thích và định dạng gốc không?

Không bảo đảm. Quy trình chuyển đổi giữ dữ liệu thông qua đối tượng trung gian, không giữ nguyên văn bản nguồn. Chú thích, kiểu xuống dòng và cách trình bày ban đầu có thể mất hoặc thay đổi.

Kết quả hợp lệ có thể dùng ngay cho ứng dụng không?

Kết quả hợp lệ cho biết quá trình chuyển đổi đã thành công. Trước khi triển khai, vẫn cần kiểm tra tên khóa, kiểu dữ liệu, giá trị bắt buộc và quy tắc cấu hình riêng của ứng dụng đích.