Entity Schema Documentation

This document describes the entity and relationship schema for the Kibi Knowledge Base. It covers all supported entity types, their properties, relationship types, and provides frontmatter examples for each entity and relationship.

Entity Types

Kibi intentionally supports eight core entity types, organized into two logical groups:

Common Authoring Entities (Standard Workflow)

Type	Description
req	Software requirement specifying functionality or constraints
scenario	BDD scenario describing user behavior (Given/When/Then)
test	Unit, integration, or e2e test case
fact	Atomic domain fact; includes strict lanes and observation/meta notes

Supporting & System Entities (Context & Infrastructure)

Type	Description
adr	Architecture Decision Record documenting technical choices
flag	Runtime or config gate (feature flag, kill-switch, deferred capability)
event	Domain or system event published/consumed by components
symbol	Abstract code symbol (function, class, module) - language-agnostic

Entity Choice: When to Use Each Type

This section provides guidance on selecting the appropriate entity type for your documentation needs.

Decision Table

What you are documenting	Entity Type	Notes
Intended or corrected behavior	`req`	Requirements specify what the system should do
Bug, incident, or workaround	`fact` (observation/meta)	Use `fact_kind: observation` or `meta` for non-blocking evidence
Runtime/config gate controlling feature access	`flag`	Feature flags, kill-switches, deferred capabilities
Executable verification or reproduction	`test`	Unit, integration, or e2e tests
Technical decision or tradeoff rationale	`adr`	Architecture Decision Records

Important Rules

Do NOT create a flag for bugs or workarounds unless there is an actual runtime/config gate. Use fact with fact_kind: observation or meta instead.

When a bug is mitigated by a feature gate: Create TWO records - a fact describing the issue and a flag representing the gate. Link them with relates_to since no typed relationship exists for this case.

Canonical Mapping Summary

flag = Runtime/config gate (includes kill-switches, deferred capabilities) - NOT for bug records
fact (observation/meta) = Bug records, incident notes, workarounds
req = Intended/corrected behavior
test = Executable verification/reproduction
adr = Durable design rationale

Common Properties (All Entities)

Property	Required	Type	Description
id	Yes	string	Unique identifier (SHA256 or explicit frontmatter)
title	Yes	string	Short summary/name
status	Yes	string	Entity status (see below for values)
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance (file path, URL, or reference)
tags[]	No	array[string]	Array of metadata/search tags only
owner	No	string	Owner/assignee
priority	No	string	Priority level (must, should, could)
severity	No	string	Severity level
links[]	No	array[string]	Array of URLs
text_ref	No	string	Pointer to Markdown/doc blob

Entity Type Details & Example Frontmatter

