bra0 / Docs / Reference / KS Snapshot Format
Reference

Knowledge Space Snapshot Format

How a complete, self-describing Knowledge Space — a TBox, a set of SHACL shapes, an ABox, and a battery of competency queries — assembles into a single Turtle file that any RDF 1.1 + SPARQL 1.1 + SHACL stack can ingest without out-of-band coordination. Comment un Knowledge Space complet et auto-descriptif — un TBox, un jeu de shapes SHACL, un ABox et une batterie de requêtes de compétence — s'assemble en un seul fichier Turtle qu'une pile RDF 1.1 + SPARQL 1.1 + SHACL peut ingérer sans coordination hors-bande.

WORKING DRAFT v0.1.5 — an evolving specification. Like the rest of the bra0 estate, this document is under active development and refined as the doctrine matures; it is not yet promoted to the equivalent of an IETF Proposed Standard. Substantive feedback is solicited. v0.1.5 — spécification évolutive. Comme le reste de l'estate bra0, ce document est en développement actif et affiné à mesure que la doctrine mûrit ; il n'est pas encore promu à l'équivalent d'un IETF Proposed Standard. Les retours de fond sont sollicités.
In plain terms

A Knowledge Space is a small, self-contained knowledge database — its schema, its validation rules, its data, and a set of test queries — that ships as one plain-text file. You can email it, commit it to git, or drop it into any RDF tool and it works, with nothing else to install and no configuration to wire up. This page is the spec for that file: what goes inside it, and how a tool checks it is well-formed. If you have ever shipped a Docker image or handed someone a single-file SQLite database, the intent is the same — one artefact, zero out-of-band setup. Un Knowledge Space est une petite base de connaissance autonome — son schéma, ses règles de validation, ses données et un jeu de requêtes de test — livrée sous forme d'un seul fichier texte. Vous pouvez l'envoyer par mail, le commiter dans git, ou l'ouvrir dans n'importe quel outil RDF : ça marche, sans rien à installer ni à configurer. Cette page est la spécification de ce fichier : ce qu'il contient, et comment un outil vérifie qu'il est bien formé. Si vous avez déjà livré une image Docker ou passé une base SQLite en un seul fichier, l'intention est la même — un artefact, zéro configuration externe.

