nahpu_dwc 0.4.0

A utility crate for mapping and converting Nahpu project data into Darwin Core JSON format.
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

# nahpu_dwc

A utility crate for mapping and converting Nahpu project data into the Darwin Core (DwC) JSON format. It automatically pulls the Nahpu drift database schema and maps its struct fields natively into the `dwc` and `dcterms` namespaces.

## Example Usage

```rust
use nahpu_dwc::export::json::convert_to_dwc_json;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct DummySite {
    site_id: String,
    country: String,
}

fn main() {
    let site = DummySite {
        site_id: "S1".to_string(),
        country: "USA".to_string(),
    };

    // Convert the struct to a Darwin Core mapped JSON
    let result = convert_to_dwc_json("site", &site).unwrap();
    
    // Output: {"dwc:locationID": "S1", "dwc:country": "USA"}
    println!("{}", result);
}
```

### Darwin Core specimen bundles

`package` creates the two NAHPU bundle formats from a JSON specimen snapshot:

- `DarwinCoreArchive` writes an occurrence-core DwC-A ZIP with `meta.xml`,
  `eml.xml`, optional extensions, and bundled media.
- `DarwinCoreDataPackage` writes a relational DwC Data Package as either
  tar.gz or ZIP. The archive contains `datapackage.json`, inline resource
  schemas, primary/foreign keys, EML, and available media at archive root.

TAR.GZ is the default DwC-DP container. ZIP is available as a compatibility
option and is reported in the returned manifest.

The package writer removes optional columns with no values and returns the same
deterministic manifest used by the NAHPU Bundle Project screen.

### Simple Darwin Core XML Export

To natively export an array of structs into the flat XML format compliant with the [Simple Darwin Core specification](https://dwc.tdwg.org/xml/), you can use `export_to_dwc_xml`:

```rust
use nahpu_dwc::export::xml::export_to_dwc_xml;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct DummySite {
    site_id: String,
    country: String,
}

fn main() {
    let sites = vec![
        DummySite { site_id: "S1".to_string(), country: "USA".to_string() }
    ];

    let xml = export_to_dwc_xml("site", &sites).unwrap();
    println!("{}", xml);
}
```

## Darwin Core mappings

The complete NAHPU persistence model and the authoritative NAHPU-to-Darwin
Core field mapping are maintained in the [Persistence data documentation](https://nahpu.app/en/contributing/code/database/).

Version 0.4 maps only fields with an exact semantic equivalent. Callers should
emit fields without an exact mapping in the `nahpu:` namespace. Weight
measurements expose a `measurement_unit_source` so each record can preserve
its selected `g`, `kg`, or `lbs` unit. Verbatim coordinate fields and
determiner identifiers use their current Darwin Core terms.
The audit follows the normative
[Darwin Core List of Terms](https://dwc.tdwg.org/list/); terms that do not exist
there are not generated.

Update that page when the mapper or bundle output changes so the API
implementation and contributor documentation remain aligned.