Google zmienia sposób parsowania JSON-LD

Google Search Central opublikowało informację:

To bring our parser up to JSON and other standards, we changed our JSON-LD extraction and are now only applying a single pass of HTML unescaping. Practically speaking, this means that double-escaped entities (like & or ✔) will no longer be unrolled.

If you’re using JSON-LD for structured data, be sure to update your code to standard JSON escapes or Unicode hexadecimal escapes (like \u0026).

Czyli w skrócie:

1. Wcześniej parser Google wykonywał więcej niż jedno przejście dekodowania HTML na treści wyciąganej z bloków JSON-LD
2. Od teraz wykonuje dokładnie jedno przejście
3. Google rekomenduje, żeby nie polegać na tym mechanizmie w ogóle i stosować standardowe escape’y JSON lub Unicode (\u0026).

To zmiana w tym jak Google interpretuje treść, którą dostaje jako dane strukturalne.

Jak to teraz działa

Google podaje dwa przykłady problematycznych zapisów.

Przykład 1: &

• Zapis w kodzie źródłowym: &
• Jedno przejście dekodowania HTML zamienia & na &, więc & staje się &
• Wynik koncowy to & – czyli NIE znak docelowy &

Przykład 2: ✔

• Zapis w kodzie źródłowym: ✔
• Po jednym przejściu: ✔
• Wynik końcowy to ✔ – czyli NIE docelowy znak checkmark (✔)

W obu przypadkach wynikiem końcowym jest tekst, który dalej zawiera fragment encji HTML zamiast właściwego znaku. Wcześniej Google dekodował to wielokrotnie, aż dochodził do prawidłowego wyniku. Teraz zatrzymuje się po pierwszym kroku.

Dlaczego to w ogóle jest problem i skąd się bierze

Podwójne escapowanie najczęściej powstaje wtedy, gdy ten sam mechanizm szablonu lub CMS’a, który automatycznie zamienia znaki specjalne na encje HTML w artykule (np. & -> &) jest używany do wygenerowania treści wewnątrz bloku application/ld+json.

Typowy scenariusz:

1. Redaktor wpisuje w CMS’ie: Research & Development
2. CMS zapisuje to w bazie danych już jako Research & Development, bo tak escapuje pola tekstowe
3. Wygenerowany blok JSON-LD dodatkowo escapuje tę wartość przy wstawianiu do HTML, tworząc Research & Development
4. Do niedawna Google to „naprawiał” po swojej stronie. Teraz nie naprawia.

Strona mogła więc w wyszukiwarce mogła wyglądać prawidłowo przez lata, mimo błędu w kodzie. Błąd był maskowany przez zachowanie parsera Google.

Podstawa standardu RFC 8259

Zmiana Google, to po prostu dostosowanie do specyfikacji JSON. Dokładnie RFC 8259, sekcja 7²

„All Unicode characters may be placed within the quotation marks, except for the characters that MUST be escaped: quotation mark, reverse solidus, and the control characters (U+0000 through U+001F).

Any character may be escaped (…) as a six-character sequence: a reverse solidus, followed by the lowercase letter u, followed by four hexadecimal digits (…) Alternatively, there are two-character sequence escape representations of some popular characters.”

Dwa fakty z tego zapisu maja bezpośrednie znaczenie dla SEO:

• Znak & nie wymaga escapowania w JSON. Może wystąpić w stringu bez żadnego dodatkowego zapisu
• Jedyne dopuszczalne mechanizmy escapowania w JSON to sekwencja \uXXXX (cztery cyfry szesnastkowe) oraz krótkie dwuznakowe sekwencje typu \\ czy \". Encje HTML (&, ✔ itd.) nie są częścią specyfikacji JSON

Pojedyncze przejście dekodowania HTML, które Google nadal wykonuje nie jest zachowaniem zdefiniowane przez RFC 8259. Parser JSON zgodny z RFC 8259 interpretowałby & ciąg znaków typu: &, a, m, p, ;. Także zmiana Google to redukcja liczby przejść z „kilku” do „jednego” – krok w stronę zgodności, a nie pełna zgodność ze standardem.

Checklista do sprawdzenia

1. Audyt JSON-LD na typach stron (produkty, artykuły, strona główna z danymi organizacji, strony lokalizacji) pod kątem podwójnie zakodowanych encji HTML
2. Kod – sprawdź czy funkcja generująca blok JSON-LD używa dedykowanej serializacji JSON (np. json_encode w PHP, JSON.stringify w JS) albo czy przechodzi dodatkowo przez funkcję escapującą HTML
3. Naprawa u źródła – docelowy zapis w kodzie powinien zawierać znak escape Unicode (\u0026), anigdy encję HTML
4. Przetestuj strony Rich Results Test lub walidator schema.org po wdrożeniu poprawki, korzystając z faktycznie wyrenderowanego kodu strony. Możesz tez użyć mojego skanera żeby zautomatyzować cały proces.

8 testów, 4 strony, 2 narzędzia

Zrobiłem 4 strony i przeprowadziłem 8 testów używając:

1. Test wyników rozszerzonych (Rich Results Test)
2. Walidator Schema

Test 1: brak escapowania

A & B → A & B

Znak & w JSON nie wymaga escapowania (RFC 8259), wiec zostaje odczytany dokładnie tak, jak został zapisany. To jest punkt odniesienia dla reszty testu.

Test 2: pojedyncze escapowanie

A & B → A & B

To potwierdza ogłoszenie Google: 1 przejście dekodowania HTML nadal działa.

Test 3: podwójne escapowanie

A & B → A & B

To jest dokładne potwierdzenie ogłoszenia Google. Podwójnie zakodowana wartość nie została w pełni rozwinięta – po jednym przejściu zostało & zamiast &. To jest dokładnie ten wynik, który teraz będzie trafiał do danych strukturalnych Google i (potencjalnie) do SERP.

Test 4: macierz rożnych typów escapowania

W tym teście zrobiłem mix, bo sprawdzam encje nazwane, dziesiętne i szesnastkowe

Wniosek: mechanizm „jednego przejścia” działa niezależnie od typu encji HTML, bez znaczenia czy jest:

• nazwana – &, <, >, "
• dziesiętna A
• szesnastkowa – A

Problem dotyczy całej rodziny encji HTML Google dostosował swój parser do tego jak standard RFC 8259 definiuje JSON. Czyli do tego jak powinno to wyglądać od zawsze.

FAQ

1. Google informuje o zmianie parsowania JSON-LD –
   https://www.linkedin.com/posts/to-bring-our-parser-up-to-json-and-other-share-7496492350370713600-jxi2/ ↩︎
2. RFC 8259, sekcja 7 – https://datatracker.ietf.org/doc/html/rfc8259#section-7 ↩︎