= csdif-core
:author: Egon Kastelijn
:source-highlighter: coderay
:icons: font
:toc: left
:toclevels: 2
📦 Core library for modeling, validating, and transforming CSDIF data.
== 🧠 Purpose
This crate provides the reusable core logic for working with CSDIF data structures. It is designed to be used by multiple adapters, including:
* `csdif-cli` — command-line exporter
* `csdif-api` — web-based API service
It implements the format and validation layer of the CSDIF RFC, but does not include any I/O, CLI, or web-specific logic.
== 🧱 Design Pattern
This crate represents the **core hexagon** in a hexagonal architecture (Ports & Adapters). It contains:
* Domain models (`Sensor`, `Observation`, `Location`, `CsdifDocument`)
* Validation logic (`validate_document`)
* Transformation and mapping functions
Adapters such as CLI or web-API interact with this crate via public interfaces, but this crate remains unaware of its consumers.
== 📦 Features
* ✅ CSDIF-compliant data structures
* ✅ JSON serialization and deserialization
* ✅ Validation of document structure and semantics
* ✅ Mapping and transformation helpers
* ❌ No I/O, CLI, or async dependencies
== Data Processing Flow
Incoming CSDIF data passes through the following stages:
|===
| Step | Description | Responsible Component | Extensibility
| 1. Transport (Inbound)
| Data arrives via HTTP, MQTT, File, etc.
| csdif-api, csdif-mqtt, csdif-cli
| Add new transport modules
| 2. Format Decoding
| Raw data is decoded from JSON, XML, CSV, etc.
| csdif-core::format
| Implement new FormatDecoder traits
| 3. Schema Interpretation
| Data is interpreted according to the initiative-specific schema
| csdif-mapper-*
| Implement InitiativeMapper trait
| 4. Mapping to SensorML
| Data is converted into the internal SensorML domain model
| csdif-mapper-* + sensorml
| Add new mappers per initiative
| 5. Validation & Processing
| SensorML document is validated and optionally enriched
| sensorml
| Extend domain validation via traits
| 6. Mapping to External Schema (optional)
| SensorML is transformed into a target schema if needed
| csdif-core::mapper::*
| Implement SchemaExporter trait
| 7. Format Encoding
| Data is encoded into JSON, XML, CSV, etc.
| csdif-core::format
| Implement FormatEncoder traits
| 8. Transport (Outbound)
| Data is sent via HTTP, MQTT, File, etc.
| csdif-api, csdif-mqtt, csdif-cli
| Add new transport modules
|===
This layered architecture ensures that new formats, transports, or initiative-specific schemas can be added without modifying the core logic. Each layer is pluggable and testable in isolation.
== 🧪 Testing Philosophy
* All logic is covered by unit tests
* No `unwrap`, `?`, or `panic!` allowed
* Errors are handled explicitly and surfaced clearly
* JSON roundtrip tests ensure format stability
* Validation logic is tested with both valid and invalid cases
== 📄 License
All source files include:
[source,rust]
----
// SPDX-License-Identifier: MIT
----
== 📚 Usage
Add to your `Cargo.toml`:
[source,toml]
----
csdif-core = { git = "https://codeberg.org/meten-natuurlijk/csdif-core", branch = "main" }
----
Or use crates.io once published:
[source,toml]
----
csdif-core = "0.1.0"
----
Then in your code:
[source,rust]
----
use csdif_core::{CsdifDocument, validate_document};
----
== 🔗 Related Crates
* `csdif-cli`: CLI tool for exporting and validating CSDIF documents
* `csdif-api`: Web service exposing CSDIF validation and transformation endpoints