SO4AG는 비즈니스 사실을 위한 개방형 형식입니다. 모든 사실은 의미, 적용 범위, 출처, 유효성을 함께 가집니다. 판독기는 한 가지 질문에 답합니다. 이 사실을 지금 이 작업에 사용할 수 있는가, 사용할 수 없다면 그 이유는 무엇인가.
형식은 무료이며 계정이 필요하지 않습니다. 코드는 Apache-2.0으로, 명세 본문은 CC BY 4.0으로 라이선스됩니다.
GitHub 저장소 · 사양 · JSON Schema · 적합성 스위트 · JSON-LD · 브라우저 검증기 · 동작 현황
Contents: 1. Get the code · 2. Validate a source · 3. Ask about a fact · 4. Publish your own source · 5. API · 6. MCP · 7. Your own reader · Any industry · Where to find the project
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
검증기는 파일 또는 주소를 읽습니다. SO4AG JSON, JSON-LD 형식, JSON-LD가 포함된 HTML 페이지를 이해합니다.
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로 시작합니다. 유효하지 않은 소스이면 파일 내 위치와 함께 오류 목록이 이어집니다. 별도 설치 없이 브라우저 검증기에서도 동일하게 동작합니다.
유효한 소스는 구조가 올바르다는 점만 증명합니다. 사실이 참이라는 의미는 아닙니다.
작업은 어떤 속성을 어떤 조건(범위)에 대해 묻는지 지정합니다. 판독기는 일치하는 모든 주장과 사용 가능 여부, 사용할 수 없을 때의 이유를 반환합니다.
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
지점 조건 없이, 또는 다른 시점에 동일하게 시도해 보십시오(--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 | 게시자가 값을 알 수 없거나 적용되지 않는다고 명시합니다. 알 수 없음은 0이 아닙니다. |
disputed | 해당 주장에 이의가 있습니다. |
no_trust_policy | 작업은 검토된 주장을 요청하지만 누구를 신뢰하는지는 지정하지 않습니다. 누구를 신뢰할지는 주장을 읽는 쪽의 결정입니다. |
attestation_not_authenticated | The source carries an attestation with the name of an issuer you trust, but you have not authenticated it with the issuer. A name written in the source is not a proof. |
conflicting_claims | Two current claims state different values for the same thing. The reader uses neither and never picks a winner silently. |
invalid_source | The source breaks the structure of the format (for example a claim without evidence or an unreadable date). Nothing of it is used. |
unsupported_version | 소스가 판독기가 알지 못하는 형식 버전입니다. 다른 버전의 규칙으로는 읽지 않습니다. |
이유와 규칙의 전체 목록은 사양에 있습니다.
소스는 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"
}
]
}
so4ag.json로 저장하고 검증기로 확인하십시오(2단계)./so4ag.json 위치에 유형 application/json로 제공하십시오.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json"> 태그에 넣으십시오. 변환은 무손실입니다. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until)을 지정하고, 그 시점이 지나기 전에 주장을 확인하거나 변경하십시오. 그 이후 판독기는 해당 주장을 사용하지 않습니다.The format is not tied to an industry. Properties (what a fact means, its type and unit, and which conditions limit it) are set by a profile, and one source may use several profiles together.
| 프로파일 | For whom |
|---|---|
| General | Any business or organisation: operator, places and opening hours, contacts, languages, what it offers and for how much, payment, booking, response and delivery times, cancellation, guarantee, accessibility, licences, availability. 26 properties. |
| Vehicle rental, Retail | What is specific to the industry: deposit, mileage limit, shipping, returns. |
| Your own | Anything else. A profile is a JSON file on your domain; you ask nobody and register nothing. |
Your own profile describes your properties the same way ours do: label, description, value type, units, allowed codes and conditions. The smallest form:
{
"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 and add that address to profiles in your source.namespace + name, that is 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.jsonA reader that does not know your profile still uses the claim when the task states its conditions; when the task does not, the claim is not used. The safety rules of the format therefore hold for every profile alike. A complete example of a dental practice with the General profile and its own profile is in the repository: general-dental.json. Schema of a profile: profile.schema.json.
파일을 직접 작성하지 않으시겠습니까? SOQVER 서비스가 귀사 웹사이트를 바탕으로 제안안을 준비합니다. 사실을 확인하신 뒤 당사와 함께 소스를 게시하거나 자체 도메인용으로 내려받으십시오. 소스 준비
인터페이스는 읽기 전용이며 계정과 키가 필요하지 않습니다.
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이기도 합니다.
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"}'
적합성 스위트는 순수 JSON이며 당사 코드가 전혀 필요하지 않습니다. 세 가지 형태의 유효한 소스 두 개, 클레임의 예상 다이제스트, 평가 사례 45건, 검증 사례 31건, 전체 소스 사례 10건, 정규형 벡터 25개(RFC 8785)를 포함합니다.
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
리더 또는 검증기가 스위트를 통과하는 경우는 적합성 스위트 설명에 기술되어 있습니다. Python 리더는 참조 코드와 독립적으로 작성되었으며 동일한 스위트를 통과하므로, 본보기로 사용하실 수 있습니다.
| Place | What it is for |
|---|---|
| GitHub: soqvercom/so4ag | Code, specification, conformance suite and releases. This is where the format is developed. |
| GitHub Discussions | The place for the community: questions, proposals and experience with the format. We answer here. |
| GitHub Issues | Errors in the specification and the code, cases the format cannot express. |
| PyPI: so4ag | The Python package: pip install so4ag |
| Releases | The JavaScript package and the files of every version: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | A permanent link to the releases for citing in papers and documentation. |
| MCP Registry | The entry of our MCP server: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Quick questions and a chat with others who try the format. |
| DEV: @soqvercom | Technical articles and how-to texts about the format. |
| daily.dev: @soqver | Links to new articles for developers. |
| X · YouTube | News about the format and short demos. |
형식으로 표현할 수 없는 사실을 발견하셨거나, 응답이 서로 다른 리더가 두 개입니까? GitHub 이슈로 작성해 주십시오. 취약점은 이메일 [email protected]으로 신고해 주십시오.