SO4AG on avoin muoto yritysfaktoille: jokainen fakta sisältää merkityksensä, soveltamisalansa, alkuperänsä ja voimassaolonsa. Lukija vastaa yhteen kysymykseen: saako tätä faktaa käyttää tähän tehtävään tällä hetkellä, ja jos ei, miksi ei.
Muoto on maksuton eikä vaadi tiliä. Koodi on lisensoitu Apache-2.0-lisenssillä ja spesifikaation teksti CC BY 4.0 -lisenssillä.
Tietovarasto GitHubissa · spesifikaatio · JSON Schema · yhteensopivuustestisarja · JSON-LD · validaattori selaimessa · mikä toimii
Sisällys: 1. Hakekaa koodi · 2. Validoikaa lähde · 3. Kysykää faktasta · 4. Julkaiskaa oma lähde · 5. API · 6. MCP · 7. Oma lukija · Mikä tahansa toimiala · Mistä projekti löytyy
Tarvitsette Gitin ja Node.js 20:n tai uudemman. Python-lukija tarvitsee vain standardikirjaston (Python 3.10 tai uudempi).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Viimeinen komento ajaa viitekoodin testit yhteensopivuustestisarjaa vasten. Kaikkien tulisi mennä läpi.
Paketit asentuvat omaan projektiinne kukin yhdellä komennolla:
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
Validaattori lukee tiedoston tai osoitteen. Se ymmärtää SO4AG JSON -muodon, JSON-LD-muodon ja HTML-sivun, jonka sisällä on JSON-LD.
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
Vastaus alkaa sanalla VALID tai INVALID. Virheellisestä lähteestä seuraa luettelo virheistä ja niiden paikasta tiedostossa. Ilman asennuksia sama toimii validaattorissa selaimessa.
Kelvollinen lähde todistaa vain rakenteen oikeellisuuden. Se ei sano, että fakta on tosi.
Tehtävä ilmoittaa, mitä ominaisuutta kysytte ja millä ehdoilla (soveltamisala). Lukija palauttaa jokaisen vastaavan väitteen sekä vastauksen siihen, onko se käyttökelpoinen, ja syyt, jos se ei ole.
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
Kokeilkaa samaa ilman toimipiste-ehtoa tai toisena ajankohtana (--now 2027-06-01T12:00:00Z, JavaScriptissä kolmas argumentti { now: new Date(…) }). Väite lakkaa olemasta käyttökelpoinen, ja lukija kertoo, miksi.
| Syy | Mitä se tarkoittaa |
|---|---|
expired, not_yet_valid | Väite ei päde kysymyksen ajankohtana. |
scope_mismatch:<key> | Väite pätee ehdon toisella arvolla, esimerkiksi toisella toimipisteellä. |
scope_not_in_task:<key> | Väitettä rajaa ehto, jota tehtävä ei ilmoita. Ilman sitä kukaan ei voi sanoa, soveltuuko väite. |
unknown, not_applicable | Julkaisija ilmoittaa nimenomaisesti, että arvoa ei tiedetä tai ettei se sovellu. Tuntematon ei ole nolla. |
disputed | Väite on kiistetty. |
no_trust_policy | Tehtävä pyytää tarkastettua väitettä mutta ei ilmoita, kehen se luottaa. Kehen luotetaan, on väitteen lukijan päätös. |
attestation_not_authenticated | Lähde sisältää attestaation, jossa on luottamanne myöntäjän nimi, mutta ette ole todentanut sitä myöntäjän kanssa. Lähteeseen kirjoitettu nimi ei ole todiste. |
conflicting_claims | Kaksi voimassa olevaa väitettä esittää samasta asiasta eri arvot. Lukija ei käytä kumpaakaan eikä koskaan valitse voittajaa hiljaa. |
invalid_source | Lähde rikkoo formaatin rakenteen (esimerkiksi väite ilman näyttöä tai lukukelvoton päivämäärä). Siitä ei käytetä mitään. |
unsupported_version | Lähde on muodon versiossa, jota lukija ei tunne. Sitä ei lueta toisen version säännöillä. |
Täydellinen luettelo syistä ja säännöistä on spesifikaatiossa.
Lähde on yksi JSON-tiedosto. Pienin hyödyllinen muoto sisältää julkaisijan ja yhden väitteen:
{
"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 ja tarkistakaa se validaattorilla (vaihe 2)./so4ag.json tyypillä application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">-tagiin. Muunnos on häviötön. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) ja vahvistakaa tai muuttakaa väite ennen sen umpeutumista. Sen jälkeen lukijat lakkaavat käyttämästä sitä.Muoto ei ole sidottu toimialaan. Ominaisuudet (mitä fakta tarkoittaa, sen tyyppi ja yksikkö sekä mitkä ehdot rajaavat sitä) määrittelee profiili, ja yksi lähde voi käyttää useita profiileja yhdessä.
| Profiili | Kenelle |
|---|---|
| General | Mikä tahansa yritys tai organisaatio: toimija, toimipaikat ja aukioloajat, yhteystiedot, kielet, mitä se tarjoaa ja mihin hintaan, maksu, varaus, vastaus- ja toimitusajat, peruutus, takuu, saavutettavuus, luvat, saatavuus. 26 ominaisuutta. |
| Ajoneuvovuokraus, Vähittäiskauppa | Toimialalle ominaista: vakuus, kilometriraja, toimitus, palautukset. |
| Oma | Mitä tahansa muuta. Profiili on JSON-tiedosto verkkotunnuksellanne; ette kysy keneltäkään ettekä rekisteröi mitään. |
Oma profiilinne kuvaa ominaisuutenne samalla tavalla kuin meidän profiilimme: nimiö, kuvaus, arvotyyppi, yksiköt, sallitut koodit ja ehdot. Pienin muoto:
{
"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, ja lisätkää kyseinen osoite lähteessänne kohtaan profiles.namespace + nimi, eli 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.jsonLukija, joka ei tunne profiilianne, käyttää väitettä silti, kun tehtävä ilmoittaa sen ehdot; kun tehtävä ei ilmoita niitä, väitettä ei käytetä. Muodon turvallisuussäännöt pätevät siksi jokaiseen profiiliin samalla tavoin. Täydellinen esimerkki hammaslääkäriasemasta, jossa on General-profiili ja sen oma profiili, on repositoriossa: general-dental.json. Profiilin skeema: profile.schema.json.
Ette mieluusti kirjoita tiedostoa käsin? SOQVER-palvelu laatii ehdotuksen verkkosivustonne pohjalta, vahvistatte faktat ja julkaisette lähteen meillä tai lataatte sen omalle verkkotunnuksellenne: valmistele lähde.
Käyttöliittymä on vain luettavissa, eikä se vaadi tiliä eikä avainta.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Ensimmäinen osoite palauttaa luettelon lähteistä, jotka yritys on julkaissut tai vahvistanut. Toinen arvioi yhden lähteen väitteet tehtäväänne ja palauttaa kullekin usable ja reasons. Jokainen lähde on myös sivu ihmisille (/s/<slug>/), tiedosto /s/<slug>/so4ag.json ja JSON-LD-muoto /s/<slug>/facts.jsonld.
MCP-palvelin on vain luettavissa, ei vaadi tiliä ja käyttää Streamable HTTP -siirtoa. Virallisessa MCP Registryssä se on luettelossa nimellä com.soqver/so4ag.
https://soqver.com/mcp
| Työkalu | Mitä se tekee |
|---|---|
list_sources | Luettelee julkaistut lähteet. |
get_source | Palauttaa yhden yrityksen koko lähteen. |
get_claims | Arvioi lähteen väitteet annetulle ominaisuudelle ja annetuille ehdoille. |
check_claim | Kertoo, saako yhtä väitettä käyttää nyt ja miksi ei. |
Asiakasohjelmassa, joka tukee etä-MCP-palvelimia, antakaa yllä oleva osoite. Palvelimen vastauksen voi tarkistaa myös komentoriviltä:
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"}'
Yhteensopivuussarja on pelkkää JSONia eikä tarvitse koodiamme. Se sisältää kaksi kelvollista lähdettä kolmessa muodossa, väitteiden odotetut tiivisteet, 45 arviointitapausta, 31 validointitapausta, 10 koko lähteen tapausta ja 25 kanonisen muodon vektoria (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Se, milloin lukija tai validaattori läpäisee testisarjan, kuvataan yhteensopivuustestisarjan kuvauksessa. Python-lukija on kirjoitettu viitekoodista riippumatta ja läpäisee saman testisarjan; voitte käyttää sitä mallina.
| Paikka | Mihin se on tarkoitettu |
|---|---|
| GitHub: soqvercom/so4ag | Koodi, spesifikaatio, yhteensopivuustestit ja julkaisut. Formaattia kehitetään täällä. |
| GitHub Discussions | Yhteisön paikka: kysymykset, ehdotukset ja kokemukset formaatista. Vastaamme täällä. |
| GitHub Issues | Virheet spesifikaatiossa ja koodissa sekä tapaukset, joita formaatti ei voi ilmaista. |
| PyPI: so4ag | Python-paketti: pip install so4ag |
| Julkaisut | JavaScript-paketti ja jokaisen version tiedostot: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Pysyvä linkki julkaisuihin viittaamista varten artikkeleissa ja dokumentaatiossa. |
| MCP Registry | MCP-palvelimemme tietue: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Nopeat kysymykset ja keskustelu muiden muotoa kokeilevien kanssa. |
| DEV: @soqvercom | Teknisiä artikkeleita ja ohjetekstejä muodosta. |
| daily.dev: @soqver | Linkkejä uusiin artikkeleihin kehittäjille. |
| X · YouTube | Uutisia formaatista ja lyhyitä demoja. |
Löysittekö faktan, jota muoto ei pysty ilmaisemaan, tai kaksi lukijaa, jotka vastaavat eri tavoin? Kirjoittakaa siitä issue GitHubiin. Ilmoittakaa haavoittuvuus sähköpostitse osoitteeseen [email protected].