The property format

Two files, both JSON

The format is two file kinds and one rule: the schema defines types, the data holds instances of them, and everything is valid JSON, so jq, git diff and your own loader keep working.

Every file starts with "$dialect": "bi/1" — the extension picks the view, the dialect confirms it. A data file names its schema with $schema, a path relative to itself. Keys starting with $ are bi’s; your types and fields must not use them.

A schema is a types map. A struct’s fields are an array, because order is display order:

{
  "$dialect": "bi/1",
  "types": {
    "Rarity": { "kind": "enum", "values": ["common", "rare", "epic"] },
    "Weapon": {
      "kind": "struct",
      "fields": [
        { "name": "name",   "type": "string" },
        { "name": "damage", "type": "i32", "default": 10, "min": 0, "max": 999 },
        { "name": "rarity", "type": "Rarity", "default": "common" }
      ]
    }
  }
}

A data file is a list of instances, each naming its $type and $id:

{
  "$dialect": "bi/1",
  "$schema": "game.bischema",
  "instances": [
    { "$type": "Weapon", "$id": "rusty_sword", "name": "Rusty Sword", "damage": 12 }
  ]
}

Storage is sparse. rusty_sword omits rarity, so it is common from the schema — and changing that default changes every instance that did not override it. Writing a value equal to the default removes the key again on :w, so a diff shows real overrides and nothing else.

Starting from nothing

You do not have to write either file by hand. Open a name that does not exist yet, and the two commands that matter are :bi init — the skeleton — and :bi add, which grows the schema a type or a field at a time.

loot.bischema A schema and its data, from nothing 1 / 9 play

1. start bi loot.bischema on a name with no file behind it. An empty buffer is not valid JSON, so it opens as text and says why — the view needs something to draw.
2. 1 :bi initEnter :bi init writes the skeleton — $dialect and an empty types map — and the schema view comes up over it. The mode reads BISCHEMA.
3. 2 :bi add Rarity enum common rare epicEnter An enum and its values, in one command.
4. 3 :bi add Weapon struct name:string damage:i32 rarity:RarityEnter A struct with three fields. rarity names the enum above it, and the type grammar resolves it.
5. 4 :bi add Weapon two_handed:boolEnter:wEnter :bi add <Type> <field>:<type> on a struct that already exists appends a field. :w writes the file — JSON on disk, all along.
6. 5 :e loot.bidataEnter Now the data. Same story: nothing on disk yet, so nothing to draw.
7. 6 :bi initEnter :bi init again. Exactly one .bischema sits beside this file, so $schema is filled in for you and the data view opens knowing what a Weapon is.
8. 7 :bi new Weapon rusty_swordEnter An instance, with every field at the schema’s default — dim, because nothing here overrides anything yet.
9. 8 :bi set rusty_sword.damage 12Enter:wEnter One value set by path, then written. Only damage lands in the file: storage is sparse, so the other three stay the schema’s.

:bi init on the data file guesses $schema when exactly one .bischema sits beside it, so the second half of that session never named the first. From there :bi new <Type> <id> appends an instance and :bi set <path> <value> fills it in; both are covered in Editing data.

Types

A field’s type is a string, parsed by a small grammar with no whitespace in it:

Embed a struct for small value-like data each parent owns — a Vec2, a stats block. Use ref<S> for something shared and identified, so one edit reaches every user. A ref without a default is required; make it optional<ref<S>> when absence is legitimate.

Ids are scoped per type, so a Weapon and an Enemy may both be boss. Enum values are stored by name, never by index, so reordering them is free.

The data view

Open a .bidata and you get a form: a section per instance, one row per field, each drawn as what it is.

level1.bidata A data file as a form 1 / 4 play

1. start level1.bidata opens as a form: a section per instance, one row per field, each drawn as what it is.
2. 1 j×4 j and k pick a row. element has widget: toggle in the schema, so every value is shown with the current one bracketed.
3. 2 Tab×3 Tab steps to the next instance — here past the other weapons to goblin.
4. 3 l l opens it. stats is inline, so its fields sit in the form; weapon is a ref, drops a list of them.

