記錄使用 JSON-LD 檢查器取結構化資料的步驟，意味著要為每一次執行寫下確切的輸入、剖析器輸出以及觀察到的警告，讓工作流程可以重複執行、可稽核，並且易於交接。一份有用的紀錄不僅是一張螢幕截圖：它會標示你貼上的來源、列出工具所找到的每一個 JSON-LD 區塊與 Microdata 項目、區分剖析錯誤與設定檔警告，並註記任何遺漏或空白的屬性。由於結構化資料建立在可能會變動的內容之上，紀錄中也應註明取樣的是哪個範本或頁面版本。結構化資料檢查與擷取工具完全在你的瀏覽器中，針對你所貼上的 HTML 運作，因此文件所記載的事實描述的是被貼上的來源，而非將其上傳。以這種方式記錄步驟，能將臨時的測試轉化為一份可在每次發布前重跑、在 pull request 中分享，或在稽核時引用的檢核清單，而不會讓分頁一關閉後，推理依據就隨之消失的一次性檢查。
「記錄擷取步驟」真正的含義
文件化不只是把 URL 貼進工具後存一張螢幕截圖。當你為 JSON-LD 檢查器記錄擷取步驟時，你正在撰寫一份程序，讓其他人——或未來的你——能依此套用於新頁面，並得到相同的觀察結果。必須捕捉三個要素。
第一個是輸入。檢查器不會去擷取頁面；它只剖析你提供的 HTML。因此紀錄必須辨識該輸入是靜態 HTML 原始檔匯出、受控的渲染後 DOM 匯出，還是從某個 script 標籤抽出的片段。如果範本在載入後注入標記，文件應說明你使用了哪種匯出及其原因，因為同一個頁面在原始回應與渲染後 DOM 中，可能呈現不同的結構化資料。
第二個是清單。JSON-LD 可以是單一物件、陣列，或是包含多個節點的 @graph，檢查器會將這些容器展開為個別項目，同時保留宣告的 @type 值。Microdata 則存在於一般 HTML 中的 itemscope、itemtype 與 itemprop 屬性。一份良好的紀錄會列出每個找到的項目、其宣告的類型，以及觀察到的屬性，而不是將整份文件摺疊成單一形狀。巢狀項目在擷取輸出中仍保持可見的巢狀結構，因此你的文件可以記錄相同的階層，而不是默默地把值攤平。
第三個是結果分類。剖析錯誤、設定檔警告以及資訊性觀察應分開記錄，因為它們回答的是不同層面的問題：格式錯誤的腳本、缺少的高價值屬性，或是對不支援結構的註記。將這些類別混為一談，會掩蓋部署可能失敗的真正原因，並讓紀錄難以與下一次執行進行比較。
每次執行需要記錄的輸入
在開始撰寫程序之前，先決定文件每次擷取必須捕捉哪些欄位。確切清單取決於團隊的審查流程，但下列的結構化資料合約是一個可靠的最低基準。
記錄來源。註明檔案名稱、HTML 取自的頁面 URL，以及匯出方式（原始回應、渲染後 DOM，或框架渲染後的輸出）。這一點很重要，因為在用戶端產生的 JSON-LD 區塊不會出現在原始回應中，而靜態匯出則可能包含爬蟲永遠接收不到的標記。
記錄執行環境。記錄檢查器版本、瀏器與日期。結構化資料檢查與擷取工具完全在獨立的覽器範本中運作，因此來源不會向遠端 URL 請求、也不會以頁面形式執行，更不會送出裝置外，這道界線值得記錄下來，讓審查者知道這些事實純粹來自本機剖析。
記錄清單。列出每個 JSON-LD 物件、每個 @graph 節點，以及每個 Microdata 項目，並附上其宣告的 @type。巢狀項目應保持可見的巢狀結構，不要被攤平成不相關的字串。使用與工具相同的術語，讓紀錄能與螢幕上的各個段落對應。
記錄剖析狀態。將任何 JSON-LD 剖析錯誤分開記錄，這樣一處損壞的腳本才不會掩蓋同一份文件中其他位置所找到的有效項目。格式錯誤的區塊會單獨回報，文件應保留這種區隔，而不是將其混入一個籠統的「失敗」判定。
記錄設定檔警告。在類型受支援的情況下，檢查器會顯示聚焦的缺漏屬性警告，並附帶證據連結的指引。警告代表本機設定檔找不到某個屬性；並不能證明搜尋引擎會拒絕該頁面。紀錄應將這些標示為缺漏，而非失敗。
記錄觀察結果。註記工具回報的任何資訊性限制，例如 RDFa 超出目前產品範圍，讓審查者不會誤將這次擷取視為通用的語意網稽核。若頁面上存在 RDFa，紀錄應明確加以說明。
如何撰寫擷取步驟
下列程序反映了結構化資料檢查與擷取工具經驗證的運作步驟，撰寫方式使每次執行都能產生一份自足的紀錄條目。請將其複製到你的 Runbook 中，並依團隊審查流程調整欄位名稱。
- 在全新的瀏覽器分頁中開啟結構化資料檢查與擷取工具。確認輸入框為空，且沒有殘留上次執行的貼上內容。
- 匯出你想檢查的 HTML。對於伺服器端渲染的頁面，請使用來自本機伺服器或爬蟲匯出的原始回應。對於用戶端渲染的頁面，請使用受控的渲染後 DOM 匯出，以取所有載入後注入的標記。在執行紀錄中註明匯出方式。
- 將 HTML 貼入輸入區。不要貼上 URL；檢查器不會擷取或執行頁面，因此單獨貼上 URL 將無法產生清單。
- 執行擷取。依序檢視三個段落：JSON-LD 剖析錯誤、Microdata 項目，以及宣告的類型、屬性與聚焦的缺漏屬性警告。請分開檢視各段落，而非捲動尋找單一的通過／失敗摘要。
- 針對每個 JSON-LD 項目，記錄其 @type、可見的屬性，以及任何巢狀結構。確認容器形狀（單一物件、陣列或 @graph）符合你的範本預期應輸出的內容。
- 針對每個 Microdata 項目，記錄其 itemtype、itemprop 值，以及任何巢狀項目。標記出空白的 URL 或空白的內容屬性，因為這些通常代表使用了錯誤的屬性。
- 註記任何存在的 RDFa。檢查器不會擷取或評分 RDFa；記錄其存在可避免審查者將空白的 RDFa 段落誤讀為「缺少結構化資料」。
- 將來源出處、清單、剖析狀態、設定檔警告與觀察結果，連同紀錄條目一起存入票證或 commit 中。接著修正來源範本，並以你所針對搜尋功能的官方工具驗證部署後的 URL。
可重複使用的文件範本
一致的範本可避免兩次執行以不同的格式被記錄，使得 diff 與稽核得以進行。下表展示了組織單次擷取紀錄的一種方式。請依團隊審查流程調整欄位名稱，但在不同次執行間保持欄位結構固定，使各條目得以比較。
| 欄位 | 應捕捉內容 | 為何重要 |
|---|---|---|
| 執行 ID | 唯一識別碼、日期、審查者 | 將備註連結回 commit 或票證 |
| 來源 | 檔案名稱、頁面 URL、匯出方式 | 區分原始回應與渲染後 DOM |
| 輸入大小 | HTML 的大約大小、項目數量 | 維持在輸入上限範圍內 |
| JSON-LD 項目 | 每個 @type、容器形狀、屬性 | 每個項目的基準清單 |
| Microdata 項目 | 每個 itemtype、itemprop 值、巢狀結構 | 每個項目的基準清單 |
| 剖析錯誤 | 損壞的 JSON 區塊、位置提示 | 與其他位置的有效項目區隔 |
| 設定檔警告 | 類型、缺漏屬性、證據連結 | 聚焦的缺漏，而非阻擋性的判定 |
| 觀察結果 | RDFa 存在與否、不支援的結構 | 避免誤讀稽核結果 |
當每次執行都使用相同的範本時，你就能並排比較兩次取，並回答「範本是否開始輸出重複項目」、「某個變體是否缺少必要欄位」，或「重構後某個 JSON-LD 區塊是否剖析失敗」等問題。這些問題無法從一張未經整理的螢幕截圖得到解答，也都不依賴搜尋引擎回傳特定結果。
若你想驗證擷取後的清單在實務上的閱讀方式，取後如何讀 JSON-LD 檢查器結果這份指南以敘述性的方式走過相同的分類。
記錄 JSON-LD 檢查器執行時常見的缺漏
即使有了範本，某些細節仍容易遺漏。在審查他人的文件或稽核自己的紀錄時，請留意以下缺漏。
缺少來源出處。僅列出「兩個 JSON-LD 項目，皆剖析正常」的紀錄條目無法重現。務必記錄所貼上的內容，包括匯出方式。
將剖析錯誤與設定檔警告混為一談。格式錯誤的 JSON 區塊是語法問題；缺漏屬性則是完整性問題。將兩者混在一起，會難以判斷修正應歸於範本的序列化器，還是資料來源。
將警告視為失敗。檢查器僅在產品具備已記錄規則集時，才會顯示聚焦的缺漏屬性警告。不熟悉的 Schema.org 類型仍會被擷取，但不會被賦予捏造的要求。文件應保留這種區別，使審查者不會因為表面的缺漏而擋下發布。
忽略渲染差異。若框架在載入後注入標記，原始回應、渲染後 DOM 與爬蟲可見的輸出可能各自呈現不同的面貌。文件應註明使用的是哪一種匯出，讓未來的執行能鎖定同一個產出物。
捏造需求。為了消音警告而新增欄位，可能會讓實作變得更不可信。少量完整且真實的屬性，優於一個塞滿通用或捏造值的大型物件，紀錄也應反映這一點。
Limits of Local Documentation vs. Real Eligibility
Even a meticulous log only describes the pasted HTML. The Structured Data Checker & Extractor reports facts about the source you provided; it does not simulate how a crawler will receive the page, what policies the search feature applies, or whether indexing will occur. The official guidance in Google's structured-data introduction treats syntax validity and search eligibility as separate questions, and your documentation should reflect that split.
A local log can answer whether the intended type is present, whether a template emitted duplicate items, whether a required field is missing from one variant, whether a JSON-LD block fails to parse, or whether Microdata exposes a blank URL because the wrong attribute was used. It cannot answer whether the markup agrees with visible content, whether a feature-specific policy is satisfied, or whether deployment, indexing, and feature eligibility will hold at search time. After updating the template, validate the public URL with the official validator for the search feature you actually target and inspect the enhancement reports after recrawling.
For a deeper look, see Schema Markup Generator for Beginners: Your First JSON-LD.