SOQVER Preparate una fonte
Italiano

Guida per sviluppatori

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.

Tutto in un unico posto

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

1. Ottenere il codice

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

2. Validare una fonte

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.

3. Chiedere se un fatto può essere usato

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 è.

JavaScript

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

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.

MotivoChe cosa significa
expired, not_yet_validL'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_applicableL'editore dichiara esplicitamente che il valore non è noto o non si applica. Sconosciuto non è zero.
disputedL'affermazione è contestata.
no_trust_policyIl compito richiede un'affermazione revisionata ma non dice di chi si fida. Decidere di chi fidarsi spetta a chi legge l'affermazione.
attestation_not_authenticatedLa 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_claimsDue dichiarazioni correnti indicano valori diversi per la stessa cosa. Il lettore non ne usa nessuna e non sceglie mai in silenzio un vincitore.
invalid_sourceLa fonte infrange la struttura del formato (ad esempio una dichiarazione senza evidenza o una data illeggibile). Nulla di essa viene utilizzato.
unsupported_versionLa 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.

4. Pubblicare la propria fonte

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"
    }
  ]
}
  1. Salvi il file come so4ag.json e lo controlli con il validatore (passo 2).
  2. La serva tramite HTTPS sul Suo dominio all'indirizzo /so4ag.json con il tipo application/json.
  3. Aggiunga un link alla sorgente nelle pagine per le persone:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Per avere gli stessi fatti all'interno della pagina, converta la sorgente in JSON-LD e inserisca il risultato in un tag <script type="application/ld+json">. La conversione è senza perdite.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Assegni a ogni affermazione una fine di validità (valid_until) e confermi o modifichi l'affermazione prima che scada. Dopo quel momento i lettori smettono di usarla.

Qualsiasi settore: il profilo General e il vostro profilo

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.

ProfiloPer chi
GeneralQualsiasi 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 dettaglioCiò che è specifico del settore: cauzione, limite di chilometraggio, spedizione, resi.
VostroTutto 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."
    }
  }
}
  1. Pubblicate il file via HTTPS all'indirizzo indicato in id e aggiungete quell'indirizzo a profiles nella vostra fonte.
  2. Scrivete la proprietà di un'asserzione come namespace + nome, cioè https://dental.example/so4ag-profile#emergencySlot.
  3. Controllate il profilo e la fonte:
    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.json

Un 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.

5. Leggere le fonti pubblicate tramite l'API

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.

6. Collegare un agente tramite MCP

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
StrumentoChe cosa fa
list_sourcesElenca le fonti pubblicate.
get_sourceRestituisce l'intera fonte di un'azienda.
get_claimsValuta le affermazioni di una fonte per una proprietà e condizioni date.
check_claimIndica 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"}'

7. Scrivere il proprio lettore

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.

Dove trovare il progetto

LuogoA cosa serve
GitHub: soqvercom/so4agCodice, specifica, suite di conformità e rilasci. È qui che viene sviluppato il formato.
GitHub DiscussionsIl luogo della comunità: domande, proposte ed esperienza con il formato. Rispondiamo qui.
GitHub IssuesErrori nella specifica e nel codice, casi che il formato non può esprimere.
PyPI: so4agIl pacchetto Python: pip install so4ag
RilasciIl 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 RegistryLa voce del nostro server MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGDomande rapide e una chat con altri che provano il formato.
DEV: @soqvercomArticoli tecnici e testi pratici sul formato.
daily.dev: @soqverCollegamenti ai nuovi articoli per gli sviluppatori.
X · YouTubeNovità sul formato e brevi demo.

Feedback ed errori

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].