Create BKN

Generate well-formed BKN directories (Markdown + YAML frontmatter) in either spec version: BKN 3.0 (default) or BKN 2.x.

Works with the openbkn skill

create-bkn authors the .bkn tree; the openbkn skill runs openbkn auth login and openbkn bkn push / pull after files exist.

What is BKN

BKN is Markdown + YAML frontmatter for schema; one file per definition under typed subfolders. Details (sections, required tables, types, every declaration) live in references/SPECIFICATION.llm.md.

Spec version: 3.0 or 2.x

Pick the spec version before writing anything:

• Find the target platform with openbkn --version: the CLI only talks to a platform of its own version. If the user names a version, use that; if neither the spec nor the platform is known, ask.
• A 2.x package is the 3.0 writing minus the 3.0 additions (value types, declarations, aliases, lifecycle, fallback paths); what they would say goes into descriptions. Every platform reads it the same way, including 0.2.1 and later. The rules are in references/SPECIFICATION.llm.md.
• Never mix the two: 2.x readers (no bkn_spec, or a 0.2.0 platform) import 3.0 content without an error, but ### Property Constraints and ### Relation Constraints become description text, value types and aliases are dropped, and fallback paths and deprecated relations become ordinary relations.
• 3.0 accepts one way to write each thing. Unknown frontmatter fields, unknown ### sections, unknown or legacy columns and wrappers are rejected on push with the file and position. Write only what the spec lists.
• The templates are 3.0; for 2.x drop the 3.0 parts the spec lists.

Directory layout

Do not hand-write a CHECKSUM, and delete it when you copy the example and change its files: a stale one only makes push warn, but a package with object metrics is refused. openbkn bkn pull writes a fresh one.

{network_dir}/
├── SKILL.md
├── network.bkn
├── CHECKSUM                 # optional; generated on export — do not write or copy one
├── value_types/             # 3.0 only: enums, formats, ranges reused by properties
├── object_types/
├── relation_types/
├── action_types/
├── risk_types/
└── concept_groups/

Workflow

