Controlling Output

This page explains how to control where and how Cassiopeia outputs transformed NGSI-LD entities: file output, Context Broker integration, null value handling, and representation formats.

Output Destinations

Cassiopeia supports two output destinations.

File Output (Default)

When using file output, Cassiopeia writes transformed entities to JSON files in the specified output directory.

Required option: --writer-type file -o <output_directory>

Example:

cassiopeia map csv -i data.csv -m mapping.json5 -o output --writer-type file

Output structure: * Each transformed entity is written as a separate JSON file * Files are named using the entity type (data model name) * All files are placed in the specified output directory

Context Broker Output

When using Context Broker output, Cassiopeia sends entities directly to an NGSI-LD Context Broker via HTTP API.

Required options: --writer-type context-broker --broker-url <broker_url>

Example:

cassiopeia map csv -i data.csv -m mapping.json5 \
  --writer-type context-broker \
  --broker-url http://localhost:1026

The default broker URL can be defined in the main configuration file; the CLI argument is optional.

NGSI-LD Representation Formats

Cassiopeia supports three NGSI-LD representation formats.

Normalized Mode

Full NGSI-LD compliance with explicit type information for all attributes.

  • Every attribute includes a "type" field

  • Properties have "value" field

  • Relationships have "object" field

  • GeoProperties have "value" field with geometry

  • All metadata (observedAt, datasetId, etc.) is preserved

Example:

{
  "@context": [
    "https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"
  ],
  "id": "urn:ngsi-ld:Person:John_Lennon",
  "type": "Person",
  "age": {
    "type": "Property",
    "value": 40,
    "unitCode": "ANN"
  },
  "name": {
    "type": "Property",
    "value": "John Lennon"
  },
  "spouse": {
    "type": "Relationship",
    "object": "urn:ngsi-ld:Person:Cynthia_Lennon"
  },
  "location": {
    "type": "GeoProperty",
    "value": {
      "type": "Point",
      "coordinates": [-73.975, 40.775556]
    }
  }
}

Concise Mode (Default)

Compact representation that removes redundant type information while preserving metadata.

  • Simple properties without metadata become just their values

  • Properties and relationships with metadata remain as objects

  • No "type" fields

  • Metadata (observedAt, datasetId, etc.) is preserved

  • More readable and smaller output size

Example:

{
  "@context": [
    "https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"
  ],
  "id": "urn:ngsi-ld:Person:John_Lennon",
  "type": "Person",
  "name": "John Lennon",
  "spouse": "urn:ngsi-ld:Person:Cynthia_Lennon",
  "age": {
    "value": 40,
    "unitCode": "ANN"
  },
  "location": {
    "type": "Point",
    "coordinates": [-73.975, 40.775556]
  }
}

Simplified Mode

Maximum compaction with all metadata removed.

  • All attributes become just their values

  • No type information or metadata preserved

  • Relationships become simple URN strings

  • GeoProperties become raw GeoJSON geometries

  • Smallest possible output size

Example:

{
  "@context": [
    "https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"
  ],
  "id": "urn:ngsi-ld:Person:John_Lennon",
  "type": "Person",
  "name": "John Lennon",
  "spouse": "urn:ngsi-ld:Person:Cynthia_Lennon",
  "age": 40,
  "location": {
    "type": "Point",
    "coordinates": [-73.975, 40.775556]
  }
}

Null Value Handling

Cassiopeia provides two options for handling null values.

Include Null Values

Behavior: All null values are included in the output.

Use cases: * Data auditing and quality control * Systems that need to distinguish between missing and null values * Debugging data transformation issues

Example: --writer-skip-null include --writer-representation normalized

Skip Null Values (Default)

Behavior: Null and empty values are omitted from the output.

Use cases: * Reducing output file size * Cleaner JSON structure * Systems that do not need to distinguish missing vs null values

Example: --writer-skip-null skip --writer-representation concise

In Normalized mode, attributes with null values still include the "type" field to maintain NGSI-LD compliance, even when skipping nulls.

Practical Examples

File Output with Different Formats

Normalized format with null values included:

cassiopeia map csv -i data.csv -m mapping.json5 \
  -o output \
  --writer-type file \
  --writer-representation normalized \
  --writer-skip-null include

Concise format with null values skipped (recommended):

cassiopeia map csv -i data.csv -m mapping.json5 \
  -o output \
  --writer-type file \
  --writer-representation concise \
  --writer-skip-null skip

Simplified format for maximum compaction:

cassiopeia map csv -i data.csv -m mapping.json5 \
  -o output \
  --writer-type file \
  --writer-representation simplified \
  --writer-skip-null skip

Context Broker Output

Standard Context Broker deployment:

cassiopeia map json -i data.json -m mapping.json5 \
  --writer-type context-broker \
  --broker-url http://localhost:1026 \
  --writer-representation concise \
  --writer-skip-null skip

Production Context Broker with full compliance:

cassiopeia map geojson -i data.geojson -m mapping.json5 \
  --writer-type context-broker \
  --broker-url https://orion.example.com \
  --writer-representation normalized \
  --writer-skip-null include

Advanced Output Control

Validation vs. Writer Formatting

You can use different formatting for validation and actual output:

cassiopeia map csv -i data.csv -m mapping.json5 \
  -o output \
  --writer-type file \
  --writer-representation concise \
  --writer-skip-null skip \
  --validation-representation normalized \
  --validation-skip-null include

Use cases: * Use concise format for output (smaller files) * Use normalized format for validation (strict compliance checking) * Include nulls for validation but skip them in output

Multi-Attribute Handling

When an entity has multiple values for the same attribute:

Normalized mode — Arrays of full attribute objects:

{
  "temperature": [
    {
      "type": "Property",
      "value": 20,
      "datasetId": "urn:dataset:1"
    },
    {
      "type": "Property",
      "value": 22,
      "datasetId": "urn:dataset:2"
    }
  ]
}

Concise mode — Arrays of compacted objects:

{
  "temperature": [
    {
      "value": 20,
      "datasetId": "urn:dataset:1"
    },
    {
      "value": 22,
      "datasetId": "urn:dataset:2"
    }
  ]
}

Simplified mode — Arrays of just the values:

{
  "temperature": [20, 22]
}