This is the Reference surface for the snapshot format. It specifies only the additive profile over pre-existing W3C and community specifications: it introduces no new syntax, no new query language, and no new validation engine — it specifies how the existing pieces co-locate and what minimal metadata a harness needs to validate, version and promote a snapshot. The doctrine a Knowledge Space carries (eight facets, eleven entity types, stratification, grounding) lives on the companion concept page and is cross-referenced here, never restated. Ceci est la surface de référence du format d'instantané. Elle spécifie uniquement le profil additif au-dessus de spécifications W3C et communautaires préexistantes : aucune nouvelle syntaxe, aucun nouveau langage de requête, aucun nouveau moteur de validation — elle spécifie comment les pièces existantes se co-localisent et quelles métadonnées minimales un harnais requiert pour valider, versionner et promouvoir un instantané. La doctrine qu'un Knowledge Space porte (huit facettes, onze types d'entité, stratification, ancrage) vit sur la page de concept compagne et est renvoyée ici, jamais répétée.

1Knowledge Space vs snapshotKnowledge Space contre instantané

Why two words

Why two names for what looks like one thing? Because one keeps evolving and the other is frozen. Think of a git repository (the living project, always moving) versus a specific release tag or tarball (a fixed point you can hand to someone). The Knowledge Space is the repo; the snapshot is the release. Everything below specifies the release artefact. Pourquoi deux noms pour ce qui semble être une seule chose ? Parce que l'un évolue sans cesse et l'autre est figé. Pensez à un dépôt git (le projet vivant, qui bouge en permanence) contre un tag de version ou une archive précise (un point fixe qu'on peut remettre à quelqu'un). Le Knowledge Space est le dépôt ; l'instantané est la version publiée. Tout ce qui suit spécifie l'artefact de version.

The format distinguishes consistently between two referents: Le format distingue de manière constante deux référents :

Over the underlying W3C stack, the format adds exactly eight things:Au-dessus de la pile W3C sous-jacente, le format ajoute exactement huit choses :

2Snapshot structureStructure de l'instantané

The idea

The whole point is no assembly required. Instead of a schema file here, a data file there, and a README explaining how to wire them together, everything lives in one .ttl, split into labelled sections — much like the parts of a single HTML document (head, body, scripts) rather than a folder of loose assets. A consumer opens one file and has the complete picture: the vocabulary, the rules, the data, and the queries that prove the data answers real questions. Tout l'intérêt est qu'il n'y a rien à assembler. Au lieu d'un fichier de schéma ici, un fichier de données là, et un README expliquant comment les relier, tout tient dans un seul .ttl, découpé en sections étiquetées — un peu comme les parties d'un document HTML unique (head, body, scripts) plutôt qu'un dossier de fichiers épars. Le lecteur ouvre un fichier et a l'image complète : le vocabulaire, les règles, les données, et les requêtes qui prouvent que les données répondent à de vraies questions.

A snapshot MUST be a single Turtle 1.1 file with a .ttl extension and UTF-8 encoding. It MUST parse to a valid RDF graph and MUST round-trip (re-parsing yields an identical triple count). It declares its sections via bra0t:hasSection:Un instantané DOIT être un seul fichier Turtle 1.1 avec extension .ttl et encodage UTF-8. Il DOIT se parser en un graphe RDF valide et DOIT faire un aller-retour stable (le re-parse donne un nombre de triplets identique). Il déclare ses sections via bra0t:hasSection :

Section markerContentCardinality
bra0t:MetadataSnapshot-level metadata (root resource).Métadonnées au niveau de l'instantané (ressource racine).exactly 1
bra0t:TBoxClass/property declarations, OWL axioms.Déclarations de classes/propriétés, axiomes OWL.exactly 1
bra0t:ShapesSHACL (and optionally ShEx) constraints.Contraintes SHACL (et optionnellement ShEx).exactly 1
bra0t:ABox | bra0t:SampleABoxInstance triples.Triplets d'instances.exactly 1 of the two
bra0t:QueriesEmbedded competency queries.Requêtes de compétence embarquées.0 or 1

The single root resource (type bra0t:KnowledgeSpace, or its subclass bra0t:Template for reusable archetypes) MUST carry rdfs:label, dct:creator, dct:created, dct:license (as an IRI, never a plain string), owl:versionInfo (SemVer 2.0.0), bra0t:snapshotFormat, bra0t:lifecycleStage, one bra0t:hasSection per section, and the declared triple counts (bra0t:tboxTripleCount, …shapesTripleCount, …aboxTripleCount, …queryCount). Each embedded competency query is a bra0t:CompetencyQuery with a unique bra0t:queryId, its bra0t:sparql text, and an rdfs:label; the harness MUST execute every query against the snapshot's own merged graph without error.La ressource racine unique (type bra0t:KnowledgeSpace, ou sa sous-classe bra0t:Template pour les archétypes réutilisables) DOIT porter rdfs:label, dct:creator, dct:created, dct:license (comme IRI, jamais une chaîne simple), owl:versionInfo (SemVer 2.0.0), bra0t:snapshotFormat, bra0t:lifecycleStage, un bra0t:hasSection par section, et les comptes de triplets déclarés. Chaque requête de compétence embarquée est un bra0t:CompetencyQuery avec un bra0t:queryId unique, son texte bra0t:sparql et un rdfs:label ; le harnais DOIT exécuter chaque requête sur le graphe fusionné de l'instantané sans erreur.

3The bra0t: vocabularyLe vocabulaire bra0t:

What it is for

To find the sections and run the bundled queries, a tool needs a handful of agreed-upon labels — and nothing more. bra0t: is that small glue vocabulary (about fifteen terms). It does not model your domain; it only says « here is the schema section », « here is a test query », « this file is at maturity stage Audited ». It is kept deliberately tiny so there is almost nothing new to learn on top of the standards you already know. Pour trouver les sections et exécuter les requêtes embarquées, un outil a besoin d'une poignée d'étiquettes convenues — rien de plus. bra0t: est ce petit vocabulaire de liaison (une quinzaine de termes). Il ne modélise pas votre domaine ; il dit seulement « voici la section schéma », « voici une requête de test », « ce fichier est au stade Audited ». Il est gardé volontairement minuscule pour qu'il n'y ait presque rien de nouveau à apprendre au-dessus des standards que vous connaissez déjà.

Defined in bra0_meta/ontologies/template/template.ttl, resolving at https://schema.bra0.org/template# once whitelisted (the template label is a legacy artefact preserved across v0.1.x). Every term carries an rdfs:seeAlso back to its clause in this specification.Défini dans bra0_meta/ontologies/template/template.ttl, résolvant à https://schema.bra0.org/template# une fois inscrit à la liste blanche (le label template est un artefact hérité conservé sur v0.1.x). Chaque terme porte un rdfs:seeAlso vers sa clause dans cette spécification.

The vocabulary is licensed CC BY-SA 4.0; the spec text itself is licensed CC BY 4.0.Le vocabulaire est sous licence CC BY-SA 4.0 ; le texte de la spécification est sous licence CC BY 4.0.

4Conformance gates and levelsPortes et niveaux de conformité

In short

Conformance is just a test suite for the file. Four checks answer four practical questions: does it parse? does its manifest match? do its own validation rules pass? do its bundled queries still return what they used to? The levels below (Bronze → Platinum) tell you how much of that suite a file has passed — think of a CI badge that climbs from « it compiles » to « production-ready ». La conformité n'est qu'une suite de tests sur le fichier. Quatre contrôles répondent à quatre questions concrètes : est-ce que ça se parse ? est-ce que son manifeste correspond ? est-ce que ses propres règles de validation passent ? est-ce que ses requêtes embarquées renvoient toujours ce qu'elles renvoyaient ? Les niveaux ci-dessous (Bronze → Platinum) disent jusqu'où un fichier a passé cette suite — comme un badge d'intégration continue qui monte de « ça compile » à « prêt pour la production ».

A conformant implementation MUST pass four gates. A snapshot that fails any gate MUST NOT advance its lifecycle stage.Une implémentation conforme DOIT passer quatre portes. Un instantané qui échoue à une porte NE DOIT PAS faire avancer son étape de cycle de vie.

Levels stack — each inherits the requirements of the levels below:Les niveaux s'empilent — chacun hérite des exigences des niveaux inférieurs :

LevelGatesLifecycle floorPublication eligible
Bronze1–2DraftNo
Silver1–3DogfoodedNo
Gold1–4 + strata + containment + 6-dim auditAuditedYes (non-confidential license)
PlatinumGold + open-question closure ≤3 + external witnessPublishedYes

Conformance and quality are distinct axes. The conformance level (above) is machine-checkable, the output of the harness. The quality tier is human-judged, indexed on the Keet six-dimension audit and documented on the buyer landing. Quality-Gold (6/6 Keet dimensions) is a prerequisite for Conformance-Gold, but the two are different objects of judgement — the conformance verdict is mechanical, the quality verdict interpretive. At v0.2 the conformance levels rename to L1 / L2 / L3 / L4 to retire the colour-name collision; the quality tiers keep the Bronze/Silver/Gold framing.Conformité et qualité sont deux axes distincts. Le niveau de conformité (ci-dessus) est vérifiable par machine, sortie du harnais. Le palier de qualité est jugé par un humain, indexé sur l'audit Keet à six dimensions et documenté sur la page acheteur. Qualité-Gold (6/6 dimensions Keet) est un prérequis pour Conformité-Gold, mais les deux sont des objets de jugement différents — le verdict de conformité est mécanique, le verdict de qualité interprétatif. En v0.2 les niveaux de conformité se renomment L1 / L2 / L3 / L4 pour retirer la collision de noms de couleurs ; les paliers de qualité gardent le cadrage Bronze/Silver/Gold.

5Manifest contractContrat de manifeste

Familiar ground

If you have written a package.json or a lockfile, this will feel familiar. The manifest is a small JSON sidecar that restates the file's key facts — version, triple count, the prefixes it froze — so a build tool can verify them cheaply without re-parsing the whole graph. When the manifest and the file disagree, the build fails fast, exactly like a checksum mismatch. Si vous avez déjà écrit un package.json ou un lockfile, vous serez en terrain connu. Le manifeste est un petit fichier JSON compagnon qui répète les faits clés du fichier — version, nombre de triplets, préfixes figés — pour qu'un outil de build puisse les vérifier à peu de frais, sans re-parser tout le graphe. Quand le manifeste et le fichier divergent, le build échoue immédiatement, exactement comme une somme de contrôle qui ne correspond pas.

A conformant snapshot carries a manifest.json next to the .ttl, validating against the published JSON Schema. It is REQUIRED for Silver and above, OPTIONAL for Bronze.Un instantané conforme porte un manifest.json à côté du .ttl, validant contre le JSON Schema publié. Il est REQUIS pour Silver et au-delà, OPTIONNEL pour Bronze.

{
  "name":              "<string, KS slug>",
  "version":           "<SemVer>",
  "title":             "<string>",
  "description":       "<string>",
  "creator":           "<string>",
  "created":           "<xsd:date>",
  "snapshotFormatADR": "035",
  "snapshot":          "<filename>.ttl",
  "tripleCount":       <integer>,
  "frozenPrefixes":    { "<prefix>": "<IRI>", … },
  "lifecycleStage":    "DRAFT" | "DOGFOODED" | "AUDITED" | "PUBLISHED",
  "validationCommand": "<command line>",
  "buildCommand":      "<command line>"
}

6Lifecycle statesÉtats de cycle de vie

Like release tags

These are release-maturity stages, much like npm's draft → beta → latest tags. A snapshot climbs from Draft (work in progress) to Published (public, and vouched for by someone other than the author). The rule is simple: you never move a file up a stage until it has passed every check that stage requires. Ce sont des stades de maturité, un peu comme les tags npm draft → beta → latest. Un instantané grimpe de Draft (travail en cours) à Published (public, et attesté par quelqu'un d'autre que l'auteur). La règle est simple : on ne fait jamais monter un fichier d'un stade tant qu'il n'a pas passé tous les contrôles que ce stade exige. 

