1. Creating a BEJSON 104a Document
The create104a function within lib_bejson_Core_bejson_bejson.js facilitates the structured generation of BEJSON 104a documents. This function correctly initializes all mandatory top-level keys and allows for the seamless inclusion of custom metadata as an optional parameter, aligning with the 104a specification.
The following example demonstrates creating a configuration document, similar to the "Global Application Configuration" discussed in Chapter 4, complete with custom headers and primitive data.
// File: example_create_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
// Define the fields for the configuration document.
// BEJSON 104a strictly enforces primitive types: 'string', 'integer', 'number', 'boolean'.
const configFields = [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" }, // Value stored as string for flexibility
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
];
// Define the initial records.
// Positional integrity requires all rows to match the field count,
// using 'null' for absent data if necessary.
const configValues = [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1]
];
// Define custom top-level headers for the 104a document.
// These are standard PascalCase headers as per 104a convention.
const customMetadata = {
AppName: "TelemetryService",
ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging",
LastUpdateTimestamp: new Date().toISOString()
};
// Create the BEJSON 104a document using the create104a helper.
const telemetryConfig = BEJSON.create104a(
"AppSetting", // Records_Type (single string for 104a)
configFields, // Array of field definitions
configValues, // Array of data records
customMetadata // Optional custom headers
);
console.log("Successfully created BEJSON 104a document:\n");
console.log(JSON.stringify(telemetryConfig, null, 2));
/*
Expected output (timestamp will vary):
Successfully created BEJSON 104a document:
{
"Format": "BEJSON",
"Format_Version": "104a",
"Format_Creator": "Elton Boehnen",
"Records_Type": [
"AppSetting"
],
"AppName": "TelemetryService",
"ConfigVersion": "1.2.0",
"DeploymentEnvironment": "Staging",
"LastUpdateTimestamp": "2026-11-01T12:34:56.789Z",
"Fields": [
{
"name": "setting_key",
"type": "string"
},
{
"name": "setting_value",
"type": "string"
},
{
"name": "is_enabled",
"type": "boolean"
},
{
"name": "priority",
"type": "integer"
}
],
"Values": [
[
"feature_flag_x",
"true",
true,
1
],
[
"api_base_url",
"https://api.example.com/v1",
true,
0
],
[
"cache_duration_minutes",
"60",
false,
2
],
[
"max_retries",
"3",
true,
1
]
]
}
*/
This output confirms that create104a correctly populates the mandatory keys, integrates the custom metadata, and structures the Fields and Values arrays according to the BEJSON 104a specification. The ability to include custom, context-specific headers is a primary advantage of the 104a format for configuration files and manifests.
2. Accessing and Manipulating Data in BEJSON 104a
Data manipulation in BEJSON 104a documents relies on their tabular structure. Accessing data by field name requires determining its positional index within the Fields array, which then allows for direct, efficient array access within the Values array. The getFieldIndex function from lib_bejson_Core_bejson_bejson.js provides this capability, leveraging the O(1) field map caching mechanism from lib_bejson_core.js for optimal performance, as demonstrated in bejson_cache.test.js.
a. Retrieving Values by Field Name
// File: example_access_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
// Assume 'telemetryConfig' is the BEJSON 104a document created previously.
// For demonstration, we re-declare it here:
const telemetryConfig = {
Format: "BEJSON", Format_Version: "104a", Format_Creator: "Elton Boehnen",
Records_Type: ["AppSetting"], AppName: "TelemetryService", ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging", LastUpdateTimestamp: "2026-11-01T12:34:56.789Z",
Fields: [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" },
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
],
Values: [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1]
]
};
// Get the index for the 'setting_key' and 'setting_value' fields.
const keyIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_key");
const valueIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_value");
const isEnabledIndex = BEJSON.getFieldIndex(telemetryConfig, "is_enabled");
const priorityIndex = BEJSON.getFieldIndex(telemetryConfig, "priority");
if (keyIndex === -1 || valueIndex === -1 || isEnabledIndex === -1 || priorityIndex === -1) {
console.error("One or more critical fields not found in the document schema.");
process.exit(1);
}
console.log(`Index of 'setting_key': ${keyIndex}`);
console.log(`Index of 'setting_value': ${valueIndex}`);
// Iterate and display all settings.
console.log("\nCurrent Telemetry Settings:");
telemetryConfig.Values.forEach(row => {
const key = row[keyIndex];
const value = row[valueIndex];
const enabled = row[isEnabledIndex];
const priority = row[priorityIndex];
console.log(`- Key: ${key}, Value: ${value}, Enabled: ${enabled}, Priority: ${priority}`);
});
// Retrieve a specific setting.
const baseUrlSetting = telemetryConfig.Values.find(
row => row[keyIndex] === "api_base_url"
);
if (baseUrlSetting) {
console(`\nAPI Base URL: ${baseUrlSetting[valueIndex]}`); // Output: API Base URL: https://api.example.com/v1
} else {
console.log("\n'api_base_url' setting not found.");
}
b. Updating Values
Updating a value involves locating the specific record and then modifying the data at the appropriate field index.
// File: example_update_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
// Using the 'telemetryConfig' from the previous example.
const telemetryConfig = {
Format: "BEJSON", Format_Version: "104a", Format_Creator: "Elton Boehnen",
Records_Type: ["AppSetting"], AppName: "TelemetryService", ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging", LastUpdateTimestamp: "2026-11-01T12:34:56.789Z",
Fields: [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" },
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
],
Values: [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1]
]
};
const keyIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_key");
const valueIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_value");
const isEnabledIndex = BEJSON.getFieldIndex(telemetryConfig, "is_enabled");
// Update 'api_base_url'
const baseUrlRow = telemetryConfig.Values.find(row => row[keyIndex] === "api_base_url");
if (baseUrlRow) {
baseUrlRow[valueIndex] = "https://new.api.example.com/v2_beta";
console.log(`Updated 'api_base_url' to: ${baseUrlRow[valueIndex]}`);
}
// Disable 'cache_duration_minutes'
const cacheSettingRow = telemetryConfig.Values.find(row => row[keyIndex] === "cache_duration_minutes");
if (cacheSettingRow) {
cacheSettingRow[isEnabledIndex] = false;
console.log(`'cache_duration_minutes' enabled status: ${cacheSettingRow[isEnabledIndex]}`);
}
console.log("\nTelemetry Settings after update:");
telemetryConfig.Values.forEach(row => {
console.log(`- Key: ${row[keyIndex]}, Value: ${row[valueIndex]}, Enabled: ${row[isEnabledIndex]}`);
});
c. Adding and Deleting Records
New records are appended to the Values array, strictly maintaining positional integrity by matching the Fields array length and using null for absent data. Deleting records involves filtering or splicing the Values array.
// File: example_add_delete_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
// Using the 'telemetryConfig' from previous examples.
const telemetryConfig = {
Format: "BEJSON", Format_Version: "104a", Format_Creator: "Elton Boehnen",
Records_Type: ["AppSetting"], AppName: "TelemetryService", ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging", LastUpdateTimestamp: "2026-11-01T12:34:56.789Z",
Fields: [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" },
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
],
Values: [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1]
]
};
const keyIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_key");
console.log("Initial record count:", telemetryConfig.Values.length); // Output: Initial record count: 4
// Add a new setting.
const newSetting = ["max_connections", "100", true, 3];
telemetryConfig.Values.push(newSetting);
console.log("Record count after adding:", telemetryConfig.Values.length); // Output: Record count after adding: 5
console.log("Newly added setting:", telemetryConfig.Values[telemetryConfig.Values.length - 1]);
// Delete a setting (e.g., 'max_retries').
// Create a new array, filtering out the unwanted record.
telemetryConfig.Values = telemetryConfig.Values.filter(
row => row[keyIndex] !== "max_retries"
);
console.log("Record count after deleting 'max_retries':", telemetryConfig.Values.length); // Output: Record count after deleting 'max_retries': 4
console.log("\nTelemetry Settings after add/delete operations:");
telemetryConfig.Values.forEach(row => {
console.log(`- Key: ${row[keyIndex]}, Value: ${row[BEJSON.getFieldIndex(telemetryConfig, "setting_value")]}`);
});
d. Querying Records
The BEJSON.query function, provided by lib_bejson_Core_bejson_bejson.js, simplifies filtering records based on a specific field's value.
// File: example_query_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
// Using the 'telemetryConfig' from previous examples.
const telemetryConfig = {
Format: "BEJSON", Format_Version: "104a", Format_Creator: "Elton Boehnen",
Records_Type: ["AppSetting"], AppName: "TelemetryService", ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging", LastUpdateTimestamp: "2026-11-01T12:34:56.789Z",
Fields: [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" },
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
],
Values: [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1],
["debug_mode", "false", false, 5]
]
};
const keyIndex = BEJSON.getFieldIndex(telemetryConfig, "setting_key");
// Query all enabled settings.
const enabledSettings = BEJSON.query(telemetryConfig, "is_enabled", true);
console.log("Enabled Settings:");
enabledSettings.forEach(row => console.log(`- ${row[keyIndex]} (Value: ${row[BEJSON.getFieldIndex(telemetryConfig, "setting_value")]})`));
// Query all disabled settings.
const disabledSettings = BEJSON.query(telemetryConfig, "is_enabled", false);
console.log("\nDisabled Settings:");
disabledSettings.forEach(row => console.log(`- ${row[keyIndex]} (Value: ${row[BEJSON.getFieldIndex(telemetryConfig, "setting_value")]})`));
/*
Expected output:
Enabled Settings:
- feature_flag_x (Value: true)
- api_base_url (Value: https://api.example.com/v1)
- max_retries (Value: 3)
Disabled Settings:
- cache_duration_minutes (Value: 60)
- debug_mode (Value: false)
*/
3. Validation of BEJSON 104a Documents
The robust validation of BEJSON documents is critical for maintaining data integrity. While lib_bejson_Core_bejson_bejson.js offers a basic isValid check, comprehensive structural and type validation for BEJSON 104a is performed by lib_bejson_validator.js. This library enforces all universal BEJSON requirements and 104a-specific rules, such as mandatory primitive types and strict positional integrity.
For the purpose of these examples, we will use a conceptual validate104a function that mirrors the key checks performed by lib_bejson_validator.js, including the error codes specified in lib_bejson_errors.js.
a. Conceptual validate104a Function
// File: conceptual_bejson_validator.js (Illustrative representation of lib_bejson_validator.js for 104a)
// Error codes, as defined in lib_bejson_errors.js
const ERROR_CODES = {
E_INVALID_JSON: 1,
E_MISSING_MANDATORY_KEY: 2,
E_INVALID_FORMAT_VERSION: 3,
E_INVALID_CREATOR: 4,
E_INVALID_RECORDS_TYPE: 5,
E_INVALID_FIELDS_ARRAY: 6,
E_INVALID_VALUES_ARRAY: 7,
E_INVALID_FIELD_DEFINITION: 8,
E_INVALID_FIELD_TYPE: 9, // Specifically for 104a's primitive type constraint
E_POSITIONAL_INTEGRITY_VIOLATION: 10,
E_INVALID_ROW_TYPE: 11,
E_INVALID_TYPE_MISMATCH: 12
};
function validate104a_conceptual(doc) {
// 1. Universal BEJSON Requirements
const mandatoryKeys = ["Format", "Format_Version", "Format_Creator", "Records_Type", "Fields", "Values"];
for (const key of mandatoryKeys) {
if (!(key in doc)) {
throw new Error(`[${ERROR_CODES.E_MISSING_MANDATORY_KEY}] Mandatory key '${key}' is missing.`);
}
}
if (doc.Format !== "BEJSON") throw new Error(`[${ERROR_CODES.E_INVALID_JSON}] 'Format' must be 'BEJSON'.`);
if (doc.Format_Version !== "104a") throw new Error(`[${ERROR_CODES.E_INVALID_FORMAT_VERSION}] 'Format_Version' must be '104a'.`);
if (doc.Format_Creator !== "Elton Boehnen") throw new Error(`[${ERROR_CODES.E_INVALID_CREATOR}] 'Format_Creator' must be 'Elton Boehnen'.`);
if (!Array.isArray(doc.Records_Type) || doc.Records_Type.length !== 1 || typeof doc.Records_Type[0] !== 'string') {
throw new Error(`[${ERROR_CODES.E_INVALID_RECORDS_TYPE}] 'Records_Type' must be an array with exactly one string.`);
}
if (!Array.isArray(doc.Fields) || doc.Fields.length === 0) throw new Error(`[${ERROR_CODES.E_INVALID_FIELDS_ARRAY}] 'Fields' array is invalid or empty.`);
if (!Array.isArray(doc.Values)) throw new Error(`[${ERROR_CODES.E_INVALID_VALUES_ARRAY}] 'Values' array is invalid.`);
// 2. BEJSON 104a Specific: Primitive Types Only
const primitiveTypes = ["string", "integer", "number", "boolean"];
for (const field of doc.Fields) {
if (!field.name || typeof field.name !== 'string') throw new Error(`[${ERROR_CODES.E_INVALID_FIELD_DEFINITION}] Field missing 'name' or it's not a string.`);
if (!field.type || typeof field.type !== 'string' || !primitiveTypes.includes(field.type)) {
throw new Error(`[${ERROR_CODES.E_INVALID_FIELD_TYPE}] Field '${field.name}' has invalid or non-primitive type '${field.type}'. BEJSON 104a only allows primitive types.`);
}
}
// 3. Positional Integrity and Type Consistency of Values
const expectedFieldCount = doc.Fields.length;
for (let i = 0; i < doc.Values.length; i++) {
const row = doc.Values[i];
if (!Array.isArray(row)) throw new Error(`[${ERROR_CODES.E_INVALID_ROW_TYPE}] Value row ${i} is not an array.`);
if (row.length !== expectedFieldCount) {
throw new Error(`[${ERROR_CODES.E_POSITIONAL_INTEGRITY_VIOLATION}] Row ${i} has ${row.length} values, but ${expectedFieldCount} fields are defined.`);
}
for (let j = 0; j < expectedFieldCount; j++) {
const declaredType = doc.Fields[j].type;
const actualValue = row[j];
if (actualValue === null) continue; // Null is always allowed for padding
if (declaredType === "string" && typeof actualValue !== "string") {
throw new Error(`[${ERROR_CODES.E_INVALID_TYPE_MISMATCH}] Row ${i}, field '${doc.Fields[j].name}' expects string, got ${typeof actualValue}.`);
}
if ((declaredType === "integer" || declaredType === "number") && typeof actualValue !== "number") {
throw new Error(`[${ERROR_CODES.E_INVALID_TYPE_MISMATCH}] Row ${i}, field '${doc.Fields[j].name}' expects number/integer, got ${typeof actualValue}.`);
}
if (declaredType === "boolean" && typeof actualValue !== "boolean") {
throw new Error(`[${ERROR_CODES.E_INVALID_TYPE_MISMATCH}] Row ${i}, field '${doc.Fields[j].name}' expects boolean, got ${typeof actualValue}.`);
}
}
}
return true; // Document is valid if no errors are thrown
}
module.exports = { validate104a_conceptual };
b. Demonstrating Validation
This example uses the conceptual validate104a_conceptual function to check a valid 104a document and then deliberately introduces errors to demonstrate how validation failures are reported.
// File: example_validation_104a.js
const BEJSON = require('./lib_bejson_Core_bejson_bejson.js');
const { validate104a_conceptual } = require('./conceptual_bejson_validator.js'); // Our conceptual validator
// A valid BEJSON 104a document
const validTelemetryConfig = {
Format: "BEJSON", Format_Version: "104a", Format_Creator: "Elton Boehnen",
Records_Type: ["AppSetting"], AppName: "TelemetryService", ConfigVersion: "1.2.0",
DeploymentEnvironment: "Staging", LastUpdateTimestamp: "2026-11-01T12:34:56.789Z",
Fields: [
{ name: "setting_key", type: "string" },
{ name: "setting_value", type: "string" },
{ name: "is_enabled", type: "boolean" },
{ name: "priority", type: "integer" }
],
Values: [
["feature_flag_x", "true", true, 1],
["api_base_url", "https://api.example.com/v1", true, 0],
["cache_duration_minutes", "60", false, 2],
["max_retries", "3", true, 1],
["debug_mode", "false", false, null] // null is allowed for positional integrity
]
};
console.log("--- Validating a correct BEJSON 104a document ---");
try {
validate104a_conceptual(validTelemetryConfig);
console.log("SUCCESS: Document is valid.");
} catch (error) {
console.error("FAILURE: Document reported as invalid:", error.message);
}
console.log("\n--- Testing invalid scenarios ---");
// Scenario 1: Missing mandatory key (e.g., 'Values')
const invalidDocMissingValues = { ...validTelemetryConfig };
delete invalidDocMissingValues.Values;
try {
validate104a_conceptual(invalidDocMissingValues);
} catch (error) {
console.log(`CAUGHT ERROR (Missing Key): ${error.message}`);
}
// Scenario 2: Non-primitive type in 'Fields' (e.g., 'object' or 'array')
const invalidDocNonPrimitiveField = JSON.parse(JSON.stringify(validTelemetryConfig));
invalidDocNonPrimitiveField.Fields.push({ name: "complex_settings", type: "object" }); // 104a forbids complex types
invalidDocNonPrimitiveField.Values.forEach(row => row.push(null)); // Maintain row length for now
try {
validate104a_conceptual(invalidDocNonPrimitiveField);
} catch (error) {
console.log(`CAUGHT ERROR (Non-primitive Field Type): ${error.message}`);
}
// Scenario 3: Positional integrity violation (row length mismatch)
const invalidDocPositionalViolation = JSON.parse(JSON.stringify(validTelemetryConfig));
invalidDocPositionalViolation.Values[0].pop(); // Remove a value from the first record
try {
validate104a_conceptual(invalidDocPositionalViolation);
} catch (error) {
console.log(`CAUGHT ERROR (Positional Integrity): ${error.message}`);
}
// Scenario 4: Type mismatch for a value (e.g., boolean where string is expected)
const invalidDocTypeMismatch = JSON.parse(JSON.stringify(validTelemetryConfig));
const valueIdx = BEJSON.getFieldIndex(invalidDocTypeMismatch, "setting_value");
invalidDocTypeMismatch.Values[0][valueIdx] = false; // "true" (string) -> false (boolean)
try {
validate104a_conceptual(invalidDocTypeMismatch);
} catch (error) {
console.log(`CAUGHT ERROR (Type Mismatch): ${error.message}`);
}
// Scenario 5: Records_Type is not an array of exactly one string
const invalidDocRecordsType = JSON.parse(JSON.stringify(validTelemetryConfig));
invalidDocRecordsType.Records_Type = ["AppSetting", "AnotherType"]; // Too many elements
try {
validate104a_conceptual(invalidDocRecordsType);
} catch (error) {
console.log(`CAUGHT ERROR (Invalid Records_Type): ${error.message}`);
}
/*
Expected output (error codes match conceptual_bejson_validator.js):
--- Validating a correct BEJSON 104a document ---
SUCCESS: Document is valid.
--- Testing invalid scenarios ---
CAUGHT ERROR (Missing Key): [2] Mandatory key 'Values' is missing.
CAUGHT ERROR (Non-primitive Field Type): [9] Field 'complex_settings' has invalid or non-primitive type 'object'. BEJSON 104a only allows primitive types.
CAUGHT ERROR (Positional Integrity): [10] Row 0 has 3 values, but 4 fields are defined.
CAUGHT ERROR (Type Mismatch): [12] Row 0, field 'setting_value' expects string, got boolean.
CAUGHT ERROR (Invalid Records_Type): [5] 'Records_Type' must be an array with exactly one string.
*/
These examples demonstrate how core libraries facilitate working with BEJSON 104a. The create104a function ensures initial adherence to the format, while getFieldIndex and query provide efficient data access and retrieval. Crucially, the validation mechanisms, as conceptually presented by validate104a_conceptual and executed by lib_bejson_validator.js in a production environment, rigorously enforce 104a's specific constraints regarding primitive types and structural integrity. This combination of tools ensures that BEJSON 104a documents remain consistent, predictable, and reliable for their designated roles in configuration and metadata management. The direct application of these libraries, such as BEJSON_Switch.BEJSON.create104a used in lib_bejson_Core_bejson_assets.js for asset registries, further underscores their practical utility within the BEJSON ecosystem.
