KG-SSOT manual¶
English | Português (Brasil)
KG-SSOT is a verifiable knowledge graph in a plain text file. Each claim can carry its source, the date it was
verified, and what it was verified against. A formal contract decides whether the file is well formed. This manual
covers the .kg.yaml format, the contract, the tools, and how to adopt KG-SSOT in a repository.
This manual describes release 4.45.0 (tag kg-ssot-v4.45.0). The current contract in this release is v4.
The manual is also available in Brazilian Portuguese, in docs/manual/pt-BR/. When the two
differ, the English text wins.
Chapters¶
| # | Chapter | What it covers |
|---|---|---|
| 1 | What it is and who it is for | The problem, the thesis, and who benefits |
| 2 | Concepts | Graph, node, types, status, planes, edges, provenance, verification stamp |
| 3 | Format reference | Every .kg.yaml field, taken from the schema |
| 4 | The contract | MUST vs. SHOULD, error codes, versions, and tags |
| 5 | Tools | kg_validate, kg_conformance, kg_gate, kg_vendor, kg_store, kg_mcp, kg_query, kg_refs, kg_diff, kg_prov_export, kg_migrate, with real output |
| 6 | Adoption and CI | The short path to bring the contract into a repository |
| 7 | Conformance and readers | The case suite and how to write your own reader |
| 8 | Recipes | Common tasks, step by step |
| 9 | Troubleshooting | What each error means and how to fix it |
| 10 | Glossary | The terms used in this manual |
Quick start¶
- Writing a graph? Read chapters 2 and 3, and turn to chapter 9 when the reader fails your file.
- Adopting KG-SSOT in a repository? Start with chapter 6, then move on to
ADOPTING.md. - Writing a reader in another language? Read chapter 7 and
spec/conformance/README.md.
Sources of truth¶
This manual is explanatory, not normative. When it differs from one of these files, the files win:
- the contract:
spec/kg-contract-v4.schema.json(MUST) andspec/kg-contract-v4.should.schema.json(SHOULD); - the suite:
spec/conformance/; - the release surface:
spec/release.json.
Every command output in this manual was pasted from a real run, on Python 3.12 with the versions pinned in
tools/requirements.txt. The tools print human-readable output in English by default,
and in Brazilian Portuguese when you set KG_SSOT_LANG=pt-BR or run under a pt_BR locale. Error codes, exit codes
and JSON keys never change language; only the human text does.