SO4AG è un formato aperto per i fatti aziendali: ogni fatto reca significato, ambito, origine e validità. Un lettore risponde a una sola domanda: questo fatto può essere usato per questo compito in questo momento e, in caso contrario, perché no.
Il formato è gratuito e non richiede un account. Il codice è concesso in licenza Apache-2.0, il testo della specifica in CC BY 4.0.
Repository su GitHub · specifica · JSON Schema · suite di conformità · JSON-LD · validatore nel browser · cosa funziona
Contenuti: 1. Ottenere il codice · 2. Validare una fonte · 3. Chiedere di un fatto · 4. Pubblicare la propria fonte · 5. API · 6. MCP · 7. Il proprio lettore · Qualsiasi settore · Dove trovare il progetto
Le servono Git e Node.js 20 o successivo. Il lettore Python richiede solo la libreria standard (Python 3.10 o successivo).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
L'ultimo comando esegue i test del codice di riferimento rispetto alla suite di conformità. Tutti dovrebbero essere superati.
Nel vostro progetto i pacchetti si installano con un comando ciascuno:
npm install github:soqvercom/so4ag#v0.1.3
npx so4ag-validate https://example.com/so4ag.json
pip install so4ag
so4ag ask so4ag.json --property refundableDeposit --scope vehicle_class=economy
Il validatore legge un file o un indirizzo. Comprende il JSON SO4AG, la forma JSON-LD e una pagina HTML con il JSON-LD al suo interno.
node validator/cli.mjs examples/valid/rental-first-party.json
node validator/cli.mjs https://example.com/so4ag.json
node validator/cli.mjs examples/valid/rental-first-party.json --json
La risposta inizia con VALID o INVALID. Per una sorgente non valida segue un elenco di errori con la loro posizione nel file. Senza installare nulla, lo stesso funziona nel validatore nel browser.
Una sorgente valida dimostra soltanto la correttezza della struttura. Non dice che il fatto sia vero.
Un compito indica quale proprietà si interroga e per quali condizioni (ambito). Il lettore restituisce ogni affermazione corrispondente con la risposta se è utilizzabile e i motivi quando non lo è.
import { readFileSync } from 'node:fs';
import { validateManifest, selectClaims } from './validator/index.mjs';
const source = JSON.parse(readFileSync('examples/valid/rental-first-party.json', 'utf8'));
const check = validateManifest(source); // { valid, errors, warnings, stats }
const answers = selectClaims(source, {
property: 'https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit',
scope: { branch: 'https://rental.example/branches/prague-airport', vehicle_class: 'economy' },
});
for (const { claim, result } of answers) console.log(claim.id, result.usable, result.reasons, result.value);
python readers/python/so4ag_reader.py ask examples/valid/rental-first-party.json \
--property refundableDeposit --scope vehicle_class=economy \
--scope branch=https://rental.example/branches/prague-airport
Provi lo stesso senza la condizione di filiale o in un altro momento (--now 2027-06-01T12:00:00Z, in JavaScript il terzo argomento { now: new Date(…) }). L'affermazione cessa di essere utilizzabile e il lettore ne dice il motivo.
| Motivo | Che cosa significa |
|---|---|
expired, not_yet_valid | L'affermazione non vale al momento della domanda. |
scope_mismatch:<key> | L'affermazione vale per un altro valore della condizione, per esempio un'altra filiale. |
scope_not_in_task:<key> | L'affermazione è limitata da una condizione che il compito non indica. Senza di essa nessuno può dire se l'affermazione si applica. |
unknown, not_applicable | L'editore dichiara esplicitamente che il valore non è noto o non si applica. Sconosciuto non è zero. |
disputed | L'affermazione è contestata. |
no_trust_policy | Il compito richiede un'affermazione revisionata ma non dice di chi si fida. Decidere di chi fidarsi spetta a chi legge l'affermazione. |
attestation_not_authenticated | La fonte riporta un'attestazione con il nome di un emittente di cui Lei si fida, ma non l'ha autenticata presso l'emittente. Un nome scritto nella fonte non costituisce una prova. |
conflicting_claims | Due dichiarazioni correnti indicano valori diversi per la stessa cosa. Il lettore non ne usa nessuna e non sceglie mai in silenzio un vincitore. |
invalid_source | La fonte infrange la struttura del formato (ad esempio una dichiarazione senza evidenza o una data illeggibile). Nulla di essa viene utilizzato. |
unsupported_version | La sorgente è di una versione del formato che il lettore non conosce. Non viene letta secondo le regole di un'altra versione. |
L'elenco completo dei motivi e delle regole si trova nella specifica.
Una sorgente è un file JSON. La forma minima utile ha un editore e un'affermazione:
{
"so4ag": "0.1-draft",
"id": "https://rental.example/so4ag.json",
"revision": "2026-11-20.1",
"published_at": "2026-11-19T20:05:00Z",
"publisher": {
"id": "https://rental.example/#org",
"name": "Example Rental",
"role": "first_party",
"domain": "rental.example"
},
"profiles": ["https://soqver.com/spec/so4ag/0.1/rental"],
"subjects": [
{ "id": "https://rental.example/#org", "type": "AutoRental", "name": "Example Rental" },
{ "id": "https://rental.example/branches/prague-airport", "type": "Place", "name": "Prague Airport" }
],
"claims": [
{
"id": "https://rental.example/claims/deposit-economy-airport",
"revision": "3",
"subject": "https://rental.example/#org",
"property": "https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit",
"knowledge_state": "known",
"value": { "type": "money", "amount": "10000.00", "currency": "CZK" },
"scope": { "branch": "https://rental.example/branches/prague-airport", "vehicle_class": "economy" },
"assertion_basis": "publisher_asserted",
"evidence": [
{ "url": "https://rental.example/terms#deposit", "observed_at": "2026-11-19T20:00:00Z", "kind": "webpage" }
],
"valid_from": "2026-11-20T00:00:00Z",
"valid_until": "2026-12-20T00:00:00Z"
}
]
}
so4ag.json e lo controlli con il validatore (passo 2)./so4ag.json con il tipo application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. La conversione è senza perdite. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) e confermi o modifichi l'affermazione prima che scada. Dopo quel momento i lettori smettono di usarla.Il formato non è legato a un settore. Le proprietà (il significato di un fatto, il suo tipo e la sua unità, e quali condizioni lo limitano) sono definite da un profilo, e una fonte può usare più profili insieme.
| Profilo | Per chi |
|---|---|
| General | Qualsiasi impresa o organizzazione: operatore, sedi e orari di apertura, contatti, lingue, che cosa offre e a quanto, pagamento, prenotazione, tempi di risposta e di consegna, annullamento, garanzia, accessibilità, licenze, disponibilità. 26 proprietà. |
| Noleggio veicoli, Vendita al dettaglio | Ciò che è specifico del settore: cauzione, limite di chilometraggio, spedizione, resi. |
| Vostro | Tutto il resto. Un profilo è un file JSON sul vostro dominio; non chiedete nulla a nessuno e non registrate nulla. |
Il vostro profilo descrive le vostre proprietà come i nostri: etichetta, descrizione, tipo di valore, unità, codici consentiti e condizioni. La forma minima:
{
"id": "https://dental.example/so4ag-profile",
"name": "Example Dental profile",
"version": "1",
"namespace": "https://dental.example/so4ag-profile#",
"scope_keys": { "day_type": "weekday, weekend, public_holiday, any" },
"properties": {
"emergencySlot": {
"label": { "en": "Same-day treatment of acute pain" },
"value_types": ["boolean"],
"required_scope": ["day_type"],
"max_validity": "P90D",
"description": "Whether a patient with acute pain is treated on the day of the call."
}
}
}
id e aggiungete quell'indirizzo a profiles nella vostra fonte.namespace + nome, cioè https://dental.example/so4ag-profile#emergencySlot.node validator/cli.mjs --check-profile examples/profiles/dental-example-profile.json
node validator/cli.mjs examples/valid/general-dental.json --profile examples/profiles/dental-example-profile.jsonUn lettore che non conosce il vostro profilo usa comunque l'asserzione quando il compito ne indica le condizioni; quando il compito non le indica, l'asserzione non viene usata. Le regole di sicurezza del formato valgono quindi allo stesso modo per ogni profilo. Un esempio completo di uno studio odontoiatrico con il profilo General e il proprio profilo si trova nel repository: general-dental.json. Schema di un profilo: profile.schema.json.
Preferisce non scrivere il file a mano? Il servizio SOQVER prepara una proposta a partire dal Suo sito, Lei conferma i fatti e pubblica la sorgente con noi oppure la scarica per il proprio dominio: preparare una sorgente.
L'interfaccia è di sola lettura e non richiede né un account né una chiave.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Il primo indirizzo restituisce l'elenco delle fonti che un'azienda ha pubblicato o confermato. Il secondo valuta le affermazioni di una fonte per il Suo compito e restituisce usable e reasons per ciascuna. Ogni fonte è anche una pagina per le persone (/s/<slug>/), un file /s/<slug>/so4ag.json e una forma JSON-LD /s/<slug>/facts.jsonld.
Il server MCP è di sola lettura, non richiede un account e usa il trasporto Streamable HTTP. Nell'MCP Registry ufficiale è elencato come com.soqver/so4ag.
https://soqver.com/mcp
| Strumento | Che cosa fa |
|---|---|
list_sources | Elenca le fonti pubblicate. |
get_source | Restituisce l'intera fonte di un'azienda. |
get_claims | Valuta le affermazioni di una fonte per una proprietà e condizioni date. |
check_claim | Indica se un'affermazione può essere usata ora e, in caso contrario, perché. |
In un client che supporta i server MCP remoti, inserisca l'indirizzo indicato sopra. Può verificare la risposta del server anche dalla riga di comando:
curl -s https://soqver.com/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
La suite di conformità è JSON puro e non richiede alcun nostro codice. Contiene due fonti valide in tre forme, i digest attesi delle dichiarazioni, 45 casi di valutazione, 31 casi di validazione, 10 casi sull'intera fonte e 25 vettori della forma canonica (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Quando un lettore o un validatore supera la suite è descritto nella descrizione della suite di conformità. Il lettore Python è stato scritto indipendentemente dal codice di riferimento e supera la stessa suite; può usarlo come modello.
| Luogo | A cosa serve |
|---|---|
| GitHub: soqvercom/so4ag | Codice, specifica, suite di conformità e rilasci. È qui che viene sviluppato il formato. |
| GitHub Discussions | Il luogo della comunità: domande, proposte ed esperienza con il formato. Rispondiamo qui. |
| GitHub Issues | Errori nella specifica e nel codice, casi che il formato non può esprimere. |
| PyPI: so4ag | Il pacchetto Python: pip install so4ag |
| Rilasci | Il pacchetto JavaScript e i file di ogni versione: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Un collegamento permanente ai rilasci per la citazione in articoli e documentazione. |
| MCP Registry | La voce del nostro server MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Domande rapide e una chat con altri che provano il formato. |
| DEV: @soqvercom | Articoli tecnici e testi pratici sul formato. |
| daily.dev: @soqver | Collegamenti ai nuovi articoli per gli sviluppatori. |
| X · YouTube | Novità sul formato e brevi demo. |
Ha trovato un fatto che il formato non può esprimere, o due lettori che rispondono in modo diverso? Lo scriva come issue su GitHub. Segnali una vulnerabilità via e-mail a [email protected].