Draft ─▶ Dogfooded ─▶ Audited ─▶ Published
                                     │
                                     ▼
                          (confidential snapshots
                           stop at Audited)
StatePromotion condition
DraftGates 1–2 pass (SHACL not strict, to allow rapid iteration). Bronze.Portes 1–2 passées (SHACL non strict, pour itérer vite). Bronze.
DogfoodedGates 1–3 pass; at least one consumer has imported the snapshot and exercised its competency queries. Silver.Portes 1–3 passées ; au moins un consommateur a importé l'instantané et exercé ses requêtes. Silver.
AuditedGates 1–4 pass; strata, containment and six-dimension audit clauses pass; Keet 6-dim audit PASS or PASS-WITH-WARNINGS on every dimension. Gold.Portes 1–4 passées ; clauses de strates, de confinement et d'audit six dimensions passées ; audit Keet 6-dim PASS ou PASS-WITH-WARNINGS sur chaque dimension. Gold.
PublishedRoot resource exposed at a publicly resolvable IRI under a non-confidential license; ≥1 external implementer witness. Confidential snapshots may reach Audited but MUST NOT be Published. Platinum.Ressource racine exposée à un IRI publiquement résolvable sous licence non confidentielle ; ≥1 témoin implémenteur externe. Les instantanés confidentiels peuvent atteindre Audited mais NE DOIVENT PAS être Published. Platinum.