1. Spec version — 3.0 or 2.x (see Spec version)
2. Gather requirements — objects and their key properties, relations (and which ones are reliable), actions, code tables / dictionaries, optional concept groups
3. Read spec — references/SPECIFICATION.llm.md (format rules, sections, declarations)
4. Pick templates — copy/adapt from assets/templates/
5. Create network.bkn — root file; bkn_spec: "3.0" for 3.0, none for 2.x; title and network description only
6. Create value_types/*.bkn (3.0 only) — one per code table (enum), fixed format (pattern / length) or bounded number (range / unit) that properties share
7. Create object_types/*.bkn — one file per object, {id}.bkn; for 3.0 declare semantic, required, aliases and constraints
8. Create relation_types/*.bkn — one file per relation; for 3.0 declare reverse name, cardinality, constraints; mark helper relations secondary and link fallback paths with fallback_for
9. Create action_types/*.bkn — one file per action
10. Create concept_groups/*.bkn — optional
11. Add root SKILL.md in the BKN directory — same folder as network.bkn (this is not the create-bkn skill file); agent-facing guide for that network (see Delivered BKN: root SKILL.md)
12. Review (MUST) — cross-check Validation checklist and Business rules placement; fix IDs, cross-refs, headings
13. Validate (MUST) — openbkn bkn validate <dir> (see Validation)
14. Import (optional) — openbkn bkn push <dir>

Import (openbkn CLI)

Requires the openbkn CLI from @openbkn/bkn-sdk (npm install -g @openbkn/bkn-sdk; Node.js 22.19.0+). push uses tar; on macOS COPYFILE_DISABLE=1 is set by the tool.

• Platform auth — Don't pre-check with openbkn auth status; run openbkn bkn push directly (validate is offline and needs no login). Only when it fails with 401 / not authorized, run openbkn auth login <platform-url> and retry.
• BKN validation — If workflow step 13 (openbkn bkn validate <dir>) already succeeded for this directory, do not repeat validate before push unless you changed .bkn files. If you have not validated yet, run validate before push.
• 3.0 rules — a 0.2.1+ platform checks the 3.0 rules on push and names the file, section and field of each problem. Fix the file and push again. A 2.x package is read with the 2.x rules on every platform.
• Tools — every toolbox or MCP tool an action or logic property references must exist on the target platform, or push fails listing the missing tools. To import the model without them, push with --binding-policy detach and bind the tools on the platform afterwards.

openbkn bkn push <dir> [--branch main] [--binding-policy detach]

Export: openbkn bkn pull <kn-id> [<dir>]. More subcommands: openbkn bkn --help (see the openbkn skill if loaded).

Validation

openbkn bkn validate <dir> — must pass before delivery or upload. It is an offline structural check: it loads network.bkn and sibling .bkn files, checks frontmatter, ids, table shape and relation endpoints, and prints counts (object types, relation types, concept groups, value types). The 3.0 declaration rules are checked by the platform on push; follow the spec to get them right the first time.

A capabilities: section in network.bkn never fails validation. Read capabilities.skipped and the warnings instead: an entry listed there binds on no platform. After push, the answer's capabilities.skipped names what this platform could not resolve.

Per-type reference

Templates are complete 3.0 files: replace every {placeholder}, and delete rows, columns, keys or sections you do not need (a column no property uses, such as Semantic or Aliases, is left out whole). Full rules and optional sections: references/SPECIFICATION.llm.md.

Declarations: when to use what

• Code table / dictionary (status codes, department codes) → enum value type, referenced with value_type. Keep retired codes with deprecated: true: stored data still holds them.
• Shared format or range (ID card number, amount ≥ 0) → format / range value type. A property that references a value type writes no range / length / pattern / unit of its own.
• One-off constraint → inline in ### Property Constraints.
• Time and place → Semantic (event_time, end_time, valid_from, valid_to, location, latitude / longitude), plus timezone / crs when known.
• Other names users call it → aliases (definitions) and the Aliases column (properties).
• Relations → reverse_name when the reverse reads differently; Cardinality whenever known; required for "every X has a Y"; verification: unconfirmed for inferred links; importance: secondary + fallback_for for a path that fills gaps of a primary relation.
• Retiring a definition → lifecycle: { status: deprecated, reason, replaced_by }, never a name prefix like "【废弃】".
• BKN 2.x → none of the above exists; write what they would say in the descriptions (codes and meanings, units, time zone, "also called …", matching rules), leave out fallback-path and deprecated definitions. The table is in the spec.

Naming conventions

• ID: lowercase, digits, underscores; file: {id}.bkn under the matching folder
• Headings: # network title, ## definition (## ObjectType: {name}, ## ValueType: {name}, …), ### section, #### logic property
• Frontmatter: type, id, name, plus only the fields the spec lists for that type

Business rules placement

Rules must sit in spec-defined places so import persists them. Full wording: references/SPECIFICATION.llm.md.

• Network-level — prose in network.bkn right after # {title}
• Type-level — prose in each type file after ## ObjectType: / ## RelationType: / … and before the first ###; never in frontmatter
• Property-level — what a declaration can say (semantic, required, unit, enum, format, range) goes in the declaration; the Description column keeps only business meaning, calculation and caveats
• No extra sections — 3.0 rejects unknown ### sections and frontmatter fields

Validation checklist

• Spec version chosen; 3.0: network.bkn has bkn_spec: "3.0"; 2.x: no bkn_spec, no value_types/, no 3.0 fields, columns or sections
• network.bkn at root; body is only the title and description
• Every .bkn has valid YAML frontmatter (type, id, name) and no fields outside the spec
• Files live under folders matching type (value_types/, object_types/, …); filename = {id}.bkn; ## {Prefix}: {name} matches name
• Relations, actions, concept groups, value_type, fallback_for and replaced_by reference ids defined in the package
• Semantic values fit the property Type and appear at most once per definition; end_time has an event_time; latitude / longitude come in pairs
• Primary keys leave Required empty; no Required: false, importance: primary or lifecycle.status: active written out
• A property with value_type has no range / length / pattern / unit
• Parameter tables put property | input | const in ValueFrom, the property name or constant in Value, and the request position (Query / Body / …) in Source
• Condition YAML is written directly (no condition: wrapper); every YAML block parses
• Heading hierarchy has no skipped levels; no HTML comments or notes left inside sections
• Business rules only in allowed places (see Business rules placement)

Output rules

1. Emit raw .bkn content — do not wrap the whole file in a fenced markdown block
2. Reuse IDs consistently across relations/actions/value types
3. IDs: lowercase + underscores; display text Chinese unless asked otherwise
4. Keep heading order and column names per spec

Examples

• references/examples/clinic-lab/ — BKN 3.0: value types, property declarations, aliases, relation declarations and properties, lifecycle, fallback path, action, concept group
• references/examples/clinic-lab-2.x/ — the same network in BKN 2.x: no 3.0 declarations, their content in descriptions

Delivered BKN: root SKILL.md

When you build a knowledge network directory {network_dir}/, add {network_dir}/SKILL.md at the root (alongside network.bkn). Short overview + index tables with file paths (value type | object | relation | action | path) so agents route to the right .bkn without scanning, and how to use the declarations (enum codes, fallback paths, deprecated definitions). Example: references/examples/clinic-lab/SKILL.md.