fwNgsiv2 — NGSIv2 Validation & Normalization

What It Does

fwNgsiv2 validates and normalizes NGSIv2 payloads, parses NGSIv2-specific query parameters, handles representation modes, and provides NGSIv2 ↔ NGSI-LD translation.

Where fwNgsild deals with the complexity of JSON-LD @context semantics, fwNgsiv2 handles the NGSIv2-specific concerns: different attribute structures, v2-specific query languages, and the translation layer needed when both protocol versions share the same storage backend.

Core Capabilities

• NGSIv2 payload validation — different attribute structure from NGSI-LD: "value" directly, "type": "Text"/"Number"/"Boolean"/etc., metadata as nested objects
• Query string parsing — q (simple query language), mq (metadata query), georel, geometry, coords (geo queries), orderBy
• Representation modes — keyValues (compact), values (array), unique (distinct values), normalized (default)
• NGSIv2 ↔ FtNode normalization — convert between NGSIv2 JSON format and internal FtNode tree
• NGSIv2 ↔ NGSI-LD translation — map between v2 and LD formats when both brokers share the same kdb storage
• Attribute type mapping — NGSIv2 types (Text, Number, Boolean, StructuredValue, DateTime, geo:json) ↔ NGSI-LD types (Property, Relationship, GeoProperty)

What It Doesn't Do

No @context handling, no URI expansion/compaction, no remote context downloads. NGSIv2 uses plain attribute names — there is no JSON-LD semantic layer to deal with.

Why It Exists

The FiWorks NGSIv2 Broker needs v2-specific validation and query parsing that is fundamentally different from the NGSI-LD path. When both the NGSI-LD and NGSIv2 brokers share the same kdb storage, fwNgsiv2 provides the translation layer that maps between the two formats.

Without this library, the NGSIv2 broker would need its own inline implementation of payload validation, query parsing, and format translation — code that would inevitably diverge from the NGSI-LD side and create inconsistencies.

Dependencies

Library	Role
fwJson	JSON parser for parsing NGSIv2 payloads into FtNode trees
fwAlloc	Bump allocator for all memory allocation
fwHash	Hash tables for attribute type mappings and query caches

Note the absence of fwHttp in the dependency list — unlike fwNgsild, fwNgsiv2 never needs to download remote documents. NGSIv2 has no equivalent of @context.

fwNgsild vs fwNgsiv2

Aspect	fwNgsild	fwNgsiv2
@context handling	Full (download, cache, expand, compact)	None
Payload validation	NGSI-LD structure	NGSIv2 structure
Query parsing	NGSI-LD q syntax (URI-based)	NGSIv2 q/mq syntax (dot notation)
Representation modes	Simplified, concise, normalized	keyValues, values, unique, normalized
Translation	—	NGSIv2 ↔ NGSI-LD
Complexity	~3,000–5,000 lines	~1,000–2,000 lines