axgf-rs 0.2.0

Reference implementation of the Axiom Genealogy Format (AXGF) 1.0 — a stateless JSON-boundary library for creating, validating, importing, exporting, and converting genealogy bundles (GEDCOM 5.5.1 supported).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

// SPDX-License-Identifier: Apache-2.0
//! Typed representation of the AXGF [`Family`] entity, mirroring
//! `#/$defs/family` in the schema and SPEC §4.2.

use serde::{Deserialize, Serialize};

use super::common::{AxgfDate, BaseEntity, DocumentLink, Extra};

/// A person's role in a family union (typically `spouse`).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UnionPerson {
    /// Referenced [`crate::model::person::Person`] UUID.
    pub person_id: String,
    /// Role of that person (e.g. `spouse`, `witness`).
    pub role: String,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}

/// Optional start date/place for a union. Mirrors `family.union.start`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct UnionStart {
    /// Date of the union.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub date: Option<AxgfDate>,
    /// Referenced [`crate::model::place::Place`] UUID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub place_id: Option<String>,
    /// Referenced first-class [`crate::model::event::Event`] UUID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub event_id: Option<String>,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}

/// Optional end date/reason for a union. Mirrors `family.union.end`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct UnionEnd {
    /// Date the union ended.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub date: Option<AxgfDate>,
    /// Reason (`death_of_spouse`, `divorce`, `separation`, `annulment`, …).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// Free-form note.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}

/// The union block on a family. Mirrors `family.union`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Union {
    /// Union kind (`marriage`, `civil_union`, `cohabitation`,
    /// `religious_only`, `polygamous`, `unknown`).
    #[serde(rename = "type")]
    pub kind: String,
    /// Status (`active`, `ended_by_death`, …).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    /// Persons taking part in the union (at least one spouse).
    pub persons: Vec<UnionPerson>,
    /// Optional start date/place.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub start: Option<UnionStart>,
    /// Optional end date/reason.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub end: Option<UnionEnd>,
    /// Confidence in \[0.0, 1.0\].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub confidence: Option<f64>,
    /// Referenced [`crate::model::source::Source`] UUID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_id: Option<String>,
    /// Forward-compatible extras — captures polygamous-only fields
    /// (`primary_person_id`, `unions[]`) as-is.
    #[serde(flatten)]
    pub extra: Extra,
}

/// A child entry inside a family. Mirrors an item of `family.children[]`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FamilyChild {
    /// Referenced [`crate::model::person::Person`] UUID.
    pub person_id: String,
    /// Birth order within the family (1-based).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub birth_order: Option<i32>,
    /// Confidence in \[0.0, 1.0\].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub confidence: Option<f64>,
    /// Free-form note (e.g. adoption pedigree).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}

/// AI metadata attached to a Family. Mirrors `family.ai`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FamilyAi {
    /// Relative path to the Markdown vault page for this family.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vault_page: Option<String>,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}

/// A Family entity. See SPEC §4.2 for the full field-by-field contract.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Family {
    /// Base entity fields.
    #[serde(flatten)]
    pub base: BaseEntity,
    /// Human-readable family name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Short description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// The union defining the family.
    pub union: Union,
    /// Children of the union.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub children: Vec<FamilyChild>,
    /// Documents attached to this family.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub documents: Vec<DocumentLink>,
    /// Free-form notes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub notes: Option<String>,
    /// AI metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ai: Option<FamilyAi>,
    /// Forward-compatible extras.
    #[serde(flatten)]
    pub extra: Extra,
}