Demotion (e.g. Audited → Dogfooded) MUST be recorded with prov:wasInvalidatedBy and a rationale. The across-snapshots continuity of a KS — multi-session authoring, batched enrichment, recursive dogfood proof, sealing — is the responsibility of the KSLM capability (cap:KSLM), which runs the promotion sequence under a ratchet / non-regression / non-interop-rupture master invariant. A snapshot's Governance facet MAY declare a validation authority (self / community / authority / regulator), declarative and versioned in the PROV-O envelope.La rétrogradation (ex. Audited → Dogfooded) DOIT être enregistrée avec prov:wasInvalidatedBy et une justification. La continuité d'un KS à travers les instantanés — rédaction multi-sessions, enrichissement par lots, preuve récursive, scellement — relève de la capacité KSLM (cap:KSLM), qui déroule la séquence de promotion sous un invariant maître de rochet / non-régression / non-rupture d'interopérabilité. La facette Gouvernance d'un instantané PEUT déclarer une autorité de validation (self / community / authority / regulator), déclarative et versionnée dans l'enveloppe PROV-O.

7Folder layout and versioningDisposition de dossier et versionnage

Convention over configuration

A predictable folder, so humans and tools always know where to look: the snapshot, its manifest, its audit notes, its query fingerprints, a README. Versioning follows plain SemVer — the same PATCH / MINOR / MAJOR reflexes you already use for a library, applied to knowledge instead of code. Un dossier prévisible, pour que les humains et les outils sachent toujours où regarder : l'instantané, son manifeste, ses notes d'audit, les empreintes de ses requêtes, un README. Le versionnage suit simplement SemVer — les mêmes réflexes PATCH / MINOR / MAJOR que pour une bibliothèque, appliqués à la connaissance plutôt qu'au code. 

