# The microon specification

> Open specification · v0.1 draft · 2026-07 · living document
> Canonical (HTML): https://microon.org/spec/ · This file: https://microon.org/spec/index.md


## Abstract

microon is an open specification for recording knowledge about physical systems — buildings, factories, energy, infrastructure — and any domain where facts are only meaningful within a time window, a chain of trust, and a defined kind.

The unit of knowledge is the **quad**: subject, predicate, object, and **context**. Context is not metadata attached to a fact; it is part of the fact.

microon is designed to be read and written by AI agents as well as people: whether a fact is current, who asserted it, and who may change it are queries against the same store, and the specification itself is published in machine-readable form.

## Status of this document

This is **version 0.1, a living draft**, stewarded by [PDAT](https://pdat.cz). The five principles (§ The five principles) are normative and stable; their change is not expected. All other sections are non-normative and will evolve with implementations and domains.

Canonical URL: `https://microon.org/spec/`. Machine-readable copies: [`/spec/index.md`](/spec/index.md) (this document as plain Markdown), [`/llms.txt`](/llms.txt) (site index for language models).

## Conformance

A system is a **microon system** if and only if it satisfies principles P1–P5. There is no conformance suite, no registration, and no committee. The key words MUST and MUST NOT are to be interpreted as in RFC 2119. Everything outside the five principles is implementation-defined; the Conventions section documents proven choices without requiring them.

## The quad

```
(subject, predicate, object, context)
```

| Element | What it is | Example |
|---|---|---|
| subject | the thing being described | `sensor-fcu01-st01` |
| predicate | the property or relationship | `currentValue` |
| object | the value, or another thing | `22.5` |
| context | the fact’s conditions of truth — layer, time window, origin | see below |

Context is structured. It holds the dimensions under which the triple is true:

```
sensor-fcu01-st01  currentValue  22.5
  context:
    layer:      state                    (what kind of fact — P4)
    valid from: 2026-04-05T14:30:00Z     (when it became true — P2)
    valid to:   —                        (still true)
    origin:     pda-fieldbus             (who asserts it — P3)
```

Implementations may add further context elements on the same footing — confidence (“measured” vs. “inferred”), or an access element such as visibility or restriction. The exact encoding — columns, a structured record, a string — is an implementation choice. That every fact carries its context is not.

**Context is not topic.** What a fact concerns — a building, a machine, an organization — does not belong in context. Express it with ordinary predicates (`locatedIn`, `partOf`), where it stays queryable like any other knowledge:

```
sensor-fcu01-st01  locatedIn  bld-jn1420     (a fact like any other)
```

## The five principles

### P1 — A fact without context does not exist

Every fact is recorded together with the context that makes it true: what kind of fact it is (its layer), when it holds (its time window), and who asserts it (its origin). A bare triple is an incomplete fact. There is no “global truth” shortcut — even a fact meant to hold always and on everyone’s word states that explicitly.

The principles that follow are the dimensions of context: P2 is its time, P3 its origin, P4 its layer.

### P2 — Truth has duration

Every fact has a time window: valid **from** a moment, valid **until** a moment (or still open). Facts are never updated in place and never deleted:

- **Assert** — record a new fact, open-ended.
- **Retract** — close a fact’s time window. The fact remains: “this was true from X until Y.”
- **Replace** — close the old fact and assert the new one atomically, so the two windows meet edge to edge.

A microon store can therefore answer “what is true now?” and “what was true at T?” from the same data, with no extra machinery.

### P3 — Every fact has an origin

Every fact records who or what asserted it — a device, a person, a service, an AI agent. Origin is mandatory: an implementation must reject a fact that arrives without one, and must not let callers impersonate an origin they cannot prove. Confidence (“measured” vs. “inferred” vs. “declared”) is an optional refinement on the same axis.

### P4 — Knowledge has layers

Every fact belongs to exactly one of five layers. The layers are part of the methodology itself — the same five in every domain:

| Layer | Holds | Changes | Example |
|---|---|---|---|
| `schema` | definitions — what kinds of things and properties exist | rarely | `fcu · type · device-type` |
| `structure` | topology — what is where, what connects to what | monthly | `fcu-01 · locatedIn · room-301` |
| `state` | live values — readings, positions, setpoints | seconds | `sensor-7 · currentValue · 22.5` |
| `meta` | quality and lineage — calibration, firmware, install dates | occasionally | `dev-fcu01 · calibrated · 2026-03-01` |
| `authz` | permissions — who may read or write which facts | on policy change | `role-operator · mayWrite · state` |

Consequences: (1) **authorization is knowledge** — permissions are ordinary facts in the `authz` layer, with time windows and origins like any other, so historical access questions are queries; (2) layers give every consumer a stable expectation — an agent reading `structure` is reading topology, in any microon system, in any domain.

### P5 — Simplicity is a commitment

microon excludes: inference engines, reification, blank nodes, description logic, and mandatory serialization formats. Acceptance test for any extension: the model must remain explainable in one page and implementable in a weekend. A single table of quads in SQLite is a legitimate microon store.

## Operations

The minimal operation set every microon system offers, in whatever protocol suits it:

- **assert(quad)** — record a fact.
- **retract(quad)** — close a fact’s time window.
- **replace(old, new)** — atomic retract + assert; the canonical “update”.
- **query(pattern, at?)** — find facts by any combination of subject, predicate, object, context; optionally as of a moment in time. Default: facts true now.
- **subscribe(pattern)** — be notified when matching facts are asserted or retracted.

## Conventions

> Everything below is **non-normative**. It is how we build microon systems ourselves. Take what fits your domain; replace what does not. A system that ignores every convention here and holds the five principles is fully microon.

### Grouping and isolation

What a fact concerns is knowledge, so it lives in predicates: `locatedIn`, `partOf`, `serves`. Two proven ways to organize stores around that:

- **One shared store** — facts about many buildings or organizations side by side, grouped and filtered through their `structure` predicates.
- **One store per owner or site** — a separate store instance per building or organization. Isolation is physical — separate database, separate access — which is often exactly what an owner wants. Which store you are talking to tells you whose knowledge you are reading.

### Example: a building domain

A domain is a small curated vocabulary: entity types plus predicates per layer, published as a versioned document. Identifiers carry a type prefix so quads read without lookups (`bld-` building, `spc-` space, `dev-` device, `usr-` person, `agt-` AI agent) — a convention, not a rule. The example below shows all five layers at work; context is abbreviated to `[layer · origin]`, time windows omitted:

```
-- schema: definitions, asserted once by the domain author
fcu               type          device-type        [schema · org-pdat]
supplyTemp        type          property           [schema · org-pdat]
supplyTemp        unit          "°C"               [schema · org-pdat]

-- structure: topology, changes when someone rebuilds or rewires
spc-room301       partOf        bld-jn1420         [structure · usr-tom]
dev-fcu01         type          fcu                [structure · usr-tom]
dev-fcu01         installedIn   spc-room301        [structure · usr-tom]
dev-fcu01         hasSensor     sensor-fcu01-st01  [structure · usr-tom]
sensor-fcu01-st01 measures      supplyTemp         [structure · usr-tom]

-- state: current values, changes every cycle
sensor-fcu01-st01 currentValue  22.5               [state · pda-fieldbus]
spc-room301       setpoint      22.0               [state · usr-tom]

-- meta: quality of the equipment and its facts
dev-fcu01         calibrated    2026-03-01         [meta · svc-maintenance]

-- authz: permissions, themselves facts
agt-edgar         mayRead       state              [authz · usr-tom]
agt-edgar         mayWrite      state/setpoint     [authz · usr-tom]
```

Read bottom-up, the last two lines are the point of the whole model: the AI agent `agt-edgar` may adjust setpoints because `usr-tom` said so — a fact with an origin and a time window, revocable by closing it, queryable like everything else.

**The time dimension.** Every fact above carries its time window; a value change is a `replace` — the old fact closes at the instant the new one opens, and history accumulates by itself:

```
sensor-fcu01-st01 currentValue 22.1 [state · pda-fieldbus · 14:29:00 → 14:30:00]   closed
sensor-fcu01-st01 currentValue 22.5 [state · pda-fieldbus · 14:30:00 → —]          current
```

“What was the supply temperature at 14:29:30?” is answered by the first row — same table, no extra machinery (P2).

**External references.** High-frequency streams, documents, and records in other databases are not copied into the store — they are referenced by URI-valued predicates, so the knowledge of *where the data lives* is itself a quad:

```
sensor-fcu01-st01 hasStream    nats://bld-jn1420/stream/supplytemp   [structure · org-pdat]
dev-fcu01         hasDocument  s3://docs/fcu01-manual.pdf            [meta · usr-tom]
bld-jn1420        hasSource    oltp://energy-billing/meters          [structure · org-pdat]
```

microon holds the interpreted knowledge (current value, what measures what, who may do what); raw 1000-samples-per-second streams stay in the stream store, manuals stay in the blob store, ledgers stay in the OLTP database — each one quad away.

### Storage sketch

One table is enough. Context is a single flexible value, mirroring the quad itself:

```sql
CREATE TABLE quads (
    id        TEXT PRIMARY KEY,   -- sortable unique id (e.g. ULID)
    subject   TEXT NOT NULL,
    predicate TEXT NOT NULL,
    object    TEXT NOT NULL,
    context   TEXT NOT NULL       -- structured value, e.g. JSON:
    -- {"layer":"state",
    --  "validfrom":"2026-04-05T14:30:00Z", "validto":null,
    --  "origin":"pda-fieldbus",
    --  ...any further elements: confidence, visibility, ...}
);
```

The principles constrain what context must *contain* (layer, time window, origin — P2–P4), not how it is stored. New context elements are added without schema change. Implementations commonly promote the elements they query on — `layer`, `validfrom`/`validto`, `origin` — to indexed columns; that is an optimization, equally conformant. Append-only discipline (P2) can be enforced with triggers; current facts are those with an open `validto`.

## What microon is not

- **Not RDF.** No blank nodes, no reification, no OWL reasoning. Where RDF needs named graphs plus PROV-O plus custom vocabularies to say *who measured what, where, when* — microon says it in one quad.
- **Not a graph database.** Quads are flat facts with context, not a property graph optimized for traversal.
- **Not a time-series database.** microon stores interpreted knowledge with history, not high-frequency raw streams. Point a `hasStream` reference at those.
- **Not a rules engine.** Quads are declarative facts. Logic — control loops, schedules, inference — lives in consumers, not in the ontology.

## Implementations

Two independent implementations exist, built by different teams on different stacks — which is the point of a principles-first methodology:

- **pda-lore** (PDAT) — Go, pure-Go SQLite, NATS transport. One store instance per scope; bi-temporal quads with mandatory verified origin; published domain vocabularies for buildings, schools, accounting, inventory, and organizations.
- **WHW MicroOn Store** — PostgreSQL, append-only quad table with graph-based authorization evaluated from `authz` facts.

Neither is “the” microon. Both hold the five principles.

## Planned work

Domain vocabulary pages, a comparison cookbook (the same scenario in RDF and microon), and machine-readable domain definitions at stable URLs. Feedback, questions, and reports of independent implementations are welcome.