Crate axgf_rs 

axgf-rs — Reference implementation of the Axiom Genealogy Format (AXGF) 1.0

This crate is the canonical Rust implementation of the AXGF specification. It provides a stateless, data-oriented boundary: every public function takes JSON strings or bytes and returns a single uniform boundary::envelope::Envelope serialized to JSON. No native Rust types cross the boundary — this is what makes language bindings mechanical.

Design contract (V1)

1. Stateless & immutable. Every operation takes a bundle in, returns a new bundle out. No sessions, handles, or hidden mutation.
2. Flat JSON is the working form. The on-disk .axgf is a ZIP, but the library converts it to a single flat JSON object for all editing. ZIP is read only by import_bundle and written only by export_bundle.
3. No disk, no graph traversal, no query engine, no rendering in V1. The caller passes bytes; the library never touches the filesystem.
4. Explicit spec-version gating. Every operation checks manifest.axgf against SUPPORTED_SPEC_VERSIONS and refuses unknown versions.
5. Uniform envelope with stable diagnostic codes. Validation is non-blocking: operations may succeed with warnings.
6. Forward compatibility. Unknown fields survive a round-trip untouched.

Module layout

• model — Typed structs for the 8 entity kinds and the manifest. Internal to the library; never crosses the boundary.
• logic — Pure value-core: validation, CRUD, deduplication. Operates on model types, never on raw JSON.
• boundary — The only layer that speaks JSON, ZIP and bytes: envelope type, boundary::flat::FlatBundle, and lifecycle helpers.
• convert — Foreign-format converters (GEDCOM 5.5.1 → AXGF).
• adapters — Thin per-target wrappers (rust, wasm, cffi, mobile) behind feature flags.

Minimal example

Create an empty bundle, add a person, and validate the result. Every function takes and returns JSON, wrapped in a uniform boundary::envelope::Envelope.

use axgf_rs::{add_entity, create_bundle, validate, EntityKind};
use axgf_rs::boundary::envelope::Status;

// 1. Create an empty bundle. `data` is a serde_json::Value; convert to a
//    string for the next call.
let bundle = create_bundle(Some("Karin")).data.to_string();

// 2. Add a minimal person. The library generates a UUID v4 if none given
//    and fills in `type` and `axgf_version`. The envelope's `data` here
//    is `{ "id": <uuid>, "bundle": <updated flat bundle> }`.
let person = r#"{
    "identity": {
        "name":   {"display": "Jean Pierre-Léonard", "components": []},
        "gender": {"value": "M"},
        "is_living": true
    }
}"#;
let added = add_entity(&bundle, EntityKind::Person, person);
assert_eq!(added.status, Status::Ok);

// 3. Structural + semantic validation over the updated bundle. Warnings
//    are non-blocking, so `status == Ok` even if diagnostics are present.
let updated_bundle = added.data["bundle"].to_string();
let checked = validate(&updated_bundle);
assert_eq!(checked.status, Status::Ok);

Command-line binary

The same core is shipped as a standalone axgf executable. The cli Cargo feature is on by default so cargo install axgf-rs produces the binary; each subcommand prints a concise human summary by default and the raw boundary::envelope::Envelope under --json. See docs/CLI.md for the full reference. Library-only consumers can opt out with default-features = false, features = ["gedcom"].

Further reading

• docs/API.md — a longer walk-through of every public function.
• docs/CLI.md — the axgf binary: subcommands, flags, scripting.
• SETUP.md — build instructions and per-target adapter notes.
• AXGF specification — the format itself.

Re-exports

pub use logic::crud::DeletePolicy;

pub use logic::crud::EntityKind;

Modules

adapters

adapters — thin per-target wrappers around the public API

boundary

boundary — the JSON / ZIP / bytes edge of the library

convert

convert — foreign-format ingestion

logic

logic — the value core (validation, CRUD, dedup)

model

model — typed representations of AXGF entities

Constants

CURRENT_SPEC_VERSION

The AXGF specification version this build writes when creating or re-exporting bundles.

SUPPORTED_SPEC_VERSIONS

AXGF specification versions this build understands. Every lifecycle operation verifies manifest.axgf against this set and refuses to proceed on an unrecognized value with a stable UNSUPPORTED_SPEC_VERSION diagnostic.

Functions

add_entity

Add a new entity of the given kind to a flat bundle. A UUID v4 is generated when entity_json.id is missing.

convert_gedcom

Convert a GEDCOM 5.5.1 byte stream to a flat AXGF bundle.

create_bundle

Create a new, empty AXGF bundle as flat JSON.

deduplicate

Run the safe deduplication passes on a flat bundle. Ambiguous merges are flagged with MANUAL_REVIEW_REQUIRED diagnostics rather than performed.

delete_entity

Delete an entity by id, applying the caller’s referential-integrity DeletePolicy.

export_bundle

Export a flat-bundle JSON string to a .axgf ZIP archive.

import_bundle

Import a .axgf ZIP archive (bytes) and return its flat-bundle JSON.

inspect

Return manifest and computed stats for the given flat bundle without modifying it.

update_entity

Update an existing entity in a flat bundle, keyed by id.

validate

Validate a flat bundle structurally (JSON Schema) and semantically (dangling refs, cycles, chronology, duplicate unique refs). Warnings do not cause a non-ok status.