SOQVER Ετοιμάστε μια πηγή
Ελληνικά

Οδηγός για προγραμματιστές

Το SO4AG είναι μια ανοιχτή μορφή για επιχειρηματικά γεγονότα: κάθε γεγονός φέρει το νόημά του, το πεδίο εφαρμογής, την προέλευση και την ισχύ του. Ένας αναγνώστης απαντά σε μία ερώτηση: μπορεί αυτό το γεγονός να χρησιμοποιηθεί για αυτή την εργασία αυτή τη στιγμή και, αν όχι, γιατί όχι.

Η μορφή είναι δωρεάν και δεν απαιτεί λογαριασμό. Ο κώδικας διατίθεται με άδεια Apache-2.0 και το κείμενο της προδιαγραφής με άδεια CC BY 4.0.

Όλα σε ένα σημείο

Αποθετήριο στο GitHub · προδιαγραφή · JSON Schema · σουίτα συμμόρφωσης · JSON-LD · επικυρωτής στο πρόγραμμα περιήγησης · τι λειτουργεί

Περιεχόμενα: 1. Αποκτήστε τον κώδικα · 2. Επικυρώστε μια πηγή · 3. Ρωτήστε για ένα γεγονός · 4. Δημοσιεύστε τη δική σας πηγή · 5. API · 6. MCP · 7. Ο δικός σας αναγνώστης · Οποιοσδήποτε κλάδος · Πού θα βρείτε το έργο

1. Αποκτήστε τον κώδικα

Χρειάζεστε το Git και το Node.js 20 ή νεότερο. Ο αναγνώστης Python χρειάζεται μόνο την τυπική βιβλιοθήκη (Python 3.10 ή νεότερο).

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

Η τελευταία εντολή εκτελεί τις δοκιμές του κώδικα αναφοράς έναντι της σουίτας συμμόρφωσης. Όλες πρέπει να επιτύχουν.

Στο δικό σας έργο τα πακέτα εγκαθίστανται με μία εντολή το καθένα:

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. Επικυρώστε μια πηγή

Ο επικυρωτής διαβάζει ένα αρχείο ή μια διεύθυνση. Κατανοεί SO4AG JSON, τη μορφή JSON-LD και μια σελίδα HTML με το 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

Η απάντηση ξεκινά με VALID ή INVALID. Για μια μη έγκυρη πηγή ακολουθεί λίστα σφαλμάτων με τη θέση τους στο αρχείο. Χωρίς να εγκαταστήσετε τίποτα, το ίδιο λειτουργεί στον επικυρωτή στο πρόγραμμα περιήγησης.

Μια έγκυρη πηγή αποδεικνύει μόνο τη σωστή δομή. Δεν λέει ότι το γεγονός είναι αληθές.

3. Ρωτήστε αν ένα γεγονός μπορεί να χρησιμοποιηθεί

Μια εργασία δηλώνει για ποια ιδιότητα ρωτάτε και για ποιες συνθήκες (πεδίο εφαρμογής). Ο αναγνώστης επιστρέφει κάθε ταιριαστό ισχυρισμό με την απάντηση αν είναι χρησιμοποιήσιμος, και τους λόγους όταν δεν είναι.

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

Δοκιμάστε το ίδιο χωρίς τη συνθήκη υποκαταστήματος ή σε άλλη χρονική στιγμή (--now 2027-06-01T12:00:00Z, στη JavaScript το τρίτο όρισμα { now: new Date(…) }). Ο ισχυρισμός παύει να είναι χρησιμοποιήσιμος και ο αναγνώστης εξηγεί γιατί.

ΛόγοςΤι σημαίνει
expired, not_yet_validΟ ισχυρισμός δεν ισχύει τη χρονική στιγμή της ερώτησης.
scope_mismatch:<key>Ο ισχυρισμός ισχύει για άλλη τιμή της συνθήκης, για παράδειγμα άλλο υποκατάστημα.
scope_not_in_task:<key>Ο ισχυρισμός περιορίζεται από μια συνθήκη που η εργασία δεν δηλώνει. Χωρίς αυτήν κανείς δεν μπορεί να πει αν ο ισχυρισμός εφαρμόζεται.
unknown, not_applicableΟ εκδότης δηλώνει ρητά ότι η τιμή δεν είναι γνωστή ή δεν εφαρμόζεται. Το άγνωστο δεν είναι μηδέν.
disputedΟ ισχυρισμός αμφισβητείται.
no_trust_policyΗ εργασία ζητά ελεγμένο ισχυρισμό, αλλά δεν λέει ποιον εμπιστεύεται. Το ποιον να εμπιστευτεί κανείς είναι απόφαση εκείνου που διαβάζει τον ισχυρισμό.
attestation_not_authenticatedΗ πηγή φέρει βεβαίωση με το όνομα εκδότη που εμπιστεύεστε, αλλά δεν την έχετε αυθεντικοποιήσει με τον εκδότη. Ένα όνομα γραμμένο στην πηγή δεν αποτελεί απόδειξη.
conflicting_claimsΔύο τρέχοντες ισχυρισμοί δηλώνουν διαφορετικές τιμές για το ίδιο πράγμα. Ο αναγνώστης δεν χρησιμοποιεί κανέναν και δεν επιλέγει ποτέ σιωπηρά νικητή.
invalid_sourceΗ πηγή παραβιάζει τη δομή της μορφής (για παράδειγμα ισχυρισμός χωρίς τεκμήριο ή μη αναγνώσιμη ημερομηνία). Δεν χρησιμοποιείται τίποτα από αυτήν.
unsupported_versionΗ πηγή είναι μιας έκδοσης της μορφής που ο αναγνώστης δεν γνωρίζει. Δεν διαβάζεται με τους κανόνες άλλης έκδοσης.

