BEJSON + MFDB Crash Course

Document Version 21 · MFDB Spec Version 1.31 · BEJSON Formats: 104 · 104a · 104db

Format Creator: Elton Boehnen · https://boehnenelton2024.pages.dev

BEJSON Crash Course

(v104, 104a, 104db)

VERSION 1

BEJSON is a strict, self-describing tabular data format built on JSON. A key feature is positional integrity, meaning the field order within Fields precisely matches the value order in each record found in Values. This design allows for index-based access (eliminating key lookups), rapid parsing, strong typing, and integrated schema validation without the need for external files.

All BEJSON versions mandate the presence of these top-level keys:

{

"Format": "BEJSON",

"Format_Creator": "Elton Boehnen",

"Records_Type": [ ... ],

"Fields": [ ... ],

"Values": [ [ ... ], [ ... ], ... ]

}

Common Rules (All Versions)

The Fields key must contain an array of objects, structured as follows:

• Each record within Values must contain an exact number of elements matching the number of entries in Fields.
• Optional or missing values should be represented by null to maintain length and position.
• Duplicate field names are not permitted.
• null is considered a valid value for any declared type.

Version Differences

BEJSON 104 – Single Record Type, Full Types

• Records_Type: An array containing exactly one string, which represents the entity name.
• No custom top-level keys are allowed, beyond the six mandatory ones.
• Exception: Parent_Hierarchy is an optional, built-in key permitted in 104. Its interpretation is intentionally flexible; applications can use it as needed (e.g., to indicate a folder path, an index hierarchy, or any logical grouping).
• Supports complex data types, including array and object.
• Ideal for homogeneous, high-throughput data such as logs, metrics, or archives.

Example:

{

"Format": "BEJSON",

"Format_Version": "104",

"Format_Creator": "Elton Boehnen",

"Records_Type": ["SensorReading"],

"Fields": [

{"name": "sensor_id", "type": "string"},

{"name": "timestamp", "type": "string"},

{"name": "temperature", "type": "number"},

{"name": "tags", "type": "array"}

],

"Values": [

["S001", "2026-01-10T12:00:00Z", 23.5, ["indoor","ground"]],

["S002", "2026-01-10T12:00:00Z", 19.8, null]

]

}

BEJSON 104a – Primitive Types + Custom Metadata

• Records_Type: Must be exactly one string.
• Custom top-level keys are allowed, but only for file-level metadata, never for per-record data.
• Fields are restricted to primitive types only: string, integer, number, boolean.
• Custom keys should adhere to PascalCase naming conventions and must not conflict with the six mandatory keys.
• Best suited for configuration files, health checks, or simple log data.

Example:

{

"Format": "BEJSON",

"Format_Version": "104a",

"Format_Creator": "Elton Boehnen",

"Server_ID": "WEB-01",

"Environment": "Production",

"Retention_Days": 90,

"Records_Type": ["ConfigParam"],

"Fields": [

{"name": "key", "type": "string"},

{"name": "value", "type": "string"},

{"name": "sensitive", "type": "boolean"}

],

"Values": [

["db_host", "prod-db-01", true],

["max_threads", "32", false]

]

}

BEJSON 104db – Multi-Entity Lightweight Database

• Records_Type: An array containing two or more unique strings, each representing an entity name.
• No custom top-level keys are allowed.
• The very first field in the Fields array must be: {"name": "Record_Type_Parent", "type": "string"}.
• The value at position 0 in every record within Values must precisely match one of the entries in Records_Type.
• Every field (except Record_Type_Parent itself) must include a "Record_Type_Parent" property, assigning it to a specific entity. Fields lacking this assignment are invalid in 104db. There are no "common fields" shared across all entities.
• Fields that are not applicable to a given entity must be set to null.
• Supports complex data types.
• Enables relationships through shared ID fields (acting as logical Primary Key/Foreign Key).
• Convention: It is recommended practice to use the _fk suffix on foreign key fields (e.g., owner_user_id_fk) to indicate relationships to automated mapping tools. This is a convention and not strictly enforced by the BEJSON specification.

Example:

