Schema v2.0

The RKF schema defines element types and their attributes. The spec is serialization-independent; examples below use an XML element notation (see the note under Root element). v2.0 reframes the spec as "documents as state machines" grounded in three vector spaces.

Root element

<wity-rkf version="2.0" id="my-document" title="My Reactive Document">
  ...
</wity-rkf>

This XML is notation, not a format you can load

The <wity-rkf> XML format is retired. Nothing reads or writes it any more except rkfToKnowledge(), the one-time upgrade for old documents; parse() rejects it.

This guide keeps the element notation because it is the most compact way to list each element type and its attributes. Read every example as a description of the document model:

In this guide	In the document model (what parse() returns)	In the stored form (<wity-knowledge>)
an element <rkf-var …/>	an object { tag: 'rkf-var', … }	a node of type rkf-var
an attribute init="0.5"	a field init: 0.5	a <data key="init"> of that node
nesting	the parent's list (vars, children, ports, …)	a contains edge

Documents are built with the edit API or as plain objects, and stored with serialize(). See Documents are <wity-knowledge> graphs.

Attribute	Type	Required	Description
version	string	yes	Must be "2.0"
id	string	no	Document identifier
title	string	no	Document title

Document children

The root <wity-rkf> element accepts:

• <rkf-var> -- document-level feature variables
• <rkf-section> -- top-level content sections

Sections

<rkf-section id="intro" label="Introduction" gate="showIntro">
  ...
</rkf-section>

Attribute	Type	Default	Description
id	string	--	Unique section identifier
label	string	none	Display label (for chapter navigation)
gate	string	none	Visibility condition (gate id or expression)

Sections can contain: rkf-var, rkf-env, rkf-machine, nested rkf-section.

Environment element

rkf-env

Unified opaque environment element. Replaces the v1.0 rkf-prose, rkf-math, and rkf-media elements. The type attribute selects the variant. Can contain child rkf-port elements for interaction.

<rkf-env type="prose">Text here.</rkf-env>
<rkf-env type="math" display="block">\forall x \in \mathcal{L}</rkf-env>
<rkf-env type="image" src="diagram.png" alt="A diagram" />
<rkf-env type="video" src="lecture.mp4">
  <rkf-port dir="in" var="playing" type="boolean" />
  <rkf-port dir="out" var="currentTime" type="number" />
</rkf-env>
<rkf-env type="model" src="scene.glb" alt="3D model" />
<rkf-env type="audio" src="track.mp3" />

Attribute	Type	Default	Description
type	enum	required	prose, math, image, video, model, audio
display	enum	block	block or inline (for math type)
src	string	none	Source URL (for image, video, model, audio)
alt	string	none	Alt text (for image, model)
gate	string	none	Visibility condition (gate id or expression)

Content for prose and math types is the text inside the element. image, video, model, and audio types use the src attribute.

rkf-env elements can contain child rkf-port elements for typed I/O with the environment (e.g. controlling video playback, reading current time).

Content blocks (v2.0 multi-block model)

An rkf-env can carry a heterogeneous blocks array instead of (or alongside) a single type/content pair. Each block has a kind that determines its shape:

Kind	Description	Key fields
text	Rich text (heading, list, inline formatting)	content, heading ('1'|'2'|'3'), list ('ul'|'ol')
image	Static image	src, alt
math	LaTeX expression	content
machine	Inline rkf-machine block	id, vars, gates, derives, transforms, ports, machines, children
embed	Embedded <wity-knowledge> representation	id, application, snapshot
mermaid	Mermaid diagram source	content
row	Grid container holding blocks side-by-side	columns (default 2), cells (each with its own blocks)

Every block has a stable id, unique within its card. It is assigned when the block is created and when a document is opened (RkfEdit.normalizeDoc); an embed's or a machine's id is also its identity elsewhere and is never changed. Blocks are edited through the edit API.

Embed blocks

An embed block hosts another <wity-knowledge> representation inside the document. The application field identifies which domain library interprets the snapshot:

{
  kind: 'embed',
  id: 'budget-sheet',
  application: 'workbook',   // or 'system', 'decision-matrix', 'swot', 'eisenhower', 'ooda'
  snapshot: { /* serialized editor state */ }
}

The snapshot is opaque to rkf-core — it stores the serialized state of the embedded editor (e.g. a wity-workbook snapshot or a wity-system graph). The renderer mounts the appropriate domain editor and passes the snapshot for hydration. See the Composition guide for the full picture.

Row blocks

Row blocks arrange blocks in a CSS grid layout. A row has cells, and each cell holds its own ordered list of blocks:

{
  kind: 'row',
  id: 'b-…',
  columns: 3,
  cells: [
    { blocks: [ { kind: 'text', content: 'Column 1' } ] },
    { blocks: [ { kind: 'math', content: '\\sum_{i=1}^n x_i' } ] },
    { blocks: [ { kind: 'image', src: 'chart.png', alt: 'Chart' } ] }
  ]
}

