fwNgsild — JSON-LD @context Engine

What It Does

fwNgsild is the JSON-LD @context processing engine for NGSI-LD. It downloads remote @context documents via the fwHttp client, parses them into dual fwHash tables (name→URI and URI→name), caches them thread-safely, and performs full expansion and compaction of NGSI-LD entities.

This is the library that turns short attribute names like "temperature" into fully qualified URIs like "https://uri.fiware.org/ns/data-models#temperature" and back again — the core operation that makes NGSI-LD a linked-data protocol rather than just another JSON API.

Core Capabilities

• Remote @context download and caching — uses the fwHttp client to fetch remote context documents over HTTP/HTTPS, with a thread-safe cache and TTL-based expiration
• Dual hash table lookup — short name → full URI (expansion) and full URI → short name (compaction), both via O(1) fwHash operations
• Recursive context resolution — contexts that reference other contexts are resolved recursively until all terms are fully expanded
• Prefix expansion — schema:name → https://schema.org/name, handling all registered prefixes in the @context
• @vocab fallback — terms not explicitly mapped in the @context fall back to the @vocab base URI
• Core context versioning — supports NGSI-LD core context versions v1.0 through v1.9, selecting the right context based on the request
• Inline context handling — contexts embedded directly in the request body are parsed and merged with any referenced remote contexts

Why It Exists

Without fwNgsild, every Generic Enabler would reimplement @context handling. The NGSI-LD Broker, the Multi-Agent system, any component that processes NGSI-LD payloads — they all need to expand and compact attribute names, resolve contexts, handle prefixes. That's complex, error-prone code involving HTTP downloads, caching, hash tables, and recursive resolution.

fwNgsild is designed for full JSON-LD compliance. The key design principle: no strcmp shortcuts — everything goes through fwHash. All lookups are uniform O(1) hash operations, making the library correct by construction for any @context, not just the ones the developer anticipated.

Performance

Context lookups are O(1) fwHash operations. Context download happens once per unique @context URL, then the parsed result is cached thread-safely with TTL-based expiration.

Expansion/compaction of a typical 20-attribute entity: ~5–15μs. This is fast enough to be negligible compared to any I/O operation — database access, network calls, or even HTTP parsing.

Dependencies

Library	Role
fwHttp	HTTP client for downloading remote @context documents
fwJson	JSON parser for parsing context documents into FtNode trees
fwAlloc	Bump allocator for all memory allocation during context processing
fwHash	Hash tables for the dual name↔URI lookup maps

Used By

• FiWorks NGSI-LD Broker — all incoming and outgoing NGSI-LD payloads go through fwNgsild for expansion/compaction
• FiWorks Multi-Agent — agent-to-agent communication uses NGSI-LD entities that require @context handling
• Any component that processes NGSI-LD payloads — the library is designed to be pulled in by any GE that needs linked-data semantics