SOQVER Przygotuj źródło
Polski

Blog · Poradnik ·

Jak udostępniać so4ag.json i JSON-LD w Next.js, Astro i Nuxt

Gdzie umieścić plik so4ag.json w Next.js, Astro i Nuxt, jak sprawdzić jego poprawność w CI i jak osadzić te same dane w formacie JSON-LD.

Przechowuj fakty dotyczące klienta razem z treścią witryny

SO4AG (Source Objects for AGents) to otwarty format zapisu faktów biznesowych. Wersja 0.1 jest wersją roboczą. Źródło można przechowywać w repozytorium jako zwykły plik JSON i udostępniać pod adresem /so4ag.json. Te same fakty mogą być dostępne w formacie JSON-LD na publicznej stronie „Fakty i warunki”.

Przechowywanie pliku razem z treścią witryny pozwala sprawdzić zmianę ceny lub zasad wraz ze stroną, na której są podane. Osoby sprawdzające widzą, co się zmieniło, kogo dotyczy dany fakt, gdzie klient go podaje i kiedy traci ważność. Można również ustawić walidację jako obowiązkowy etap kompilacji, aby błędnie zapisane fakty zatrzymywały kompilację przed publikacją. Program odczytujący opublikowane fakty może sprawdzić ich warunki i daty, co zmniejsza ryzyko błędu.

Zacznij od jednego stwierdzenia

Przykład firmy Example Plumbing podaje stawkę 95.00 USD za godzinę wizyty serwisowej. Pole scope określa, czego dotyczy cena. Każde stwierdzenie wymaga pól valid_from i valid_until. Stwierdzenie oznaczone jako known wymaga też co najmniej jednego dowodu z polem url i znacznikiem czasu observed_at. W tym przykładzie dowód wskazuje stronę z cennikiem i odnotowuje, kiedy widniała na niej ta cena.

{
  "id": "https://plumbing.example/so4ag.json#price-hour",
  "subject": "https://plumbing.example/#org",
  "property": "https://soqver.com/spec/so4ag/0.1/general#price",
  "knowledge_state": "known",
  "value": {
    "type": "money",
    "amount": "95.00",
    "currency": "USD"
  },
  "scope": {
    "item": "service call",
    "per": "hour"
  },
  "assertion_basis": "publisher_asserted",
  "evidence": [
    {
      "url": "https://plumbing.example/prices",
      "observed_at": "2026-11-20T15:00:00Z",
      "kind": "webpage"
    }
  ],
  "valid_from": "2026-11-20T00:00:00Z",
  "valid_until": "2027-01-15T00:00:00Z"
}

Ten blok zawiera jedno stwierdzenie. Specyfikacja pokazuje, jak stwierdzenia są umieszczane w pełnym pliku źródłowym. Specyfikacja SO4AG 0.1

Udostępnij źródło pod adresem /so4ag.json

Ścieżka public/so4ag.json działa we wszystkich trzech frameworkach. Jeśli używasz trasy lub punktu końcowego, sprawdź plik źródłowy, z którego pochodzą dane zwracane w odpowiedzi. Dla tego adresu URL użyj jednej metody udostępniania.

Next.js

Umieść plik w lokalizacji public/so4ag.json, aby udostępnić go z katalogu głównego witryny. Aby udostępnić go przez App Router, użyj app/so4ag.json/route.ts i zwróć dane źródłowe z funkcji obsługującej trasę za pomocą Response.json(...).

Astro

Umieść plik w lokalizacji public/so4ag.json lub utwórz statyczny punkt końcowy w lokalizacji src/pages/so4ag.json.ts, aby wygenerować /so4ag.json. Jeśli korzystasz z punktu końcowego, przechowuj odczytywany przez niego plik JSON w repozytorium, aby można go było przejrzeć i poddać walidacji przed kompilacją.

Nuxt

Umieść plik w lokalizacji public/so4ag.json. Nuxt udostępnia pliki z public/ z katalogu głównego witryny, więc adres URL to /so4ag.json.

Dodaj ten link w sekcji head stron, które czytają użytkownicy, aby każda z nich wskazywała plik źródłowy.

<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">

Sprawdź poprawność pliku i wygeneruj JSON-LD

Uruchom walidator przed kompilacją witryny lub jako obowiązkowy krok CI. Te polecenia zakładają strukturę public/. Jeśli punkt końcowy odczytuje plik JSON z innej lokalizacji, przekaż jej ścieżkę do walidatora.

npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json

Polecenie wypisuje VALID lub INVALID. Jeśli plik jest nieprawidłowy, polecenie wyświetla listę błędów i miejsca ich wystąpienia. Skonfiguruj kompilację lub zadanie CI tak, aby zatrzymywały się w razie niepowodzenia walidacji. Na podstawie wskazanych lokalizacji popraw plik źródłowy przed wygenerowaniem strony.

Uruchom poniższy konwerter ze sklonowanego repozytorium SO4AG, umieszczając so4ag.json w bieżącym katalogu. Możesz również przekazać ścieżkę do zweryfikowanego pliku w repozytorium witryny. Kod źródłowy SO4AG

node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld

Umieść zawartość facts.jsonld wewnątrz znacznika <script type="application/ld+json"> na stronie „Fakty i warunki”. Generuj zawartość skryptu z tego samego pliku, który udostępniasz pod adresem /so4ag.json, aby po każdej aktualizacji oba warianty zawierały te same fakty. Konwersja zachowuje fakty wraz z ich warunkami i datami.

Poproś klienta o potwierdzenie faktów

Za utrzymanie pliku i kontroli podczas kompilacji odpowiada wykonawca. Klient potwierdza fakty i bierze za nie odpowiedzialność. Przed opublikowaniem faktu pod adresem valid_until poproś klienta o potwierdzenie jego wartości, zakresu i strony, na której jest podany. Na przykład cenę można potwierdzić na maksymalnie 60 dni naraz.

Gdy klient potwierdzi stwierdzenie, zaktualizuj je wraz z datami, przeprowadź walidację i ponownie wygeneruj JSON-LD. Po upływie ostatniego dnia ważności program traktuje fakt jako informację historyczną. Jeśli klient nie podaje danego faktu, opublikuj stwierdzenie bez wartości, ustawiając knowledge_state na unknown. Na stronach pojawi się oznaczenie „nie podano”.

Następny krok

Dodaj public/so4ag.json do repozytorium klienta zgodnie z przewodnikiem dla programistów. Sprawdź plik w publicznym walidatorze przed dodaniem kontroli do CI.

Więcej artykułów

Poradnik ·

Jak opublikować dane firmy w witrynie opartej na WordPress

Proszę zainstalować wtyczkę SO4AG Facts w WordPress, dodać dane firmy wraz z warunkami i datami oraz opublikować stronę „Dane i warunki”, którą można sprawdzić w panelu administracyjnym.

Poradnik ·

Jak opublikować dane o wysyłce, płatnościach i zwrotach w WooCommerce

W SO4AG Facts można sprawdzić sugestie dotyczące wysyłki i płatności z WooCommerce, a następnie ręcznie dodać terminy zwrotów, czas dostawy i pozostałe warunki.

Poradnik ·

Shopify: jak opublikować dane i warunki bez aplikacji

Jak opublikować stronę „Dane i warunki” w Shopify, dodać JSON-LD i umieścić odnośnik do hostowanego pliku SO4AG, gdy pliku nie można umieścić w katalogu głównym domeny sklepu.

Bezpłatny audyt witryny Wszystkie artykuły