SOQVER Valmistakaa lähde
Suomi

Opas kehittäjille

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

Kaikki yhdessä paikassa

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

1. Hakekaa koodi

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

2. Validoikaa lähde

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.

3. Kysykää, saako faktaa käyttää

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.

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

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.

SyyMitä se tarkoittaa
expired, not_yet_validVä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_applicableJulkaisija ilmoittaa nimenomaisesti, että arvoa ei tiedetä tai ettei se sovellu. Tuntematon ei ole nolla.
disputedVäite on kiistetty.
no_trust_policyTehtävä pyytää tarkastettua väitettä mutta ei ilmoita, kehen se luottaa. Kehen luotetaan, on väitteen lukijan päätös.
attestation_not_authenticatedLä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_claimsKaksi voimassa olevaa väitettä esittää samasta asiasta eri arvot. Lukija ei käytä kumpaakaan eikä koskaan valitse voittajaa hiljaa.
invalid_sourceLähde rikkoo formaatin rakenteen (esimerkiksi väite ilman näyttöä tai lukukelvoton päivämäärä). Siitä ei käytetä mitään.
unsupported_versionLä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.

4. Julkaiskaa oma lähteenne

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"
    }
  ]
}
  1. Tallentakaa tiedosto nimellä so4ag.json ja tarkistakaa se validaattorilla (vaihe 2).
  2. Tarjotkaa se HTTPS:n kautta omalla verkkotunnuksellanne osoitteessa /so4ag.json tyypillä application/json.
  3. Lisätkää linkki lähteeseen ihmisille tarkoitetuille sivuille:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Jotta samat faktat ovat sivun sisällä, muuntakaa lähde JSON-LD-muotoon ja sijoittakaa tulos <script type="application/ld+json">-tagiin. Muunnos on häviötön.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Antakaa jokaiselle väitteelle voimassaolon päättyminen (valid_until) ja vahvistakaa tai muuttakaa väite ennen sen umpeutumista. Sen jälkeen lukijat lakkaavat käyttämästä sitä.

Mikä tahansa toimiala: General-profiili ja oma profiili

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

ProfiiliKenelle
GeneralMikä 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äiskauppaToimialalle ominaista: vakuus, kilometriraja, toimitus, palautukset.
OmaMitä 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."
    }
  }
}
  1. Tarjotkaa tiedosto HTTPS:n kautta osoitteessa, joka on annettu kohdassa id, ja lisätkää kyseinen osoite lähteessänne kohtaan profiles.
  2. Kirjoittakaa väitteen ominaisuus muodossa namespace + nimi, eli https://dental.example/so4ag-profile#emergencySlot.
  3. Tarkistakaa profiili ja lähde:
    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

Lukija, 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.

5. Lukekaa julkaistuja lähteitä APIn kautta

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.

6. Yhdistäkää agentti MCP:n kautta

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ökaluMitä se tekee
list_sourcesLuettelee julkaistut lähteet.
get_sourcePalauttaa yhden yrityksen koko lähteen.
get_claimsArvioi lähteen väitteet annetulle ominaisuudelle ja annetuille ehdoille.
check_claimKertoo, 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"}'

7. Kirjoittakaa oma lukijanne

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.

Mistä projekti löytyy

PaikkaMihin se on tarkoitettu
GitHub: soqvercom/so4agKoodi, spesifikaatio, yhteensopivuustestit ja julkaisut. Formaattia kehitetään täällä.
GitHub DiscussionsYhteisön paikka: kysymykset, ehdotukset ja kokemukset formaatista. Vastaamme täällä.
GitHub IssuesVirheet spesifikaatiossa ja koodissa sekä tapaukset, joita formaatti ei voi ilmaista.
PyPI: so4agPython-paketti: pip install so4ag
JulkaisutJavaScript-paketti ja jokaisen version tiedostot: npm install github:soqvercom/so4ag
Zenodo (DOI)Pysyvä linkki julkaisuihin viittaamista varten artikkeleissa ja dokumentaatiossa.
MCP RegistryMCP-palvelimemme tietue: com.soqver/so4ag
Discord: SOQVER · SO4AGNopeat kysymykset ja keskustelu muiden muotoa kokeilevien kanssa.
DEV: @soqvercomTeknisiä artikkeleita ja ohjetekstejä muodosta.
daily.dev: @soqverLinkkejä uusiin artikkeleihin kehittäjille.
X · YouTubeUutisia formaatista ja lyhyitä demoja.

Palaute ja virheet

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