BikeHireDockingStation (CSV)

This example demonstrates how to transform a CSV file containing Milan’s bike docking station data into FIWARE-compliant NGSI-LD entities.

Source Data

The source data (BikeHireDockingStation.csv) contains bike docking stations from Milan with columns such as:

  • LOCALITÀ DI INTERVENTO — Location name

  • Attrattore Tipo — Attractor type (category of nearby point of interest)

  • Attrattore Nome — Attractor name

  • Municipio — Municipality/borough number

  • Tot posti — Total number of posts (bike parking spaces)

  • Data di posa — Installation date

Mapping Challenges

Field Names with Special Characters

The CSV contains Italian field names with spaces that are invalid in template expressions. Use this['field_name'] syntax:

source: "{{ this['LOCALITA DI INTERVENTO'] | default(value='Unknown') }}"
source: "{{ this['Tot posti'] }}"

Synthetic Entity Creation

The data references an organization (Comune di Milano) that does not exist as a separate entity. Create it on-the-fly:

owner: {
    source: "urn:ngsi-ld:Organization:ComuneDiMilano",
    type: "ListRelationship",
    targetObjectType: "Organization",
    syntheticEntity: {
        dataModel: "Organization",
        identity: { entityName: "ComuneDiMilano" },
        attributes: {
            name: {
                source: "Comune di Milano",
                type: "Property",
                transformation: "string",
            },
        },
    },
}

Nested Address Object

Combine multiple CSV fields into a structured address:

address: {
    type: "Property",
    transformation: "object",
    mappings: {
        streetAddress: {
            source: "{{ this['LOCALITA DI INTERVENTO'] | default(value='Unknown') }}",
            type: "Property",
            transformation: "string",
        },
        addressLocality: {
            source: "{{ this['Municipio'] }}",
            type: "Property",
            transformation: "string",
        },
        addressCountry: {
            source: "IT",
            type: "Property",
            transformation: "string",
        },
    },
}

Running the Example

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

Key Takeaways

  • Use this['field_name'] for fields with spaces or special characters

  • Specify appropriate transformation for type safety

  • Use mappings to create nested objects from flat CSV data

  • Use default() filters for missing data

  • Create synthetic entities when related data does not exist in the source