JSON-LD 檢查器的執行過程分為三個有序階段:貼上 HTML、檢閱每個找到的項目,以及在以官方工具驗證已部署的 URL 之前先修正來源範本。由於檢查器不會擷取或執行頁面,它所顯示的每項事實都來自您貼上的 HTML,因此規劃步驟實際上就是選擇正確的來源副本、瞭解 JSON-LD 可採用的容器形狀,並把是否符合豐富結果 (rich result) 的判斷保留給官方驗證工具。格式錯誤的 JSON-LD 區塊會被單獨回報,因此同一份文件中一個損壞的指令碼不會抹除其他位置找到的有效項目。JSON-LD 可以包含單一物件、頂層陣列,或含有數個節點的 @graph,而完善的規劃會在任何結果被解讀之前,先逐一考量每種形狀。因此輸出是關於貼上內容的證據,而不是對搜尋引擎將如何處理已部署頁面的承諾。規劃執行過程就是讓這項區別在您工作時保持清晰可見。

how do i plan the steps needed to extract structured data checker when using json ld checker
先規劃 JSON-LD 檢查器的執行步驟,再貼上 HTML

為什麼在貼上任何內容之前先規劃很重要

結構化資料檢查器與擷取器是僅供貼上內容的本地解析器,因此輸入品質決定了所有下游結論。這個工具不會請求遠端 URL、不會執行指令碼,也不會載入圖片或表單。它會在分離的瀏覽器範本片段中走訪解析後的文件,並回報檢查器在該貼上副本中找到的項目看起來是什麼樣子。這個界線保護了私有網路請求與跨來源失敗,但也意味著這個工具只能描述您餵給它的 HTML。如果框架在頁面載入後注入標記,您貼上的內容可能與爬蟲接收到的內容不一致。請保留一個規劃步驟來選擇正確的來源副本。另請參閱無需上傳檔案即可運作的 JSON-LD 檢查器,以瞭解驅動此設計的更廣泛界線。

規劃也能區分擷取與驗證。Schema.org 定義了廣泛的詞彙,而搜尋產品則會為特定體驗發布各自的必要與建議屬性。檢查器僅在產品具備已記錄的規則集時,才會套用明確且可檢驗的設定檔。未知類型仍會被擷取,但不會被指派捏造的需求。警告代表本地設定檔未找到該屬性;並不代表搜尋引擎會拒絕該頁面。經過規劃的執行會將擷取視為事實查證步驟,並把資格判定保留給官方驗證工具。

開啟檢查器之前要準備的輸入

在貼上之前,請先備齊讓您能解讀輸出所需的最小輸入集合。這個規劃刻意保持精簡:

  • 一份權威的 HTML 副本。頁面為伺服器端渲染時請使用原始伺服器回應;當框架在載入後注入標記時,請使用受控的已渲染 DOM 匯出;切勿使用瀏覽器內的檢視原始碼。
  • 一份您預期會找到的類型清單。每個宣告的 @type 都會觸發其專屬的聚焦警告設定檔,因此預先掌握清單內容可以縮小檢閱範圍。
  • 每個 JSON-LD 區塊的容器形狀。請預先決定您預期的是單一物件、頂層陣列,還是含有數個節點的 @graph。
  • 每個設定檔的官方說明文件連結。設定檔的警告會連結到證據而非個人意見。
  • 驗收標準。為貼上步驟定義「通過」的定義:解析正確、預期類型齊備、聚焦屬性集合符合、Microdata 項目未被攤平。

備妥這些輸入後,貼上步驟就能化為單一動作,而非摸索過程。

有序的擷取規劃

結構化資料檢查器與擷取器是為一個小而嚴謹的工作流程所設計。請依下列順序使用。

  1. 複製能代表爬蟲所見內容的 HTML。如果框架在載入後注入標記,請在得出結論前比較原始回應、已渲染 DOM 與爬蟲可見的輸出。
  2. 將該 HTML 貼入輸入欄位。檢查器會在分離的範本片段中解析來源,因此貼上文件中的指令碼不會執行。
  3. 執行擷取並依序檢查三份清單:JSON-LD 解析錯誤、Microdata 項目,以及含有屬性的已宣告類型。
  4. 優先解決解析錯誤。格式錯誤的 JSON-LD 區塊會被單獨回報,因此同一份文件中一個損壞的指令碼不會抹除其他位置找到的有效項目。
  5. 依其已記錄的設定檔逐一檢視每個已宣告類型。檢查器會將 JSON-LD 容器展開為個別項目,同時保留 @type 值與可見屬性。
  6. 將聚焦的缺失屬性警告彙整為一份範本修正清單。輸出是關於貼上內容的證據;請將警告視為訊號,而非資格判定。
  7. 編輯來源範本、針對修正後的 HTML 重新執行擷取,然後才以官方工具驗證您鎖定的搜尋功能所對應的已部署 URL。