Η πλήρης λίστα λόγων και κανόνων βρίσκεται στην προδιαγραφή.

4. Δημοσιεύστε τη δική σας πηγή

Μια πηγή είναι ένα αρχείο JSON. Η μικρότερη χρήσιμη μορφή έχει έναν εκδότη και έναν ισχυρισμό:

{
  "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. Αποθηκεύστε το αρχείο ως so4ag.json και ελέγξτε το με τον επικυρωτή (βήμα 2).
  2. Διαθέστε το μέσω HTTPS στον τομέα σας στο /so4ag.json με τον τύπο application/json.
  3. Προσθέστε σύνδεσμο προς την πηγή στις σελίδες για τους ανθρώπους:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Για να έχετε τα ίδια γεγονότα μέσα στη σελίδα, μετατρέψτε την πηγή σε JSON-LD και τοποθετήστε το αποτέλεσμα σε μια ετικέτα <script type="application/ld+json">. Η μετατροπή είναι χωρίς απώλειες.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Ορίστε σε κάθε ισχυρισμό ένα τέλος ισχύος (valid_until) και επιβεβαιώστε ή αλλάξτε τον ισχυρισμό πριν αυτό παρέλθει. Μετά από τότε οι αναγνώστες παύουν να τον χρησιμοποιούν.

Οποιοσδήποτε κλάδος: το προφίλ General και το δικό σας προφίλ

Η μορφή δεν δεσμεύεται σε έναν κλάδο. Οι ιδιότητες (τι σημαίνει ένα γεγονός, ο τύπος και η μονάδα του, και ποιες συνθήκες το περιορίζουν) ορίζονται από ένα προφίλ, και μία πηγή μπορεί να χρησιμοποιεί πολλά προφίλ μαζί.

ΠροφίλΓια ποιον
GeneralΚάθε επιχείρηση ή οργανισμός: φορέας, τοποθεσίες και ωράριο λειτουργίας, επαφές, γλώσσες, τι προσφέρει και σε ποια τιμή, πληρωμή, κράτηση, χρόνοι απόκρισης και παράδοσης, ακύρωση, εγγύηση, προσβασιμότητα, άδειες, διαθεσιμότητα. 26 ιδιότητες.
Ενοικίαση οχημάτων, ΛιανικήΌ,τι είναι ειδικό για τον κλάδο: εγγύηση, όριο χιλιομέτρων, αποστολή, επιστροφές.
Δικό σαςΟτιδήποτε άλλο. Ένα προφίλ είναι ένα αρχείο JSON στον τομέα σας· δεν ρωτάτε κανέναν και δεν εγγράφετε τίποτα.

Το δικό σας προφίλ περιγράφει τις ιδιότητές σας όπως και τα δικά μας: ετικέτα, περιγραφή, τύπος τιμής, μονάδες, επιτρεπόμενοι κωδικοί και συνθήκες. Η μικρότερη μορφή:

{
  "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. Εξυπηρετήστε το αρχείο μέσω HTTPS στη διεύθυνση που δίνεται στο id και προσθέστε αυτή τη διεύθυνση στο profiles της πηγής σας.
  2. Γράψτε την ιδιότητα ενός ισχυρισμού ως namespace + όνομα, δηλαδή https://dental.example/so4ag-profile#emergencySlot.
  3. Ελέγξτε το προφίλ και την πηγή:
    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

Ένας αναγνώστης που δεν γνωρίζει το προφίλ σας εξακολουθεί να χρησιμοποιεί τον ισχυρισμό όταν η εργασία δηλώνει τις συνθήκες του· όταν η εργασία δεν τις δηλώνει, ο ισχυρισμός δεν χρησιμοποιείται. Οι κανόνες ασφάλειας της μορφής ισχύουν επομένως εξίσου για κάθε προφίλ. Ένα πλήρες παράδειγμα οδοντιατρείου με το προφίλ General και το δικό του προφίλ βρίσκεται στο αποθετήριο: general-dental.json. Σχήμα ενός προφίλ: profile.schema.json.

Προτιμάτε να μην γράψετε το αρχείο με το χέρι; Η υπηρεσία SOQVER ετοιμάζει μια πρόταση από τον ιστότοπό σας, εσείς επιβεβαιώνετε τα γεγονότα και δημοσιεύετε την πηγή μαζί μας ή την κατεβάζετε για τον δικό σας τομέα: ετοιμάστε μια πηγή.

5. Διαβάστε δημοσιευμένες πηγές μέσω του API

Η διεπαφή είναι μόνο για ανάγνωση και δεν απαιτεί λογαριασμό ούτε κλειδί.

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

Η πρώτη διεύθυνση επιστρέφει τον κατάλογο των πηγών που δημοσίευσε ή επιβεβαίωσε μια εταιρεία. Η δεύτερη αξιολογεί τους ισχυρισμούς μίας πηγής για την εργασία σας και επιστρέφει usable και reasons για καθέναν. Κάθε πηγή είναι επίσης σελίδα για ανθρώπους (/s/<slug>/), αρχείο /s/<slug>/so4ag.json και μορφή JSON-LD /s/<slug>/facts.jsonld.

6. Συνδέστε έναν πράκτορα μέσω MCP

Ο διακομιστής MCP είναι μόνο για ανάγνωση, δεν απαιτεί λογαριασμό και χρησιμοποιεί τη μεταφορά Streamable HTTP. Στο επίσημο MCP Registry καταχωρίζεται ως com.soqver/so4ag.

https://soqver.com/mcp
ΕργαλείοΤι κάνει
list_sourcesΠαραθέτει τις δημοσιευμένες πηγές.
get_sourceΕπιστρέφει ολόκληρη την πηγή μίας επιχείρησης.
get_claimsΑξιολογεί τους ισχυρισμούς μιας πηγής για δεδομένη ιδιότητα και συνθήκες.
check_claimΔηλώνει αν ένας ισχυρισμός μπορεί να χρησιμοποιηθεί τώρα και γιατί όχι.

Σε έναν πελάτη που υποστηρίζει απομακρυσμένους διακομιστές MCP, εισαγάγετε την παραπάνω διεύθυνση. Μπορείτε επίσης να ελέγξετε την απάντηση του διακομιστή από τη γραμμή εντολών:

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. Γράψτε τον δικό σας αναγνώστη

Η σουίτα συμμόρφωσης είναι απλό JSON και δεν χρειάζεται κανέναν από τον κώδικά μας. Περιέχει δύο έγκυρες πηγές σε τρεις μορφές, τις αναμενόμενες συνόψεις των ισχυρισμών, 45 περιπτώσεις αξιολόγησης, 31 περιπτώσεις επικύρωσης, 10 περιπτώσεις ολόκληρης πηγής και 25 διανύσματα της κανονικής μορφής (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

Το πότε ένας αναγνώστης ή ένας επικυρωτής περνά τη σουίτα περιγράφεται στην περιγραφή της σουίτας συμμόρφωσης. Ο αναγνώστης Python γράφτηκε ανεξάρτητα από τον κώδικα αναφοράς και περνά την ίδια σουίτα· μπορείτε να τον χρησιμοποιήσετε ως πρότυπο.

Πού θα βρείτε το έργο

ΤόποςΣε τι χρησιμεύει
GitHub: soqvercom/so4agΚώδικας, προδιαγραφή, σουίτα συμμόρφωσης και εκδόσεις. Εδώ αναπτύσσεται η μορφή.
GitHub DiscussionsΟ χώρος της κοινότητας: ερωτήσεις, προτάσεις και εμπειρία με τη μορφή. Απαντάμε εδώ.
GitHub IssuesΣφάλματα στην προδιαγραφή και στον κώδικα, περιπτώσεις που η μορφή δεν μπορεί να εκφράσει.
PyPI: so4agΤο πακέτο Python: pip install so4ag
ΕκδόσειςΤο πακέτο JavaScript και τα αρχεία κάθε έκδοσης: npm install github:soqvercom/so4ag
Zenodo (DOI)Μόνιμος σύνδεσμος προς τις εκδόσεις για παραπομπή σε εργασίες και τεκμηρίωση.
MCP RegistryΗ καταχώριση του διακομιστή MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGΣύντομες ερωτήσεις και συνομιλία με άλλους που δοκιμάζουν τη μορφή.
DEV: @soqvercomΤεχνικά άρθρα και κείμενα οδηγιών για τη μορφή.
daily.dev: @soqverΣύνδεσμοι προς νέα άρθρα για προγραμματιστές.
X · YouTubeΝέα για τη μορφή και σύντομες επιδείξεις.

Σχόλια και σφάλματα

Βρήκατε ένα γεγονός που η μορφή δεν μπορεί να εκφράσει, ή δύο αναγνώστες που απαντούν διαφορετικά; Καταγράψτε το ως ζήτημα στο GitHub. Παρακαλούμε αναφέρετε μια ευπάθεια με μήνυμα ηλεκτρονικού ταχυδρομείου στη διεύθυνση [email protected].