ARK. 1System · Standardy
JSON-RPC i OpenAPI — jeden mówi, jak zawołać, drugi opisuje, co można zawołać.
Te dwa standardy często stoją obok siebie, ale robią co innego. JSON-RPC 2.0 to format wiadomości: „wywołaj metodę z tymi parametrami” i „oto wynik albo błąd z kodem” — przez dowolny transport. OpenAPI to dokument opisujący API HTTP: jakie są ścieżki, co przyjmują, co zwracają. Agent AI styka się z oboma: narzędzia Claude Code działają przez MCP, który jest JSON-RPC, a z dokumentu OpenAPI da się wygenerować klienta i opis narzędzi. Poniżej oba standardy i interfejsy LAB247 — czym są opisane dziś i co da się dołożyć.
Źródło: JSON-RPC 2.0 (26.03.2010), OpenAPI 3.2.1 (10.09.2026), MCP 2026-07-28; odczyt 26.09.2026. Opisy są naszym opracowaniem. Liczby tras i próba JSON Schema — z kodu LAB247 i skanera. Pozostałe standardy serii: ECS (nazwy pól zdarzeń), Bazy podatności (rekord CVE JSON 5).
- JSON-RPC
- 2.0od 26.03.2010 · 6 kodów zarezerwowanych
- OpenAPI
- 3.2.110.09.2026 · 3.2.0 z 19.09.2025
- Ingest · API skanera
- 11 · 37rodzaje ingestu · trasy GET skanera
- Schematy zod → JSON Schema
- 10 / 10próba 26.09.2026
RYS. 1Kto z kim rozmawia i czym to jest opisaneciągła = HTTP z opisem w repo · przerywana = MCP (JSON-RPC)
Wszystko, co wchodzi do LAB247, idzie przez HTTP z JSON-em i schematem zod — to materiał na dokument OpenAPI. JSON-RPC jest dziś tylko po stronie agentów, w MCP. Nazwa pod interfejsem mówi, gdzie leży jego opis.
TAB. 1Dwa standardy, dwie roleformat wywołania · opis API
| JSON-RPC 2.0 | OpenAPI 3.2.1 | |
|---|---|---|
| Czym jest | Format wiadomości: wywołaj metodę z parametrami, dostań wynik albo błąd. | Opis API HTTP: ścieżki, metody, parametry, schematy treści, odpowiedzi, uwierzytelnianie. |
| Co standaryzuje | Kopertę (jsonrpc, method, params, id) i kody błędów — nie treść parametrów. | Dokument maszynowy o API — samo API może być dowolnym HTTP. |
| Transport | Dowolny: HTTP, WebSocket, gniazdo, stdin/stdout procesu. | HTTP. |
| Adres | Jeden punkt wejścia; co robić mówi method. | Wiele ścieżek i metod HTTP; co robić mówi adres + metoda. |
| Błędy | Obiekt error z kodem liczbowym (TAB. 3); status HTTP bez znaczenia. | Statusy HTTP + opisany schemat treści błędu. |
| Po co agentowi AI | MCP: narzędzia agenta są metodami JSON-RPC (tools/list, tools/call). | Z dokumentu OpenAPI da się wygenerować klienta, walidację i opis narzędzi dla agenta. |
TAB. 2JSON-RPC 2.0: obiektyspecyfikacja
| Żądanie | jsonrpc = „2.0” (dokładnie), method (nazwy od rpc. zarezerwowane), params (obiekt albo tablica, opcjonalnie), id (tekst, liczba albo null — null odradzany, liczby bez części ułamkowej). |
|---|---|
| Powiadomienie | Żądanie bez id. Serwer NIE odpowiada — także w paczce. Wygodne do zdarzeń, ale nadawca nie wie, czy doszło. |
| Odpowiedź | jsonrpc, id takie jak w żądaniu i dokładnie jedno z: result albo error. |
| Błąd | code (liczba całkowita), message (krótki opis), data (opcjonalnie — szczegóły). |
| Paczka (batch) | Tablica żądań; odpowiedzi w dowolnej kolejności, parowane po id. Pusta tablica albo niepoprawny JSON = jedna odpowiedź z błędem. Same powiadomienia = brak odpowiedzi, nie pusta tablica. |
| Transport | „Niezależny od transportu” — ten sam format w procesie, przez gniazdo, HTTP albo kolejkę. |
→ {"jsonrpc": "2.0", "method": "strona.usterki", "params": {"domena": "example.pl"}, "id": 7}
← {"jsonrpc": "2.0", "result": {"wskaznik": 4, "usterki": ["vuln_cve"]}, "id": 7}
← {"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params", "data": "domena"}, "id": 7}Przykład nasz — metoda i dane zmyślone.
TAB. 3JSON-RPC 2.0: kody błędówzarezerwowane przez specyfikację
| Kod | Komunikat | Znaczy |
|---|---|---|
| -32700 | Parse error | serwer dostał niepoprawny JSON |
| -32600 | Invalid Request | JSON nie jest poprawnym żądaniem |
| -32601 | Method not found | metoda nie istnieje albo jest niedostępna |
| -32602 | Invalid params | niepoprawne parametry metody |
| -32603 | Internal error | wewnętrzny błąd JSON-RPC |
| -32000 … -32099 | Server error | zarezerwowane dla błędów implementacji |
TAB. 4OpenAPI: dokument i historiaobiekt główny · 3.2.1
| openapi | Wersja specyfikacji dokumentu (np. 3.2.1) — wymagane. |
| info | Tytuł, wersja API, opis, kontakt, licencja — wymagane. |
| $self | Własny adres dokumentu (baza dla odwołań) — nowe w 3.2. |
| jsonSchemaDialect | Domyślny dialekt schematów; od 3.1 pełny JSON Schema 2020-12. |
| servers | Adresy, pod którymi API działa. |
| paths | Ścieżki i ich operacje (GET, POST…; w 3.2 także QUERY i additionalOperations). |
| webhooks | Wywołania przychodzące, które API wysyła do odbiorców (od 3.1). |
| components | Schematy, odpowiedzi, parametry, zabezpieczenia do wielokrotnego użycia; w 3.2 także mediaTypes. |
| security | Wymagane mechanizmy (np. Bearer). |
| tags · externalDocs | Grupowanie operacji (w 3.2 z hierarchią) i dokumentacja zewnętrzna. |
| 2011 | Swagger — format opisu API firmy Wordnik, potem SmartBear. |
| 2014 | Swagger 2.0. |
| 2015–2016 | Specyfikacja przekazana do OpenAPI Initiative (Linux Foundation), nazwa zmieniona na OpenAPI. |
| 2017 | OpenAPI 3.0.0 — components, requestBody, callbacks. |
| 2021 | 3.1.0 — schematy w pełni zgodne z JSON Schema 2020-12, webhooks. |
| 19.09.2025 | 3.2.0 — $self, metoda QUERY, strumienie (JSON Lines, zdarzenia SSE), hierarchia tagów, mediaTypes. |
| 10.09.2026 | 3.2.1 — poprawki, obecna wersja. |
Wymagane są tylko openapi i info oraz co najmniej jedno z paths, webhooks, components.
TAB. 5Interfejsy LAB247kto do kogo · czym opisane
| Nadawca | Interfejs | Odbiorca | Opis | Tras | Uwaga |
|---|---|---|---|---|---|
| Wtyczka Creato Ping | POST /api/v1/ingest/agent-message | baza LAB247 | zod + Markdown | 1 | Bearer, zdarzenia krytyczne od razu, komunikat dobowy. |
| Helpery i skaner PING | POST /api/v1/ingest/{rodzaj} | baza LAB247 | zod + Markdown | 11 rodzajów | checks, sites, findings, plugin-report, audit, vulnerabilities, software, news, schedule, agent-message, work-report. |
| Wordfence | POST /api/v1/hooks/wordfence | baza LAB247 | HMAC + zod | 1 | Jedyna trasa publiczna z zewnątrz; podpis HMAC na surowym ciele. |
| Panel LAB247 | API skanera 127.0.0.1 | baza skanera | docstring | 37 GET · 13 POST · 5 PUT | Tylko lokalnie. Docstring wymienia 35 tras GET, kod ma 37 — opis już się rozjechał. |
| Claude Code (Agenci AI) | MCP | ClickUp, Notion… | JSON-RPC (MCP) | — | Narzędzia agenta to metody JSON-RPC; LAB247 nie wystawia własnego serwera MCP. |
TAB. 6Błędy LAB247 i próba JSON Schemadziś REST + zod · jutro OpenAPI z tego samego
| Status | Znaczenie w API LAB247 |
|---|---|
| 400 | niepoprawny JSON — odpowiednik -32700 |
| 401 / 403 | brak albo zły token, zła rola |
| 404 | nieznany rodzaj ingestu — odpowiednik -32601 |
| 413 | ciało powyżej 2 MB |
| 422 | zły kształt po schemacie zod — odpowiednik -32602 |
| Treść | {"status": "fail", "error": "…", "details"?: …} — jeden kształt we wszystkich trasach (app/api/respond.ts). |
| Schemat ingestu | JSON Schema (znaki) | Wynik |
|---|---|---|
| checks | 2495 | bez błędu |
| sites | 1543 | bez błędu |
| findings | 1277 | bez błędu |
| plugin-report | 1538 | bez błędu |
| audit | 558 | bez błędu |
| software | 1981 | bez błędu |
| agent-message | 1202 | bez błędu |
| work-report | 3936 | bez błędu |
| schedule | 2510 | bez błędu |
| wordfence (webhook i vulnerabilities) | 5266 | bez błędu |
OpenAPI 3.1 i 3.2 używają JSON Schema 2020-12 wprost, więc te schematy wchodzą do components.schemas bez tłumaczenia. Brakuje tylko ścieżek, uwierzytelniania i odpowiedzi — to kilkadziesiąt linii opisu, nie przepisanie API.
TAB. 7Standard w LAB247co jest, co warto, czego nie
| Co | Stan | Jak |
|---|---|---|
| Kontrakt ingestu | działa | Każdy rodzaj ma schemat zod walidowany przy wejściu i opis w docs/ingest-contract.md. Jeden kształt błędu, statusy HTTP jak w TAB. 6. |
| Dokument OpenAPI | dług | Nie ma. Próba z 26.09: z.toJSONSchema() zamienia 10 z 10 schematów bez błędu (TAB. 6) — dokument OpenAPI 3.1/3.2 da się złożyć z tego, co jest, bez przepisywania walidacji. Zysk: opis nie rozjedzie się z kodem, klient i narzędzia agenta z generatora. |
| Opis API skanera | dług | Docstring w skaner/api.py — już dziś 2 trasy GET za mało. Kandydat na ten sam dokument OpenAPI (serwer 127.0.0.1). |
| JSON-RPC między skanerem a LAB247 | nie robimy | Interfejsy są REST-owe (rodzaj w adresie, status HTTP), a nadawca wysyła paczki raz na przebieg. Zamiana na JSON-RPC nic by nie dała poza kopertą. |
| Serwer MCP LAB247 dla Agentów AI | nie robimy | Agenci czytają dziś bazę i ClickUp przez własne narzędzia. Serwer MCP (JSON-RPC) z narzędziami „strona”, „usterki”, „podatności” byłby naturalnym miejscem dla tego standardu — już zapisany jako dług katalogu Rozszerzeń („endpoint dla Agentów AI”, spec §8). |
TAB. 8Graniceczego protokół i opis nie dają
| Koperta ≠ treść | JSON-RPC ustala kształt wywołania, nie znaczenie parametrów. „Ustrukturyzowane Znaleziska” daje schemat (zod, JSON Schema), nie protokół. |
| Opis ≠ zachowanie | Dokument OpenAPI może kłamać tak samo jak docstring, jeśli nie powstaje z kodu. Wartość jest w generowaniu, nie w pisaniu ręcznie. |
| Powiadomienie bez potwierdzenia | Powiadomienie JSON-RPC nie dostaje odpowiedzi — dla zdarzeń bezpieczeństwa (wtyczka) potrzebne jest potwierdzenie przyjęcia, które mamy w HTTP. |
| Status HTTP w JSON-RPC nic nie znaczy | Przez HTTP odpowiedź z błędem bywa 200. Monitoring patrzący tylko na status nie zobaczy awarii. |
TAB. 9Jak czytać liczby i skąd się wzięłykod LAB247 i skanera · 26.09.2026
- Wersje
- JSON-RPC 2.0 (2010, poprawka 2013), OpenAPI 3.2.1 (10.09.2026), MCP 2026-07-28 — strony specyfikacji odczytane 26.09.2026.
- Trasy LAB247
- Policzone z kodu: 12 plików route.ts w site/src/app/api, 11 rodzajów w INGEST_KINDS; skaner: 37 wyrażeń w _TRASY_GET, docstring modułu 35 GET, 13 POST, 5 PUT.
- Próba JSON Schema
- Skrypt jednorazowy (tsx) wywołał z.toJSONSchema (zod 4.5, io: input) na 10 schematach ingestu; rozmiar = długość wynikowego JSON-a w znakach. news i vulnerabilities mają osobne parsery — vulnerabilities dzieli schemat z webhookiem Wordfence.