A cell can hold any block kind except row, embed and machine. The earlier shape — blocks directly on the row, one block per cell — is read and upgraded without loss (RkfEdit.normalizeRow).

Spatial positioning (whiteboard mode)

An rkf-env can carry a pos object for spatial placement on a whiteboard canvas:

Field	Type	Description
x	number	X coordinate (canvas units)
y	number	Y coordinate (canvas units)
w	number	Width (canvas units)
h	number	Height (optional — auto-sized if absent)

When pos is present, the renderer places the environment at the specified position rather than in linear document flow.

State elements

rkf-var (feature-space)

Declares a dimension in the machine's feature-space.

<rkf-var id="lr" type="number" init="0.1" />
<rkf-var id="mode" type="string" init="linear" />
<rkf-var id="running" type="boolean" init="false" />
<rkf-var id="data" type="array" init="[[0,1],[1,0]]" />
<rkf-var id="pulse" init="0" elasticity="2" elastic-default="0" />

Attribute	Type	Default	Description
id	string	required	Variable name (used in expressions)
type	enum	number	number, string, boolean, array
init	string	0	Initial value (parsed according to type)
elasticity	number	none	Self-reset delay in ticks for temporal variables
elastic-default	string	none	Value to reset to after elasticity delay

rkf-gate (observation-space)

Declares a named boolean condition over feature-space. Gates recognise regions in feature-space and make state emergent.

<rkf-gate id="isRunning" expr="running" />
<rkf-gate id="converged" expr="error < 0.01" />
<rkf-gate id="inRange" expr="x > 0 && x < 100" />

Attribute	Type	Description
id	string	Gate name (can be referenced by gate attributes and trigger attributes)
expr	string	Boolean expression evaluated against current state

Visual elements with a gate attribute can now reference a gate id instead of (or in addition to) inline expressions.

rkf-derive

<rkf-derive id="slope" expr="-w1 / w2" />

Attribute	Type	Description
id	string	Derived variable name
expr	string	Expression evaluated against current state

Derived values are evaluated in topological (dependency) order, not declaration order. A derive that references another derive is always evaluated after its dependency, regardless of authoring order. Cyclic combinational dependencies are illegal and reported by validate().

rkf-transform (transformation-space)

Defines state transitions triggered by gates or expressions. Replaces the v1.0 rkf-update element.

<rkf-transform trigger="isRunning" on="tick">
  <rkf-set var="epoch" expr="epoch + 1" />
  <rkf-set var="w1" expr="w1 - lr * grad_w1" />
</rkf-transform>

Attribute	Type	Description
trigger	string	Gate id or boolean expression (evaluated before applying sets)
on	string	Optional event filter: tick, click, or custom

rkf-set

Attribute	Type	Description
var	string	Variable to update
expr	string	New value expression
when	string	Per-set guard condition

Machine blocks

<rkf-machine id="perceptron-viz" gate="condition">
  <rkf-var ... />
  <rkf-gate ... />
  <rkf-derive ... />
  <rkf-canvas ... />
  <rkf-port ... />
  <rkf-transform ... />
  <rkf-machine ... />
  <rkf-env ... />
</rkf-machine>

Attribute	Type	Description
id	string	Unique machine block identifier
gate	string	Visibility condition (gate id or expression)

Machine blocks are the state machine containers. They scope their vars, gates, derives, transforms, and ports. They support recursive nesting -- a machine can contain child machines. Inner variables are accessible via dot notation: sub.varName.

Port element (typed I/O)

rkf-port

Typed I/O interface. Replaces the v1.0 rkf-input element. The dir attribute specifies whether the port is an input or output.

<rkf-port dir="in" var="x" type="continuous" min="0" max="1" step="0.01" label="Learning rate" hint="slider" />
<rkf-port dir="in" var="mode" type="choice" options="linear,step,sigmoid" label="Activation" />
<rkf-port dir="in" var="showLabels" type="boolean" label="Show labels" />
<rkf-port dir="in" var="running" type="clock" interval="120" />
<rkf-port dir="in" var="epoch" type="increment" by="1" label="Step" />
<rkf-port dir="out" var="energy" />
<rkf-port dir="out" var="currentTime" type="number" />

Common attributes

Attribute	Type	Description
dir	enum	in or out (required)
var	string	State variable to bind to (required except for event type)
type	enum	Constraint type (required for dir="in")
label	string	Display label
hint	string	Non-normative renderer hint (e.g. slider, knob, dropdown)
gate	string	Visibility condition

type="continuous"

Bounded numeric range. Renderer decides affordance (slider, knob, text input, voice, etc.).

<rkf-port dir="in" var="lr" type="continuous" min="0.01" max="1.0" step="0.01" label="Learning rate" />