Requirement (`req`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Requirement summary
status	Yes	string	open, in_progress, closed, deprecated
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	must, should, could
severity	No	string	Severity level
links[]	No	array[string]	URLs or entity IDs (for relationships)
text_ref	No	string	Markdown/doc pointer

Canonical Example: REQ + SCEN + TEST (Golden Path)

# documentation/requirements/REQ-001.md
---
id: REQ-001
title: User authentication
status: open
created_at: 2026-03-10T10:00:00Z
updated_at: 2026-03-10T10:00:00Z
source: documentation/requirements/REQ-001.md
links:
  - type: specified_by
    target: SCEN-001
---

# documentation/scenarios/SCEN-001.md
---
id: SCEN-001
title: Login with valid credentials
status: active
created_at: 2026-03-10T10:01:00Z
updated_at: 2026-03-10T10:01:00Z
source: documentation/scenarios/SCEN-001.md
---

# documentation/tests/TEST-001.md
---
id: TEST-001
title: Login test
status: passing
created_at: 2026-03-10T10:02:00Z
updated_at: 2026-03-10T10:02:00Z
source: documentation/tests/TEST-001.md
links:
  - type: validates
    target: SCEN-001
---

Generic Link Shorthand:

links:
  - ADR-001
  - FACT-001

Plain string Markdown links entries are imported as generic relates_to relationships. Use typed link objects or relationship rows when the semantic relationship matters.

Relationship Rows Example:

# Relationship: REQ-001 specified_by SCEN-001
relationship:
  type: specified_by
  source: REQ-001
  target: SCEN-001
  created_at: 2026-03-10T10:03:00Z
  created_by: analyst
  source: documentation/requirements/REQ-001.md
---
# Relationship: REQ-001 verified_by TEST-001
relationship:
  type: verified_by
  source: REQ-001
  target: TEST-001
  created_at: 2026-03-10T10:04:00Z
  created_by: qa
  source: documentation/requirements/REQ-001.md

Rule: Never embed scenarios or tests inside requirement records. Always create separate files for each entity and link them with explicit typed links entries or relationship rows (specified_by, verified_by). Plain string links are generic relates_to only.

Strict Fact Modeling (Normative Lane):

New contradiction-sensitive requirements should use the strict fact lane:
- one fact_kind: subject fact linked via constrains
- one fact_kind: property_value fact linked via requires_property
For v1, the supported evolution path is append-only: create a new requirement and link it to the prior one with supersedes.
Plain requirement upserts do not automatically replace older constrains / requires_property semantics.
Use observation and meta facts for runtime evidence, historical notes, and governance context that should not participate in contradiction blocking.

Canonical Contradiction-Safe Example:

# documentation/facts/FACT-USER-ROLE.md
---
id: FACT-USER-ROLE
title: User Role Assignment
status: active
created_at: 2026-03-24T00:00:00Z
updated_at: 2026-03-24T00:00:00Z
source: documentation/facts/FACT-USER-ROLE.md
fact_kind: subject
subject_key: user.role_assignment
---

# documentation/facts/FACT-LIMIT-3.md
---
id: FACT-LIMIT-3
title: Maximum of Three
status: active
created_at: 2026-03-24T00:00:00Z
updated_at: 2026-03-24T00:00:00Z
source: documentation/facts/FACT-LIMIT-3.md
fact_kind: property_value
subject_key: user.role_assignment
property_key: max_roles
operator: lte
value_type: int
value_int: 3
---

# documentation/requirements/REQ-019.md
---
id: REQ-019
title: Users can now have 3 roles
status: open
created_at: 2026-02-20T13:06:00Z
updated_at: 2026-03-24T00:00:00Z
source: documentation/requirements/REQ-019.md
links:
  - type: constrains
    target: FACT-USER-ROLE
  - type: requires_property
    target: FACT-LIMIT-3
  - type: supersedes
    target: REQ-018
---

Invalid Example (Prohibited):

# WRONG - embedded scenario
---
id: REQ-001
title: User authentication
scenarios:
  - given: user is on login page
    when: they enter valid credentials
    then: they are logged in
---

Scenario (`scenario`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Scenario summary
status	Yes	string	draft, active, deprecated
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: SCEN-001
title: Sample scenario SCEN-001
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/scenarios/SCEN-001
tags:
  - sample
---

Test (`test`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Test summary
status	Yes	string	passing, failing, skipped, pending
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer
verification_scope	No	enum	`unit`, `integration`, or `end_to_end`
verification_perspective	No	enum	`internal` or `consumer`

tags remain metadata only. They do not alias or replace typed verification fields.

Example:

---
id: TEST-001
title: Sample test TEST-001
status: passing
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/tests/TEST-001
tags:
  - sample
verification_scope: integration
verification_perspective: internal
---

See docs/examples/test-verification-fields.md for a complete example using both typed fields.

ADR (`adr`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	ADR summary
status	Yes	string	proposed, accepted, deprecated, superseded
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: ADR-001
title: Sample ADR ADR-001
status: accepted
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/adrs/ADR-001
tags:
  - architecture
---

Flag (`flag`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Flag summary
status	Yes	string	active, inactive, deprecated
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: FLAG-001
title: Sample flag FLAG-001
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/flags/FLAG-001
tags:
  - rollout
---

Event (`event`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Event summary
status	Yes	string	active, deprecated
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: EVT-001
title: Sample event EVT-001
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/events/EVT-001
tags:
  - domain
---

Symbol (`symbol`)

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Symbol summary
status	Yes	string	active, deprecated, removed
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: SYM-001
title: Sample symbol SYM-001
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/symbols/SYM-001
tags:
  - code
---

Fact (`fact`)

Facts support two authoring lanes:

Strict lane for normative, contradiction-sensitive knowledge
- subject: requires subject_key
- property_value: requires subject_key, property_key, operator, value_type, and exactly one value field
Context lane for non-blocking knowledge
- observation
- meta

Legacy prose facts without fact_kind remain readable during migration, but new requirements should prefer the strict lane when the fact expresses a rule that should block contradictions.

fact entities represent atomic domain concepts and invariants (for example domain nouns, cardinalities, and property values). Requirements can link to facts using constrains and requires_property so contradictions become structural and queryable.

Property	Required	Type	Description
id	Yes	string	Unique identifier
title	Yes	string	Fact summary
status	Yes	string	active, deprecated
created_at	Yes	ISO 8601	Creation timestamp
updated_at	Yes	ISO 8601	Last update timestamp
source	Yes	string	Provenance
tags[]	No	array[string]	Tags
owner	No	string	Owner/assignee
priority	No	string	Priority level
severity	No	string	Severity level
links[]	No	array[string]	URLs
text_ref	No	string	Markdown/doc pointer

Example:

---
id: FACT-USER-ROLE
title: User Role Assignment
status: active
created_at: 2026-02-20T13:00:00Z
updated_at: 2026-02-20T13:00:00Z
source: documentation/facts/FACT-USER-ROLE.md
tags:
  - domain
  - auth
---

Relationship Types

Kibi supports relationship types listed below. Each relationship has metadata:

Property	Required	Type	Description
created_at	Yes	ISO 8601	Creation timestamp
created_by	Yes	string	Creator identifier
source	Yes	string	Provenance
confidence	No	string/number	Optional confidence level

Relationship Table

Relationship	Source Entity	Target Entity	Description
depends_on	req	req	Requirement depends on another requirement
specified_by	req	scenario	Requirement is specified by a scenario
verified_by	req/scenario	test	Requirement or scenario is verified by a test
validates	test	req/scenario	Test validates a requirement or scenario
implements	symbol	req	Symbol owns or implements requirement behavior
covered_by	symbol	test	Production symbol has coverage evidence from a test
executable_for	symbol	test	Symbol is executable test code for a test entity
constrained_by	symbol	adr	Symbol constrained by ADR
constrains	req	fact	Requirement constrains a specific domain fact
requires_property	req	fact	Requirement requires a property fact/value
guards	flag	symbol/event/req	Flag guards symbol, event, or requirement
publishes	symbol	event	Symbol publishes event
consumes	symbol	event	Symbol consumes event
supersedes	adr	adr	The source ADR formally replaces the target ADR. The target is expected to carry status: archived or deprecated
relates_to	a	b	Generic relationship (escape hatch)

Relationship Examples

depends_on

# req REQ-002 depends_on req REQ-001
relationship:
  type: depends_on
  source: REQ-002
  target: REQ-001
  created_at: 2026-02-17T13:10:00Z
  created_by: analyst
  source: https://example.com/fixtures/requirements/REQ-002

specified_by

# req REQ-001 specified_by scenario SCEN-001
relationship:
  type: specified_by
  source: REQ-001
  target: SCEN-001
  created_at: 2026-02-17T13:15:00Z
  created_by: analyst
  source: https://example.com/fixtures/requirements/REQ-001

verified_by

# req REQ-001 verified_by test TEST-001
relationship:
  type: verified_by
  source: REQ-001
  target: TEST-001
  created_at: 2026-02-17T13:20:00Z
  created_by: qa
  source: https://example.com/fixtures/tests/TEST-001

verified_by has one frozen meaning: a requirement or scenario is verified by a test. Direct req -> test is fallback only when no scenario exists. Prefer req -> scenario -> test.

validates

# test TEST-001 validates scenario SCEN-001
relationship:
  type: validates
  source: TEST-001
  target: SCEN-001
  created_at: 2026-02-17T13:22:00Z
  created_by: qa
  source: https://example.com/fixtures/tests/TEST-001

validates is the inverse edge for req/scenario ↔ test links.

implements

# symbol SYM-001 implements req REQ-001
relationship:
  type: implements
  source: SYM-001
  target: REQ-001
  created_at: 2026-02-17T13:25:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-001

implements is frozen to requirement ownership only (symbol -> req).

covered_by

# symbol SYM-001 covered_by test TEST-001
relationship:
  type: covered_by
  source: SYM-001
  target: TEST-001
  created_at: 2026-02-17T13:30:00Z
  created_by: dev
  source: https://example.com/fixtures/tests/TEST-001

covered_by is frozen to production coverage evidence only (symbol -> test).

executable_for

# symbol SYM-TEST-001 executable_for test TEST-001
relationship:
  type: executable_for
  source: SYM-TEST-001
  target: TEST-001
  created_at: 2026-02-17T13:32:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-TEST-001

executable_for is frozen to executable test code identity only (symbol -> test).

constrained_by

# symbol SYM-001 constrained_by adr ADR-001
relationship:
  type: constrained_by
  source: SYM-001
  target: ADR-001
  created_at: 2026-02-17T13:35:00Z
  created_by: architect
  source: https://example.com/fixtures/adrs/ADR-001

guards

# flag FLAG-001 guards req REQ-001
relationship:
  type: guards
  source: FLAG-001
  target: REQ-001
  created_at: 2026-02-17T13:45:00Z
  created_by: devops
  source: https://example.com/fixtures/flags/FLAG-001

publishes

# symbol SYM-001 publishes event EVT-001
relationship:
  type: publishes
  source: SYM-001
  target: EVT-001
  created_at: 2026-02-17T13:50:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-001

consumes

# symbol SYM-001 consumes event EVT-001
relationship:
  type: consumes
  source: SYM-001
  target: EVT-001
  created_at: 2026-02-17T13:55:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-001

constrains

# req REQ-018 constrains fact FACT-USER-ROLE
relationship:
  type: constrains
  source: REQ-018
  target: FACT-USER-ROLE
  created_at: 2026-02-20T14:00:00Z
  created_by: analyst
  source: documentation/requirements/REQ-018.md

requires_property

# req REQ-018 requires_property fact FACT-LIMIT-2
relationship:
  type: requires_property
  source: REQ-018
  target: FACT-LIMIT-2
  created_at: 2026-02-20T14:01:00Z
  created_by: analyst
  source: documentation/requirements/REQ-018.md

relates_to

# Generic relationship between any two entities
relationship:
  type: relates_to
  source: ENTITY-A
  target: ENTITY-B
  kind: custom
  created_at: 2026-02-17T14:00:00Z
  created_by: analyst
  source: https://example.com/fixtures/entities/ENTITY-A

supersedes

# adr ADR-010 supersedes adr ADR-009
relationship:
  type: supersedes
  source: ADR-010
  target: ADR-009
  created_at: 2026-02-20T10:00:00Z
  created_by: architect
  source: https://example.com/fixtures/adrs/ADR-010

Notes

All entity and relationship types are fixed in v0; extensibility is planned for future versions.
IDs must be stable and unique (content-based SHA256 or explicit frontmatter).
Relationship metadata supports audit and conflict resolution.
Status values are entity-type specific (see above).

End of schema documentation.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Entity Schema Documentation

Entity Types

Common Authoring Entities (Standard Workflow)

Supporting & System Entities (Context & Infrastructure)

Entity Choice: When to Use Each Type

Decision Table

Important Rules

Canonical Mapping Summary

Common Properties (All Entities)

Entity Type Details & Example Frontmatter

Requirement (`req`)

Scenario (`scenario`)

Test (`test`)

ADR (`adr`)

Flag (`flag`)

Event (`event`)

Symbol (`symbol`)

Fact (`fact`)

Relationship Types

Relationship Table

Relationship Examples

Notes

FilesExpand file tree

entity-schema.md

Latest commit

History

entity-schema.md

File metadata and controls

Entity Schema Documentation

Entity Types

Common Authoring Entities (Standard Workflow)

Supporting & System Entities (Context & Infrastructure)

Entity Choice: When to Use Each Type

Decision Table

Important Rules

Canonical Mapping Summary

Common Properties (All Entities)

Entity Type Details & Example Frontmatter

Requirement (req)

Scenario (scenario)

Test (test)

ADR (adr)

Flag (flag)

Event (event)

Symbol (symbol)

Fact (fact)

Relationship Types

Relationship Table

Relationship Examples

Notes

Requirement (`req`)

Scenario (`scenario`)

Test (`test`)

ADR (`adr`)

Flag (`flag`)

Event (`event`)

Symbol (`symbol`)

Fact (`fact`)