開發者工具·語法轉換器

YAML 在 JSON 轉換中遺失的功能：註解、錨點和標籤

2026年8月4日 · 工作原理

yaml json 資料格式

YAML 具有註解、錨點、別名、合併鍵、標籤和多重檔案流； JSON 沒有這些。這篇文章解釋了轉換器對每個檔案的作用以及為什麼轉換回來永遠不會恢復原始檔案。

檔案返回的時間更長，並沒有任何註釋 - YAML 配置轉換為 JSON 並返回，以及所有未保存的內容

即使在每個註解消失後，YAML 檔案也可以從 JSON 回傳更長時間。共享一個映射的錨點被解析為重複的物件資料，因此序列化器獨立寫入每個副本。這些價值觀可能仍然一致，但創作結構和解釋已經消失。

這就是為什麼 YAML-to-JSON-to-YAML 往返應被判斷為資料轉換，而不是來源保存。 ToolAcre 讀取受限值圖並寫入新檔案。它從不保留包含註解、錨點名稱、參考選擇或區塊標量表示的特定語法樹。

註解被 YAML 解析器丟棄，因為 JSON 沒有註解節點。以 `#` 開頭的行可以解釋為什麼存在逾時或誰擁有服務；一旦刪除，任何演演算法都無法推斷措辭或位置。轉換回來會建立有效的 YAML ，而無需該操作上下文。

在版本控制中保留原始檔案並在替換之前檢查差異。如果目標只是檢查解析值，則 JSON 很有用。如果目標是在保留註解的同時重新格式化，則此通用值轉換器是錯誤的表示。

錨點和別名在安全限制內被接受，然後被解析。 `base: &b {x: 1}` 和 `copy: *b` 成為包含 `x: 1` 的兩個物件路徑。輸出 YAML 使用 `noRefs`，因此共享物件標識不會建立新的錨點。即使重複值仍然存在，緊湊關係也消失了。

遞歸別名被拒絕，因為 JSON 無法表達循環。別名擴展受到別名計數、嵌套和擴展節點測量的限制；一個將字串化為超過一百萬個值的簡短檔案被停止。這可以保護分頁而不要求任意 YAML 支援。

该大纲假設 YAML 1.1 合並鍵已展平。 ToolAcre 僅載入 js-yaml 的 JSON 或 Core 架構，這兩種架構皆不啟用合併類型。在這些模式下， `<<` 鍵是普通資料，而不是合併映射的指令。因此，將扁平合併呈現為交付行為是錯誤的。

如果您的來源依賴合併鍵語義，請在擁有該約定的應用程式中解析它，或在轉換之前明確重寫值。用作普通 `<<` 值的別名仍可能解析為對象，但鍵仍然是 `<<`；這並不等同於將其成員合併到父級中。

受限模式辨識的標準明確標記可以選擇基本類型，例如 `!!str` 或 `!!int`。自訂和更豐富的標籤（包括二進位、時間戳記、集合、有序映射、JavaScript 函數和 Python 物件建構函數）將被拒絕。它們不會被字串化，也不會被執行。

接受由 `---` 分隔的 YAML 流。一份檔案成為一種價值；其中幾個成為一個數組，並帶有命名檔案計數的警告。尾隨分隔符號可以根據所選模式建立一個空的最終檔案。這裡的目標沒有流模型，因此數組是宣告的約定。

使用重試和逾時的 `defaults: &d`、解釋逾時的註釋，然後使用 `service:` 和 `inherited: *d`。 JSON 包含預設值和重複的繼承物件；評論和錨點名稱不存在。將 JSON 轉換回來會發出兩個對應而不是錨關係。

新增 `---` 後面跟著另一個文件，JSON 根成為文件數組。新增 `!!binary` 並使用受限架構提示停止轉換。這三個變化區分了已解析的支援資料、結構約定和完全無支援的構造。

普通物件插入順序通常保持可見，但它不是來源樣式的保存，並選擇排序鍵會故意更改它。引號、流式與區塊式、標量拼字和註解都不再存在。重複的映射鍵會保留最後一個值並發出警告，而不是保留兩個無效條目。

作者透過引用 YAML 1.1 消費者可能誤讀的值來保護不明確的字串，但這種安全選擇可能與作者的原始風格不同。資料相等性是對普通 JSON 形值的合理測試；文字平等則不然。

每當意義位於 JSON 形值之外時，YAML 到 JSON 就會有損：註解、別名、不支援的標籤、流邊界本身和樣式。 ToolAcre 讓一些損失變得可見，並拒絕危險或循環結構，而不是假裝保留它們。

在採用工作流程之前轉換代表性檔案。檢查警告、區分解析值並保留編寫的 YAML。此面板是解析器所看到內容的絕佳鏡頭，但它不是保留註解的編輯器或完整的 YAML 物件模型轉換器。

對於遷移審核，請將值變更與僅來源變更分開。 JSON 深度比較可以決定普通值是否倖存，而文字差異則顯示必須變更的註解、錨點和樣式。兩張支票都不能取代另一張。將值比較稱為無損會忽略來源資訊；將每個文字變更稱為資料故障將忽略有效的重新序列化。