alktype/CHANGELOG.md

Changelog

All notable changes to this crate are documented here. The format is based on Keep a Changelog, and this crate adheres to Semantic Versioning.

0.2.0 - 2026-08-17

A breaking release that replaces the v0.1.0 AlkType:* custom-keyword JSON Schema format with BAST (Binary Abstract Syntax Tree) — a JSON document that describes binary layouts using a kind-based vocabulary with $defs/$ref for composition. BAST is itself a valid JSON Schema instance (it has a meta-schema), making it self-validating, editor-friendly, and trivially consumable from any language with a JSON parser. The engine works the same way as before: compile a document once into an AlkTypeEngine, then read/write fields at computed offsets and validate bytes/JSON. The pivot was made now because v0.1.0 has no real consumers (≈15 crates.io downloads, mostly bots/scanners), so the custom-keyword wart could be removed cleanly.

Breaking changes

• Schema format. The v0.1.0 AlkType:* custom-keyword JSON Schema format ({ "AlkType:Struct": true, "fields": [...] }) is removed. Schemas are now BAST documents: { "$defs": { "<TypeName>": { "kind": "struct", "fields": [...] } } }. The kind-based vocabulary covers 18 binary kinds (integers, floats, bytes, string, struct, union, enum, array, etc.).
• AlkTypeEngine::compile signature. Now takes (bast_doc: &Value, root_name: &str, mode: LayoutMode, json_schema: Option<&Value>). The root type name is a required parameter — it selects which $defs entry is the top-level type (previously the root was implicit from the single top-level schema object).
• Builder API output. Definitions/Schema/Discriminator now produce BAST JSON via Definitions::build_doc(name, schema). The builder method names are unchanged; only the emitted JSON shape changed. Schema::struct_() produces a BAST struct; Schema::object() produces a standard JSON Schema (for the validate_json path).
• Validation split. v0.1.0 used a single jsonschema validator with 19 custom AlkType:* keywords for both bytes and JSON validation. 0.2.0 splits this into two independent paths:
  • validate_bytes uses a new BAST-native validator (bast_validation) — a recursive walker over the BAST type tree.
  • validate_json / is_valid_json use a standard jsonschema::Validator built from a consumer-provided JSON Schema (passed to compile as the json_schema parameter). No custom keywords; BAST is not involved — BAST describes bytes, not JSON shape. Both paths return AlkTypeError::Validation with a uniform jsonschema::ValidationError<'static> payload.
• Removed. The v0.1.0 custom-keyword accessor layer (AlkTypeKind::FromStr, parse_*, resolve_ref*, DiscriminatorKind) is removed. The BAST parser (bast module) exposes a cleaner typed surface (BastDoc/BastDef/BastStruct/ BastField/BastType/etc.) that borrows from the source serde_json::Value without cloning field data.
• Public module surface. New public modules: bast, bast_meta, bast_validation, builder, materialize. The schema module is retained but now holds only Endian/AlkTypeKind/VariableEncoding (the binary-kind vocabulary); the v0.1.0 custom-keyword machinery is gone.

Additions

• BAST meta-schema. Embedded in the crate as BAST_META_SCHEMA (re-exported from the crate root) and published at https://alk.dev/bast/v1/schema. BAST documents are validated against it at compile time (AlkTypeEngine::compile calls validate_bast_doc before parsing).
• materialize module. Materializes a serde_json::Value tree from a binary buffer by walking the BAST typed tree. Used by AlkTypeEngine::validate_bytes (ADR-010).
• Builder for JSON Schemas. Schema::object() produces a standard JSON Schema object (for the validate_json path), complementing Schema::struct_() which produces a BAST struct (for the bytes path). One builder, two output shapes — the method name selects which.

Bug fixes vs v0.1.0

• Enum index bounds are now checked. The v0.1.0 validator had a dead constraint: enum variant indices were never bounds-checked against values.len(). The BAST-native validator enforces it (validate_enum checks idx < values.len()).
• Offset-indirect, field-level endian, and aligned materialization bugs found during review #003 are fixed.

Non-breaking improvements

• $ref is restricted to #/$defs/<name> — one hash lookup, no normalize_refs pass (the v0.1.0 engine needed one).
• Schemas remain untrusted input: every engine path that walks a BAST document returns Err on a malformed document, never panic!/ unreachable!. Overflow-safe arithmetic (checked_add, usize::try_from) on all offset/count casts.
• Still two dependencies (jsonschema with default-features = false, serde_json with preserve_order), no async, no unsafe, no platform deps, no feature flags. Compiles to wasm32-unknown-unknown.

Upgrade notes

There is no migration path from v0.1.0 AlkType:* schemas — the format is incompatible. Rewrite schemas as BAST documents (the builder API produces them; see the README usage example) and update compile calls to pass the root type name and the optional JSON Schema. The read/write/validate API surface (read_field, write_field, sequential_reader, validate_bytes, validate_json, is_valid_json) is unchanged.

0.1.0 - 2025-11-10

Initial crates.io release. Custom-keyword JSON Schema format (AlkType:*), single jsonschema validator for both bytes and JSON, AlkTypeEngine with packed/aligned layout modes, builder API producing serde_json::Value.