Configuration schema¶

fkf.yaml has two related schemas:

• the generated JSON Schema defines FKF's configuration syntax and rejects unknown or malformed configuration;
• the base-owned schema: dictionary defines what record fields mean across every source in that base.

The configuration and every stored evidence document use fkf: 1. They are separate contracts identified by the containing file. Compatible evidence additions remain readable under marker 1; an incompatible change requires a new marker and an explicit release boundary.

The semantic dictionary¶

Every field declaration requires a description and cardinality:

Set relation: true when every value is an FKF URI that should become a graph edge. examples document intent; they do not validate or normalize provider values.

fkf: 1
name: brain

schema:
  id:
    description: Stable record identity.
    cardinality: one
  time:
    description: Record timestamp when the provider exposes one.
    cardinality: optional
  title:
    description: Human-readable record label.
    cardinality: optional
  repository:
    description: Repository associated with the record.
    cardinality: optional
    relation: true
    examples: [repo:github.com/fmind/fkf]
  participant:
    description: Person or account involved in the record.
    cardinality: many
    relation: true
    examples: [person:email/user@example.test, actor:github.com/login]

id is required and must be one. Every collected source also maps title, and event sources map time; a new record must yield one meaningful title even when its schema cardinality is optional for envelope compatibility. time, title, and url are scalar presentation fields and therefore use one or optional. All other names are base-defined. A field name states a role such as participant, author, or reviewer; a URI value states an identity namespace such as person:email/... or actor:github.com/.... FKF merges identities only through explicit root or authored-page aliases.

Source mappings¶

A source maps provider paths into the shared dictionary. id, title, and event time are required projections; every mapping refers to a field already declared under root schema:.

sources:
  git-commits:
    enabled: true
    layer: events
    requires: [git-log-json.py, python3, git]
    window: true
    run: [git-log-json.py, "{{start}}", "{{end}}", "{{home}}"]
    test: [git-log-check.sh, "{{home}}"]
    fields:
      id: .uid
      time: .time
      title: .message
      repository: .repository_uri
      participant: [".participant_uris[]"]

FKF stores the exact schema subset and field map used by each collected document. That evidence lets current readers validate older records even after the base adds new optional fields. Optional test: hooks are one direct argv array, accept only {{base}} and {{home}}, and are execution-trusted alongside run: and body:. Put git-log-check.sh in the base's tests/ tree; FKF searches that tree only for source tests and hashes its full contents and executable modes into trust.

Generated JSON Schema¶

Print the schema without opening a base:

fkf config schema

The same generated artifact is published as fkf.schema.json. Editors that support a YAML language-server directive can bind a base directly to it:

# yaml-language-server: $schema=https://fmind.github.io/fkf/fkf.schema.json
fkf: 1

The loader rejects unknown keys, unknown field references, missing descriptions, invalid cardinality, malformed placeholders, multiple YAML documents, and enabled sources targeting disabled layers. The published artifact is generated from that loader, not maintained independently. Contributors run mise run generate:schema after loader changes and never edit docs/fkf.schema.json by hand.

The JSON Schema proves configuration shape. Provider output still needs a trusted, write-free fkf sync <source> --preview to prove decoding, field projection, cardinality, relations, and completeness against a real sample.