Examples

This page contains practical examples of using Cassiopeia to transform various data formats into NGSI-LD compliant entities. Each example demonstrates different data types, mapping configurations, and use cases.

Detailed Example Documentation

Quick Reference

Run cassiopeia download first before using any mapping commands. This one-time setup downloads the required Smart Data Model schemas for validation.

Available Commands

  • cassiopeia download — Download Smart Data Model schemas (must run first)

  • cassiopeia list — List available Smart Data Model schemas

  • cassiopeia search <query> — Search for Smart Data Model schemas

  • cassiopeia map — Map data to Smart Data Model

  • cassiopeia server — Run in server mode

  • cassiopeia generate — Generate a mapping file

  • cassiopeia format — Format a JSON5 mapping file

  • cassiopeia convert — Convert JSON5 mapping to plain JSON

Map Commands

  • cassiopeia map csv — Map CSV files

  • cassiopeia map json — Map JSON files

  • cassiopeia map geojson — Map GeoJSON files

  • cassiopeia map gbfs — Map GBFS feeds

  • cassiopeia map gtfs — Map GTFS feeds

Common Options

  • -i, --input <INPUT> — Input file path

  • -m, --mapping <MAPPING> — Mapping file path

  • -o, --output <OUTPUT> — Output directory (for file writer)

  • --writer <TYPE> — Writer type (file or ContextBroker)

  • --site <SITE> — Site component for ID pattern

  • --service <SERVICE> — Service component for ID pattern

  • --group <GROUP> — Group component for ID pattern

Running Examples

CSV and JSON/GeoJSON

CSV to BikeHireDockingStation:

cassiopeia map csv -i data/csv/BikeHireDockingStation.csv -o output -m data/csv/BikeHireDockingStation.json5 --site milano --validation-representation simplified

JSON to PointOfInterest:

cassiopeia map json -i data/json/PointOfInterest.json -o output -m data/json/PointOfInterest.json5

GeoJSON to BikeHireDockingStation or OffStreetParking:

cassiopeia map geojson -i data/geojson/BikeHireDockingStation.geojson -o output -m data/geojson/BikeHireDockingStation.json5
cassiopeia map geojson -i data/geojson/OffStreetParking.geojson -o output -m data/geojson/OffStreetParking.json5

GTFS and GBFS

GTFS feed processing:

cassiopeia map gtfs -i data/gtfs/GtfsBratislava.zip -o output
cassiopeia map gtfs -i data/gtfs/GtfsLjubljanaLpp.zip -o output

GBFS feed processing:

cassiopeia map gbfs -i data/gbfs/GbfsBicikeLJ.json -o output --validation-representation concise
cassiopeia map gbfs -i data/gbfs/GbfsDottStuttgart.json -o output --validation-representation concise
cassiopeia map gbfs -i data/gbfs/GbfsVoiDE.json -o output --validation-representation concise

Understanding the Examples

| Example | Data Source | Key Features | BikeHireDockingStation (CSV) | Milan bike parking | Italian field names, synthetic entities, conditional logic | PointOfInterest (JSON) | Economic activities | Generic field names (FIELD1–20), address construction | BikeHireDockingStation (GeoJSON) | Geographic bike stations | Geometry preservation, coordinate handling | OffStreetParking (GeoJSON) | Milan parking facilities | Conditional logic, dynamic categorization | GTFS | Standard transit feeds | Pre-built configurations, automatic processing | GBFS | Standard bikeshare feeds | Pre-built configurations, real-time data

Working with the Examples

  1. Test with sample data — Use sample data in the data/ directory to test mappings

  2. Examine output — Inspect entity structure, field mapping, relationships, and data types

  3. Modify mappings — Copy mapping files and adapt them for your data

cp data/csv/BikeHireDockingStation.json5 my_mapping.json5
cassiopeia map csv -i your_data.csv -m my_mapping.json5 -o your_output

Advanced Features

Synthetic Entities

Create related entities that do not exist in source data:

owner: {
    source: "urn:ngsi-ld:Organization:ComuneDiMilano",
    type: "ListRelationship",
    targetObjectType: "Organization",
    syntheticEntity: {
        dataModel: "Organization",
        identity: { entityName: "ComuneDiMilano" },
        attributes: { ... }
    }
}

ID Components

Add hierarchical structure to entity IDs:

cassiopeia map csv -i data.csv -m mapping.json5 --site milano --service mobility --group bikeshare

Results in: urn:ngsi-ld:Entity:milano:mobility:bikeshare:entity_id

Context Broker Integration

Write directly to a Context Broker:

cassiopeia map csv -i data.csv -m mapping.json5 --writer ContextBroker --broker-url http://localhost:1026/ngsi-ld/v1