A number with both min and max is a slider, a bool a checkbox, an enum or a ref a choice, a rgb a brick painted its colour, a curve a sparkline, a gradient sixteen sampled bricks. A value the instance sets is drawn plainly, one inherited from the schema is dim, a read-only field is muted, and a warning rides on the row after ⚠. The field’s doc shows in the status row while the row is selected.

Rows that draw instead of spell

Four of the types have no useful text form, so the view gives them a picture on the row itself.

level1.bidata Colours, curves and gradients on a row 1 / 5 play

1. start The sample bi gen sample writes. rusty_sword is open, and two rows already draw rather than spell: falloff is a sparkline of the curve it inherits, tint a brick painted #c8c8c8. Both are dim, because the instance sets neither.
2. 1 Tab×2l Tab twice to frost_hammer, l to open it. Crit multiplier is gone: its show_if names crit_chance > 0, and this weapon sets crit_chance to 0.
3. 2 j×6 Down to falloff. This one is set, so it is drawn plainly: three points, sampled across sixteen cells. The row says how many.
4. 3 j×5l Down to Advanced and l to unfold it — the schema marks that group collapsed, so it starts shut.
5. 4 jj glow is an rgba, its brick blended over the pane by its alpha. trail is a gradient: sixteen bricks sampled across the ramp, and the stop count after them.

None of the four turns with l — there is no next colour — so dd puts the default back and Enter opens the value in its own editor: the colour picker or the gradient bar for a colour or a ramp, the curve editor for a curve, each split to the right of the view with its form down the edge. :set editor color, curve and gradient on the view do the same as Enter.

The keys in the tool rewrite the JSON in this buffer, and the view re-reads after every one, so the brick or the sparkline follows the edit as you make it. An inherited value is written into the instance first, as its own undo step, so there is a literal to edit; a readonly field refuses with read-only. Esc on the picture comes back to the view with the tool still open, :q closes it.

Turning values

l and h turn the value under the cursor; everywhere else they open and close rows. That one rule is the whole keymap.

level1.bidata Turning values 1 / 5 play

1. start The cursor is on the rusty_sword header.
2. 1 j×3 Down past name and the Combat group to damage — a slider, because the schema gives it a min and a max.
3. 2 l×3 l turns a value up by its step; the slider and the number follow.
4. 3 L L is ten steps at once, H ten back.
5. 4 j×6Enter Down to two_handed; Enter flips a checkbox. The value is set now, so it is drawn plainly instead of dim.

Every key that changes something is one edit of the buffer and one undo step. The view re-reads the buffer afterwards, so there is one history, not two: :w, :q, u and the modified marker are the file’s, exactly as in a text window.

Refs across files

A ref<Weapon> stores an id. The editor keeps an index of every .bidata under the project root whose $schema resolves to the same schema, which is what l cycles through, what warns you about a dangling ref, and what gd jumps by — into another file when that is where the target lives.

level1.bidata Following a ref 1 / 3 play

1. start goblin is open. weapon holds a ref<Weapon>: the target’s id, with the type it points into.
2. 1 j×6 Down to weapon. l would cycle it through every Weapon in the project.
3. 2 gd gd jumps to the target instead — here rusty_sword, in this file; a target in another data file opens that file.

The schema view

A .bischema opens as a tree instead: one row per type, its fields under it, and every layout attribute under the field.

game.bischema The schema as a tree 1 / 3 play

1. start game.bischema opens as a tree of types: enums with their values, structs with their fields.
2. 1 j×3 Pick a type.
3. 2 l l opens it — one row per field, with its type and default.

The attributes are the schema’s own, and they change how the editor draws a field, never what the data means — a reader that does not know them ignores them.

A condition names a sibling: two_handed, !two_handed, rarity == epic, hp > 10. A struct may also carry groups with options per group, so a section can start collapsed.

Opening and mending

The extension does this for you; the commands are for a file that has none. An empty buffer gets the skeleton written first, with $schema filled in when exactly one .bischema sits beside it. A file that cannot be read — no $schema, bad JSON — opens as text with the reason on the status line, and :set editor bidata on it keeps the view up with that error as its one row, so :bi init, :bi schema and :bi migrate can mend it — see Editing data.

Errors block the view and open the file as text with the error marked; warnings — a number outside its range, a dangling ref, an unknown key left by a rename — ride on the row and never block editing or saving. Unknown keys are preserved on write; bi does not drop data it does not understand.