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.