ks/<name>/
  <name>-snapshot.ttl          ← the snapshot itself
  <name>-bfo-alignment.ttl     ← BFO 2020 alignment (if grounding claimed)
  manifest.json                ← conformance metadata
  maturity.md                  ← Keet 6-dim audit verdicts
  baseline/
    cq-results.json            ← Gate 4 fingerprints
  README.md                    ← entry point & usage

Snapshots carry a SemVer 2.0.0 version on the root resource via owl:versionInfo. PATCH = fingerprint-stable refresh; MINOR = new triples / CQs / sections without invalidating existing fingerprints; MAJOR = breaking change, requiring a Lens and a fresh baseline. The spec itself is versioned independently of any snapshot.Les instantanés portent une version SemVer 2.0.0 sur la ressource racine via owl:versionInfo. PATCH = rafraîchissement stable en empreinte ; MINOR = nouveaux triplets / requêtes / sections sans invalider les empreintes existantes ; MAJOR = changement cassant, exigeant une Lens et une ligne de base neuve. La spécification est versionnée indépendamment de tout instantané.

8Scope and closurePortée et clôture

Where the spec stops

Knowing what a spec does not do is as useful as knowing what it does. v0.1 deliberately stops at the single file. The harder distributed-systems concerns — transport, encryption, merging many files — are named here on purpose, so you know they are handled elsewhere, not forgotten. Small, sharp, and honest about its edges. Savoir ce qu'une spec ne fait pas est aussi utile que savoir ce qu'elle fait. La v0.1 s'arrête volontairement au fichier unique. Les problèmes plus durs de systèmes distribués — transport, chiffrement, fusion de plusieurs fichiers — sont nommés ici exprès, pour que vous sachiez qu'ils sont traités ailleurs, pas oubliés. Petite, précise, et honnête sur ses limites.

