csdif-core

= 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