跳到主要內容
Yunknow Toolbox

← 返回部落格

JSON 與 YAML 差在哪?怎麼互轉

JSON 與 YAML 是寫同一件事的兩種方式:由物件、清單、字串、數字與布林值組成的結構化資料。JSON 用大括號與逗號包起來;YAML 用縮排與換行。因為兩者描述的結構完全相同,可以無損互轉——但有幾個坑值得先知道。

一樣的資料,兩種風格

JSON:

{ "name": "Yunknow", "tags": ["free", "fast"], "active": true }

YAML:

name: Yunknow
tags:
  - free
  - fast
active: true

同樣的資料,只是換了件衣服。YAML 省掉標點、靠縮排,這正是設定檔愛用它的原因。

什麼時候用哪個

  • JSON——API、package.json、任何由程式自動讀寫的東西。嚴謹、無歧義、通用支援。
  • YAML——你手動編輯的設定:Docker Compose、Kubernetes、GitHub Actions、CI 流程。好讀,還支援註解。

常見流程是:用 YAML 撰寫設定,再讓工具當成 JSON 讀取。

常見的坑

  • YAML 的縮排有意義。 混用 Tab 與空白、或縮排層級搞錯,會改變意思或直接解析失敗。請一律用空白縮排。
  • 註解在轉成 JSON 時會消失。 JSON 沒有註解語法,所以 YAML → JSON 時 # 說明 那幾行會不見。這是正常,不是 bug。
  • 「挪威問題」。 舊版 YAML 中,未加引號的 no、yes、on、off 會被當成布林值——所以國碼 NO 可能變成 false。看起來像布林的字串要加引號。
  • 錨點會被展開。 YAML 的 &anchor/*ref 重用,在轉成 JSON 時會被攤平成一般資料。

特性對照

特性JSONYAML
註解無有(#)
尾逗號不允許不適用
人類可讀性好深層巢狀更好讀
解析速度較快較慢
多行字串只能跳脫 \n區塊純量
一檔多份文件不支援支援(--- 分隔)

YAML 有個常被忽略的好用功能:區塊純量,適合長文字——字面區塊保留換行,折疊區塊則把多行併成一行:

description: |
  第一行維持一行。
  第二行維持一行。
summary: >
  這段會跨越
  好幾行原始碼
  但最後變成一行。

小問答

YAML 是 JSON 的超集嗎? 實務上算是。從 YAML 1.2 起,任何合法的 JSON 都同時是合法的 YAML,所以 YAML 解析器能直接讀 JSON;反過來不行——JSON 讀不懂 YAML 的縮排語法。

API 該回傳哪個? 幾乎都選 JSON——解析快、無歧義、到處都支援。YAML 留給人類手動編輯的檔案。

轉換後我的註解跑去哪了? 被丟掉了,因為 JSON 沒有註解語法。若需要保留說明,可以改加一個真的鍵,例如 "_comment"。想更深入認識這個格式,看 JSON 是什麼。

在瀏覽器本機安全互轉

JSON ⇄ YAML 轉換工具能把兩者互轉,並邊轉邊檢查語法——有錯會指出確切位置。全程在你的瀏覽器本機執行,再私密的設定也不會離開你的裝置。

相關工具

#dev#json#yaml