Attribute	Type	Description
min	number	Minimum value
max	number	Maximum value
step	number	Step increment

type="choice"

One of an enumerated set of values.

<rkf-port dir="in" var="mode" type="choice" options="linear,step,sigmoid" label="Activation" />

Attribute	Type	Description
options	string	Comma-separated option values
labels	string	Comma-separated display labels (optional)

type="boolean"

True/false.

<rkf-port dir="in" var="showLabels" type="boolean" label="Show labels" />

type="clock"

Boolean controlling a tick timer.

<rkf-port dir="in" var="running" type="clock" interval="120" />

Attribute	Type	Default	Description
interval	number	120	Tick interval in ms

type="increment"

Step action on a numeric variable.

<rkf-port dir="in" var="epoch" type="increment" by="1" label="Step" />

Attribute	Type	Default	Description
by	number	1	Increment amount

type="event"

Spatial event region. Contains child marks that define the interactive area.

<rkf-port dir="in" type="event" on="set:revealed = revealed + 1">
  <rkf-rect x="0" y="0" width="100" height="100" fill="transparent" />
</rkf-port>

Attribute	Type	Description
on	string	Action expression

Contains child marks that define the clickable region.

Canvas and layout

rkf-canvas

<rkf-canvas width="560" height="360" padding="40">
  <rkf-scale ... />
  <rkf-axis ... />
  <!-- marks -->
</rkf-canvas>

Attribute	Type	Default	Description
width	number	560	Canvas width in px
height	number	360	Canvas height in px
padding	number	40	Uniform padding in px
gate	string	none	Visibility condition

rkf-scale

<rkf-scale id="x" type="linear" domain="0, 1" range="pad, w-pad" />

Attribute	Type	Default	Description
id	string	required	Scale name (referenced by marks)
type	enum	linear	linear, log, ordinal
domain	string	required	Data domain (e.g. "0, 1" or "-2, 2")
range	string	required	Pixel range. Tokens: pad, w-pad, h-pad, w, h, or numbers

rkf-axis

<rkf-axis scale="x" orient="bottom" label="X axis" />

Attribute	Type	Default	Description
scale	string	required	Scale id to render axis for
orient	enum	--	bottom, left, top, right
label	string	none	Axis label text

rkf-group

<rkf-group id="cluster" gate="showCluster">
  <!-- child marks or elements -->
</rkf-group>

Attribute	Type	Description
id	string	Group identifier
gate	string	Group-level visibility condition

Mark elements

All marks support a gate attribute for conditional visibility. Expression-valued attributes are evaluated against state.

rkf-scatter

<rkf-scatter data="points" x="x" y="y" color-by="class" radius="6" />

Attribute	Type	Description
data	string	Data source reference
x	string	X field or expression
y	string	Y field or expression
color-by	string	Field to map to colour
radius	string	Point radius (px or expression)

rkf-line

<rkf-line x1="0" y1="intercept" x2="1" y2="slope + intercept" stroke="#e74c3c" stroke-width="2" />

Attribute	Type	Description
x1, y1	string	Start point (expression)
x2, y2	string	End point (expression)
stroke	string	Stroke colour
stroke-width	number	Stroke width
dash	string	Dash pattern (e.g. "8 5")

rkf-arrow

<rkf-arrow x1="0" y1="0" x2="gradient_x" y2="gradient_y" color="#2563eb" width="2" label="gradient" />

Attribute	Type	Description
x1, y1	string	Start point
x2, y2	string	End point
color	string	Arrow colour
width	number	Stroke width
label	string	Label text

rkf-rect

<rkf-rect x="10" y="10" width="100" height="50" fill="#f0f0f0" stroke="#333" rx="4" />

Attribute	Type	Description
x, y	string	Position
width	string	Width
height	string	Height
fill	string	Fill colour
stroke	string	Stroke colour
rx	number	Corner radius

rkf-circle

<rkf-circle cx="x_scaled" cy="y_scaled" r="8" fill="#3b82f6" />

Attribute	Type	Description
cx, cy	string	Centre point
r	string	Radius
fill	string	Fill colour
stroke	string	Stroke colour

rkf-arc

<rkf-arc cx="200" cy="200" r="80" startAngle="0" endAngle="angle" fill="#60a5fa" />

Attribute	Type	Description
cx, cy	string	Centre point
r	string	Radius
startAngle	string	Start angle (radians, expression)
endAngle	string	End angle (radians, expression)
fill	string	Fill colour
stroke	string	Stroke colour

rkf-text

<rkf-text x="100" y="20" text-anchor="middle" font-size="14" color="#333">Label</rkf-text>

Attribute	Type	Default	Description
x, y	string	--	Position
text-anchor	enum	start	start, middle, end
font-size	string	--	Font size
color	string	--	Text colour
font-weight	string	--	Font weight

Content is the text inside the element.