{

"Format": "BEJSON",

"Format_Version": "104db",

"Format_Creator": "Elton Boehnen",

"Records_Type": ["User", "Item"],

"Fields": [

{"name": "Record_Type_Parent", "type": "string"},

{"name": "created", "type": "string", "Record_Type_Parent": "User"},

{"name": "user_id", "type": "string", "Record_Type_Parent": "User"},

{"name": "username", "type": "string", "Record_Type_Parent": "User"},

{"name": "created_at", "type": "string", "Record_Type_Parent": "Item"},

{"name": "item_id", "type": "string", "Record_Type_Parent": "Item"},

{"name": "name", "type": "string", "Record_Type_Parent": "Item"},

{"name": "owner_user_id_fk", "type": "string", "Record_Type_Parent": "Item"}

],

"Values": [

["User", "2026-01-01", "U01", "alice", null, null, null, null],

["User", "2026-01-02", "U02", "bob", null, null, null, null],

["Item", null, null, null, "2026-01-10", "I01", "Report A", "U01"],

["Item", null, null, null, "2026-01-10", "I02", "Report B", "U02"]

]

}

Note: Because the "created" field is exclusively assigned to "User", "Item" records must set it to null. Conversely, "User" records must null out "created_at". If a timestamp field is desired across multiple entities, it must be defined separately for each entity with consistent naming, or the duplication must be accepted. Each field is strictly owned by one entity.

In certain cases 104db might be superior to SQL lite:

• When you need a relational database that doesn't need to hold 10,000 records or more.
• When you want an LLM to be able to directly read the database and modify it as if it were a text file.

Limitations

• Due to the requirement of holding positional integrity and using null padding, the 104db file grows exponentially with each new field and each new record and at a certain point comes unviable, and that the best usage for 104DB is for limited size, single file quick access to relational data that is readable by any programming language natively and to AI.

Validation Summary

A BEJSON document is considered valid if it adheres to the following criteria:

• Valid JSON syntax.
• All six mandatory top-level keys are present with their correct values.
• Format_Creator must be precisely "Elton Boehnen".
• The Fields structure is correct, and no duplicate field names exist.
• The length of every record in Values equals the length of the Fields array.
• The type of each value matches its declared type in Fields (with null always being an allowed value).
• Version-specific rules:
• 104: Requires a single record type, allows complex types, and forbids custom headers (except for Parent_Hierarchy).
• 104a: Requires a single record type, allows only primitive types, and permits custom headers for file-level metadata (these must be PascalCase and not conflict with the six mandatory keys).
• 104db: Requires two or more record types, mandates that every field (except the Record_Type_Parent discriminator field itself) has a Record_Type_Parent assignment, forbids custom headers, and requires null for non-applicable fields.

Best Practices

• Use snake_case for field names.
• Use PascalCase for custom headers in BEJSON 104a.
• Append new fields only to the end of the Fields array to preserve positional integrity for existing parsers.
• Use null (rather than an empty array or object) for truly missing data, unless an empty state carries specific meaning.
• Manage your application schema version independently from Format_Version:
• For 104a / 104db: Use a custom header like Schema_Version (e.g., "v1.0").
• For 104: Custom headers are forbidden; embed the version within the Records_Type string (e.g., ["SensorReading_v1_0"]) or manage it externally.
• Schema changes: Appending fields is generally safe (minor change). Removing or retyping a field constitutes a breaking change (major change).
• For large datasets, consider splitting data into multiple complete BEJSON files.
• Encrypt sensitive files both at rest and during transit.
• In 104db, use the _fk suffix on foreign key fields (this is a convention, not enforced by the specification).
• The Event/Audit entity pattern: In 104db, define a dedicated "Event" entity within Records_Type to implement audit trails. Link it to other entities using fields like related_entity_id_fk, and store before/after state in a change_details field (of type object).

Summary of Version Capabilities

\* Parent_Hierarchy is an optional, built-in exception for BEJSON 104.

This document comprehensively covers all essential rules and provides examples necessary to fully understand, generate, validate, and effectively use any BEJSON variant.

https://boehnenelton2024.pages.dev