The format specifies the content and structure of the single Turtle file, its manifest, the conformance gates and levels, the lifecycle states, the enclosing folder layout, and the doctrinal absorption clauses. Explicitly out of scope at v0.1 (an orthogonal layer, not implied by any clause): transport, access control, encryption, multi-file packaging / fork-merge / CRDT semantics (deferred to the KS Package Format), marketplace discovery beyond a single DCAT envelope, snapshot signing and DID-based attestation, embedded SPARQL UPDATE, and runtime enforcement of ODRL / RML mappings. A future revision may normatively bind some of these layers; doing so requires a new spec version.Le format spécifie le contenu et la structure du fichier Turtle unique, son manifeste, les portes et niveaux de conformité, les états de cycle de vie, la disposition du dossier englobant, et les clauses d'absorption doctrinale. Explicitement hors portée en v0.1 (couche orthogonale, non impliquée par aucune clause) : transport, contrôle d'accès, chiffrement, empaquetage multi-fichiers / fork-merge / sémantique CRDT (reporté au format de paquet KS), découverte de marché au-delà d'une enveloppe DCAT unique, signature d'instantané et attestation par DID, SPARQL UPDATE embarqué, et application à l'exécution des mappings ODRL / RML. Une révision future pourra lier normativement certaines de ces couches ; cela exige une nouvelle version de la spécification.

9Open questions (v0.1 → v0.2)Questions ouvertes (v0.1 → v0.2)

Still in motion

This is a Working Draft, so a few things are still being decided in the open rather than settled behind closed doors. Each item below is a real question we are weighing for the next version — listed here so you can see the direction of travel and push back before it hardens. C'est un Working Draft, donc quelques points se décident encore à ciel ouvert plutôt qu'à huis clos. Chaque élément ci-dessous est une vraie question que nous pesons pour la prochaine version — listée ici pour que vous voyiez la direction prise et puissiez réagir avant qu'elle ne se fige.

The doctrine a snapshot carries (cross-referenced, not restated) This page specifies the format. The doctrine the format binds — the eight facets (Vocabulary, Validation, Queries, Data, Provenance, Mapping, Governance, Narrative), the eleven entity types and their recovery discipline, the tiered strata mandate, closed-namespace containment, BFO 2020 grounding via a separate alignment file, the epistemic admonitions (PROVEN / UNVERIFIED / GAP), the six-dimension quality audit, and the three constitutive properties (Evolvable, Modular, Reliable) — is defined on the Knowledge Space concept page, which this specification projects into snapshot-binding clauses. The two surfaces are kept aligned by rule; neither duplicates the other. Cette page spécifie le format. La doctrine qu'il lie — les huit facettes (Vocabulaire, Validation, Requêtes, Données, Provenance, Mapping, Gouvernance, Récit), les onze types d'entité et leur discipline de récupération, le mandat de strates, le confinement de namespace, l'ancrage BFO 2020 via un fichier d'alignement séparé, les admonitions épistémiques (PROVEN / UNVERIFIED / GAP), l'audit qualité six dimensions, et les trois propriétés constitutives (Évolutif, Modulaire, Fiable) — est définie sur la page de concept Knowledge Space, que cette spécification projette en clauses contraignantes. Les deux surfaces sont maintenues alignées par règle ; aucune ne duplique l'autre.

10ReferencesRéférences

Authoritative IRI of this specification: https://schema.bra0.org/template/spec/v0.1 (IRI resolution activates once whitelisted on the terminology server). Editors: Sacha Roger. Spec text under CC BY 4.0; companion vocabulary under CC BY-SA 4.0.IRI faisant autorité pour cette spécification : https://schema.bra0.org/template/spec/v0.1 (la résolution de l'IRI s'active une fois inscrite à la liste blanche du serveur de terminologies). Éditeur : Sacha Roger. Texte sous CC BY 4.0 ; vocabulaire compagnon sous CC BY-SA 4.0.

Related bra0 surfaces

Where to go next, and why:Où aller ensuite, et pourquoi :

Underlying specifications (additive profile)

The format binds back to pre-existing standards. Core binding stack:Le format se rattache à des standards préexistants. Pile de liaison principale :

Decision records (ADR)

← Previous SHACL Shapes Next → Ontology Catalog