如何解讀每項擷取輸出

檢查器將輸出分為三層,因此您無需自行混合解讀。下表說明了每層所承載的訊號類型,以及它所暗示的後續行動。

層級檢查器回報的內容它無法證明的事後續行動
JSON-LD 解析狀態每個指令碼區塊的解析錯誤、容器形狀(物件、陣列、@graph)、每個展開項目的已宣告 @type該頁面符合任何搜尋功能的資格在繼續閱讀之前先解決解析錯誤;一個損壞的指令碼不會抹除其他位置的有效項目
Microdata 項目具有 itemscope 與 itemtype 的頂層項目、有界的屬性檢視、巢狀項目以可見的巢狀方式保留該 Microdata 符合可見內容或政策驗證所暴露的值來自內容屬性、連結、媒體來源或系統讀取的文字內容
聚焦的屬性警告明確支援設定檔中缺失的屬性;警告是設定檔專屬的,而非資格專屬的搜尋引擎會拒絕該頁面將警告視為範本修正清單,並在編輯前參考所連結的規則集

逐層閱讀輸出有助於讓執行範圍保持精簡。每一層回答一個具體問題,而任何缺漏的層級都指向不同類型的來源範本修正。Microdata 檢視遵循 WHATWG HTML Microdata 規格 中的規則,包括 itemscope、itemtype 與 itemprop 如何與一般 HTML 對應。

先處理解析錯誤,再處理設定檔警告

解析錯誤會妨礙解讀,因為它們會讓格式錯誤的指令碼無法成為證據。檢查器會將它們單獨回報,但它們仍應列於修正清單的最上方。單一未跳脫字元就可能隱藏同一指令碼中所有有效屬性,而局部物件可能誤導對不相關項目的檢閱。請先修正解析錯誤、重新執行擷取,再檢閱屬性檢視。

設定檔警告之所以排在第二位,是因為它們預設結構化承載已經就緒。警告代表本地設定檔未為某條明確且可檢驗的規則找到屬性;並不表示該頁面會被拒絕。某個搜尋功能所需的屬性,對另一個搜尋功能而言可能是選用;而不屬於 Google 功能的 Schema.org 屬性,對其他消費者仍可能有意義。因此檢查器會區分解析錯誤、聚焦屬性缺失與資訊性觀察,並以各自的證據呈現。少而完整且真實的屬性,優於塞滿籠統或捏造值的大型物件——這本身也是一項規劃提醒:不要為了消除警告而新增欄位。

以已部署 URL 來完成迴圈

檢查器只回報關於貼上標記的事實。是否符合資格還取決於可見內容、功能專屬政策、部署狀態、索引狀態,以及搜尋引擎本身的決策。在進行修改之後,請以您實際鎖定的搜尋功能對應的官方驗證工具驗證公開 URL。Google 的結構化資料簡介將 JSON-LD 列為許多功能的通用建議格式,但在支援的情況下也記錄了 Microdata 與 RDFa;本工具僅擷取 JSON-LD 與 Microdata,因此僅含 RDFa 的頁面會顯示空白,這與是否缺少結構化資料無關。

搜尋引擎會決定是否以及何時顯示強化的呈現方式。沒有任何本地檢查器能保證索引、排名或豐富結果。請將這次執行視為透明的預檢程序:貼上經授權的 HTML、檢閱每個擷取項目、優先解決解析錯誤、依所連結的說明文件檢閱設定檔警告,然後才驗證已部署的回應。當來源範本已修正、已部署 URL 已以功能專屬的官方工具驗證,且修正後的範本已針對具代表性的記錄重新測試時,規劃才算結束。

延伸閱讀:Android 上的條碼產生器:在瀏覽器中執行。