Skip to main content

Understanding NGSI-LD

NGSI-LD is an open standard, published by ETSI, that enables building dynamic knowledge graphs for managing context information across diverse domains. It provides both a flexible information model and a comprehensive REST API, making it ideal for creating interoperable, context-aware applications and digital twins.

NGSI-LD is an extension of JSON-LD, a JSON-based format to serialize Linked Data. By extending JSON-LD, NGSI-LD inherits the ability to represent semantic data and link it across domains while adding specific features for managing real-time context information, temporal history, and geospatial data.

Why NGSI-LD?​

Traditional approaches to building smart solutions often result in isolated data silos, expensive custom integrations, and vendor lock-in. These approaches limit the ability to represent complex relationships and maintain historical context effectively.

NGSI-LD addresses these limitations through a flexible property-graph information model that naturally represents complex relationships. The standard includes built-in support for temporal and geospatial data, along with a standardized REST API that combines simple operations with advanced query patterns. Its subscription system enables complex event detection, pattern matching, and real-time notifications based on changes in context data. The standard also provides federation features to support distributed systems. This standardized approach enables interoperable solutions that work across different domains while preserving domain-specific semantics.

Information Model​

NGSI-LD represents context information through entities that can model physical objects, abstract concepts, processes, measurements, events, and more. Each entity is uniquely identified by an id and characterized by one or multiple types through the type field.

The standard supports various attribute types to represent different kinds of information: Property, Relationship, GeoProperty, LanguageProperty, JsonProperty, ListProperty, and ListRelationship. Each type serves a specific purpose in modeling context information and relationships within the knowledge graph.

The Information Model is structured in two levels: core foundation classes that define how context information is represented, and a cross-domain ontology comprising generic concepts that apply across different domains. This cross-domain ontology provides basic concepts related to time, mobility, system states, and system composition, preventing conflicting definitions across domains.

NGSI-LD Types​

In NGSI-LD, types are flexible categories that help classify entities. Unlike strict data models, types don't enforce specific attributes or structures - this validation is left to the application layer, making the system highly adaptable to different use cases and requirements.

An entity's type simply indicates its category or nature, and types come into existence automatically when the first entity of that type is created. Entities can have multiple types (multi-typing), enabling flexible categorization and querying patterns:

NGSI-LD Types
{
    "id": "urn:ngsi-ld:IndoorAirQualitySensor:IndoorAQ-001",
    "type": ["Sensor", "AirQualitySensor", "IndoorAirQualitySensor"],
    "co2": {
        "type": "Property",
        "value": 432,
        "unitCode": "PPM",
        "observedAt": "2024-11-05T12:00:00Z"
    }
}

In this example, the same entity can be queried at different levels of specificity. Applications can search broadly for any type of Sensor, narrow their focus to AirQualitySensor, or specifically target IndoorAirQualitySensor.

This flexible typing system enables natural categorization hierarchies without enforcing strict inheritance. Applications can work at their preferred level of specificity, while the system remains adaptable to new requirements.

The approach simplifies integration with external systems through straightforward mapping to different data models or ontologies. As new categories and relationships emerge, the knowledge graph can evolve naturally without requiring structural changes.

NGSI-LD Attributes​

Each NGSI-LD entity can have multiple attributes that describe its characteristics and relationships. Let's explore each attribute type and its purpose in building the knowledge graph.

NGSI-LD Property​

NGSI-LD Property represents a data value about an entity. This can be a simple value like a string or number, or a structured object including arrays. Every Property must have a value and can include metadata like unitCode for specifying measurement units. While value can contain arrays, these don't guarantee order preservation - for ordered lists, NGSI-LD provides the specific ListProperty type.

Properties can have their own Properties and Relationships as metadata, enabling rich descriptions, as shown in the example below with the accuracy Property.

NGSI-LD Property
{
    "id": "urn:ngsi-ld:Room:Room-101",
    "type": "Room",
    "temperature": {
        "type": "Property",
        "value": 21.7,
        "unitCode": "CEL",
        "observedAt": "2024-11-05T12:00:00Z",
        "accuracy": {
            "type": "Property",
            "value": 0.8
        }
    }
}

The temporal attribute observedAt can be included to indicate when a value was measured. Like all NGSI-LD attributes, Properties with observedAt automatically enable temporal storage and querying capabilities, allowing applications to access historical values for the attribute.

NGSI-LD ListProperty​

NGSI-LD ListProperty represents an ordered list of values through its valueList field. While standard Properties can contain arrays in their value, ListProperty specifically ensures preservation of element order, making it ideal for sequences where order matters.

NGSI-LD ListProperty
{
    "id": "urn:ngsi-ld:AssemblyLine:Robot-101",
    "type": "AssemblyLine",
    "sequence": {
        "type": "ListProperty",
        "valueList": [
            "PickComponent",
            "AlignComponent",
            "WeldComponent",
            "QualityCheck"
        ],
        "observedAt": "2024-02-23T12:00:00Z"
    }
}

This ordered representation is particularly valuable in manufacturing processes, recipe steps, procedural instructions, or any scenario where sequence directly impacts outcomes. Applications can rely on the exact order of elements being maintained throughout system operations.

NGSI-LD Relationship​

NGSI-LD Relationship represents a directed link to another entity through its object field. The objectType field specifies the expected type of the referenced entity. While object can reference multiple entities as an array, this doesn't guarantee order preservation - for ordered lists of relationships, use NGSI-LD ListRelationship instead.

Relationships can include metadata providing context about the connection, such as when it was established. Like Properties, Relationships can have their own Properties and Relationships, enabling rich context about the connection itself.

These relationships form the foundation of NGSI-LD's graph capabilities, enabling applications to traverse the knowledge graph. For example, from a sensor entity, applications can follow relationships to find its location, the building it's installed in, and the organization that manages it.

NGSI-LD Relationship
{
    "id": "urn:ngsi-ld:IndoorAirQualitySensor:IndoorAQ-001",
    "type": ["Sensor", "AirQualitySensor", "IndoorAirQualitySensor"],
    "installedIn": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:Building:Building-101",
        "installedAt": {
            "type": "Property",
            "value": "2024-08-18T10:00:00Z"
        },
        "installedBy": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:Person:Technician-123"
        }
    }
}

NGSI-LD's approach to relationships prioritizes scalability and flexibility by not enforcing strict referential integrity. This design choice enables high-performance operations at scale, as creating, updating, or deleting entities doesn't require validation of relationship references. Applications can implement their own validation rules based on their specific consistency requirements.

Just as NGSI-LD allows applications to define their own data model validation rules, they can also implement custom relationship integrity checks. For example, a fleet management system might require Vehicle entities to exist before allowing them to be referenced in Route assignments. In IoT scenarios, this flexibility is particularly valuable as devices can continuously update their status without requiring atomic transactions across the entire relationship chain. This flexibility lets developers choose the appropriate balance between consistency and operational requirements for their specific use case.

NGSI-LD ListRelationship​

NGSI-LD ListRelationship represents an ordered sequence of entity references through its objectList field. This ensures the preservation of relationship order, essential for scenarios where the sequence of connections matters.

NGSI-LD ListRelationship
{
    "id": "urn:ngsi-ld:BusLine:Line-101",
    "type": "BusLine",
    "busStops": {
        "type": "ListRelationship",
        "objectList": [
            "urn:ngsi-ld:BusStop:Stop1",
            "urn:ngsi-ld:BusStop:Stop2",
            "urn:ngsi-ld:BusStop:Stop3"
        ],
        "objectType": "BusStop"
    }
}

This ordered representation enhances graph traversal operations, allowing applications to retrieve the complete bus line information including the location of each stop in sequence, combining the ordered relationships with the geographical properties of each bus stop entity with a single query.

NGSI-LD GeoProperty​

NGSI-LD GeoProperty represents geographical locations and shapes using GeoJSON format. The location attribute is commonly used as a GeoProperty to represent the geographic location of an entity, such as the position of a vehicle or the location of a building.

NGSI-LD GeoProperty
{
    "id": "urn:ngsi-ld:Bus:Bus-1985",
    "type": ["Vehicle", "Bus"],
    "location": {
        "type": "GeoProperty",
        "value": {
            "type": "Point",
            "coordinates": [3.0583, 36.7539]
        },
        "observedAt": "2025-01-19T12:00:00Z"
    }
}

NGSI-LD supports all GeoJSON Geometries with the exception of GeometryCollection. Beyond simple points, you can represent lines for routes, polygons for areas, and other geometric shapes to model spatial characteristics of your entities.

GeoProperties enable spatial queries and geographic analysis within the knowledge graph, including proximity searches and geofencing capabilities.

For example, ride-sharing applications can match drivers with nearby ride requests, delivery services can optimize routes based on vehicle locations, and fleet management systems can implement geofencing to track vehicles within operational boundaries. In smart city scenarios, these capabilities can support real-time traffic management, such as adjusting traffic signals based on bus locations to improve public transport efficiency.

NGSI-LD JsonProperty​

NGSI-LD JsonProperty stores JSON data through its json field. The content of json is not subject to JSON-LD expansion and compaction rules (concepts described later in this documentation), meaning it is preserved exactly as provided.

NGSI-LD JsonProperty
{
    "id": "urn:ngsi-ld:MLModel:Classifier-101",
    "type": "MLModel",
    "hyperparameters": {
        "type": "JsonProperty",
        "json": {
            "layers": [
                {"type": "dense", "units": 128, "activation": "relu"},
                {"type": "dropout", "rate": 0.5},
                {"type": "dense", "units": 10, "activation": "softmax"}
            ],
            "optimizer": {
                "algorithm": "adam",
                "learning_rate": 0.001
            }
        }
    }
}

This preservation of raw JSON structure is valuable for complex configurations, nested data structures, or any information that needs to maintain its exact format without semantic processing

NGSI-LD LanguageProperty​

NGSI-LD LanguageProperty represents text in multiple languages through its languageMap field, enabling internationalization of human-readable information. Each language variant is identified by its corresponding language code.

NGSI-LD LanguageProperty
{
    "id": "urn:ngsi-ld:Museum:Museum1",
    "type": "Museum",
    "description": {
        "type": "LanguageProperty",
        "languageMap": {
            "en": "National Art Museum",
            "es": "Museo Nacional de Arte",
            "fr": "Musée National d'Art"
        }
    }
}

This multi-language support enables applications to provide localized information while maintaining the semantic meaning of the attribute across different languages.

NGSI-LD Scopes​

NGSI-LD Scopes enable organizing entities in hierarchical structures, providing an efficient way to categorize and query context information. Each entity can have one or multiple scopes, representing its place in different hierarchical structures. For example:

NGSI-LD Scopes
{
    "id": "urn:ngsi-ld:Customer:DZ42617961",
    "type": "Customer",
    "scope": [
        "/Region/Europe/Country/France/City/Paris",
        "/Program/Loyalty/Tier/Platinum"
    ],
    "customerStatus": {
        "type": "Property",
        "value": "active"
    },
    "email": {
        "type": "Property",
        "value": "janettedoe@email.com"
    },
    "bookings": {
        "type": "ListRelationship",
        "objectList": [
            "urn:ngsi-ld:Booking:AG2024021",
            "urn:ngsi-ld:Booking:AG2024089"
        ],
        "objectType": "Booking"
    }
}

This hierarchical organization enables efficient querying and filtering of entities. When querying entities, you can use wildcards to match different levels:

  • The + wildcard matches exactly one level in the hierarchy
  • The # wildcard, when used at the end, matches the current level and all levels below

For example:

  • /Region/Europe/Country/France/City/+ matches customers in all French cities
  • /Program/Loyalty/Tier/Platinum matches all platinum tier members
  • /Region/Europe/# matches all European customers across countries and cities

Airlines can use these hierarchies to efficiently manage customer communications. When launching a new route from Paris, they can quickly identify platinum members in the region for exclusive previews. The scope structure makes it simple to target specific customer groups without complex queries, whether for marketing campaigns, service updates, or regional promotions.

Beyond querying, scopes can also be used in subscriptions to monitor changes in specific hierarchical structures. This combination of scopes in both queries and subscriptions creates a flexible mechanism for organizing and monitoring context information across different hierarchical structures.

Data Representations​

NGSI-LD provides multiple ways to represent entity data, each suited for different use cases. These representations offer varying levels of detail while maintaining semantic meaning.

Normalized Representation​

The default representation in NGSI-LD provides complete metadata about properties and relationships. This format ensures full context is preserved:

Normalized Representation
{
    "id": "urn:ngsi-ld:Room:Room101",
    "type": "Room",
    "temperature": {
        "type": "Property",
        "value": 21.7,
        "unitCode": "CEL",
        "observedAt": "2024-02-23T12:00:00Z"
    }
}

Simplified Representation​

For cases where only the values are needed, NGSI-LD offers a simplified representation through the keyValues option. This representation reduces verbosity while maintaining essential information:

Simplified Representation
{
    "id": "urn:ngsi-ld:Room:Room101",
    "type": "Room",
    "temperature": 21.7
}

Concise Representation​

The concise representation provides a middle ground, directly representing Property Values and Relationship objects as JSON properties while maintaining essential metadata:

Concise Representation
{
    "id": "urn:ngsi-ld:Room:Room101",
    "type": "Room",
    "temperature": 21.7
}

System-Generated Temporal Metadata​

NGSI-LD implementations automatically maintain temporal metadata for entities:

  • createdAt: Records when an entity was first created
  • modifiedAt: Tracks the timestamp of the last modification

This temporal metadata enables tracking the lifecycle of entities and their attributes. Applications can access this information by including the sysAttrs option in their requests:

System-Generated Temporal Metadata
{
    "id": "urn:ngsi-ld:Room:Room101",
    "type": "Room",
    "temperature": {
        "type": "Property",
        "value": 21.7,
        "createdAt": "2024-02-23T12:00:00Z",
        "modifiedAt": "2024-02-23T12:00:00Z"
    },
    "createdAt": "2024-02-23T12:00:00Z",
    "modifiedAt": "2024-02-23T12:00:00Z"
}

These system-generated attributes provide essential audit capabilities, enabling applications to track when information was created or last updated. While this automatic temporal tracking covers entity lifecycle events, NGSI-LD provides even more comprehensive temporal capabilities through its temporal features.

Temporal Features​

NGSI-LD provides built-in support for temporal data through temporal properties. The most common temporal property is observedAt, which indicates when a value was measured or when a relationship was established.

Temporal Features
{
    "id": "urn:ngsi-ld:Room:Room101",
    "type": "Room",
    "temperature": {
        "type": "Property",
        "value": 18,
        "unitCode": "CEL",
        "observedAt": "2023-11-05T07:00:00.000Z",
        "providedBy": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:IndoorAirQualitySensor:IndoorAirQualitySensor-001"
        }
    }
}

When attributes include temporal properties, NGSI-LD automatically maintains their historical values. Applications can query these temporal records to analyze trends, create time-series visualizations, or understand how entity attributes change over time. In this example, applications can track the evolution of room temperature along with the sensor that provided each measurement.

NGSI-LD Subscriptions​

NGSI-LD subscriptions enable applications to monitor context information changes and receive notifications when specific conditions are met. This asynchronous mechanism forms the foundation for building reactive, event-driven systems that can respond to changes in real-time.

Through subscriptions, applications can watch for various types of changes in the context information. These include the creation of new entities, updates to specific attributes, or attribute values crossing defined thresholds. Applications can also receive notifications at regular intervals, enabling periodic monitoring without constant polling.

Here's an example of a subscription that monitors delivery vehicles entering specific zones, combining both attribute and geographic conditions:

NGSI-LD Subscriptions
{
    "id": "urn:ngsi-ld:Subscription:DeliveryZoneMonitoring",
    "type": "Subscription",
    "entities": [
        {
            "type": "DeliveryVehicle"
        }
    ],
    "watchedAttributes": ["location", "status"],
    "q": "status==delivering",
    "geoQ": {
        "georel": "within",
        "geometry": "Polygon",
        "coordinates": [[[-0.1238,51.5175],[-0.1044,51.5030],[-0.0812,51.5182],[-0.1052,51.5285],[-0.1238,51.5175]]]
    },
    "notification": {
        "attributes": ["location", "status", "vehicleId"],
        "endpoint": {
            "uri": "${GarnetPrivateSubEndpoint}",
            "accept": "application/json"
        }
    },
    "@context": [
        "https://raw.githubusercontent.com/awslabs/garnet-framework/main/context.jsonld"
    ]
}

In this subscription, the entities field specifies which types of entities to monitor - in this case, any entity of type DeliveryVehicle. The watchedAttributes field indicates we want notifications when either the location or status attributes change.

The q field defines a query filter, triggering notifications only when vehicles are in delivering status. This combines with the geoQ field, which sets up a geographic fence using a polygon. Together, these conditions mean the subscription only triggers when delivering vehicles enter the defined area.

The notification section specifies what information to include in notifications (location, status, and vehicleId) and where to send them to the specified endpoint. Garnet Framework provides a private endpoint that publishes notifications to AWS IoT Core MQTT topics, enabling secure and scalable notification delivery by design. Multiple consumers can subscribe to these topics in parallel, though you retain the flexibility to use your own endpoints if preferred.

This subscription enables geofencing capabilities by combining geographic queries with entity monitoring. Fleet managers can track when vehicles enter or leave designated zones, helping coordinate deliveries and maintain operational boundaries. The system can automatically notify when vehicles deviate from assigned areas or enter restricted zones, enabling proactive response to potential issues.

Subscriptions enable scalable event-driven architectures by decoupling event producers from consumers. For example, AI agents can subscribe to relevant context changes without directly querying the system. An autonomous delivery optimization agent might subscribe to vehicle locations, traffic conditions, and delivery status updates. When conditions change, the agent receives notifications and can automatically adjust routes or reallocate resources. This pattern scales effectively as new agents or services can subscribe to existing event streams without impacting other components.

API Overview​

The NGSI-LD API defines a standardized REST interface that aligns with the NGSI-LD information model. This coherence between data representation and interface design creates a consistent experience across implementations, allowing developers to build applications that work effectively across different NGSI-LD systems. By standardizing both the information model and the API, NGSI-LD enables interoperability at multiple levels - not just in how data is structured, but also in how it is accessed, manipulated, and queried.

This dual standardization reduces integration challenges. Developers can transfer their knowledge between different NGSI-LD implementations, using familiar patterns rather than learning proprietary interfaces for each system. The standardized API also enables the development of reusable tools, libraries, and components that work across different NGSI-LD implementations, accelerating development and increasing code reuse.

Knowledge Graph Discovery​

Understanding what information exists in the knowledge graph is essential for both applications and users. The discovery mechanisms help applications understand the structure of the knowledge graph, particularly valuable for autonomous agents or dynamic applications that need to adapt to available context information.

The Types interface (/ngsi-ld/v1/types) enables discovering available entity types and their attributes. This helps applications understand what kinds of entities exist in the system and how they're structured, allowing them to dynamically adapt to the available information rather than requiring hard-coded knowledge of the data model.

The Attributes interface (/ngsi-ld/v1/attributes) provides insights into how attributes are used across entities. Applications can discover what properties are available, which entity types use them, and their semantic meaning. This discovery capability is particularly valuable in federated scenarios where applications need to work with context information from multiple sources.

Together, these discovery capabilities create a self-describing system where applications can explore and understand the knowledge graph structure, enabling more dynamic and adaptable behaviors.

Entity Operations​

The Entities interface (/ngsi-ld/v1/entities) forms the core of context information management. The API supports both individual entity operations for detailed control and batch operations through dedicated endpoints (/ngsi-ld/v1/entityOperations). These batch capabilities allow creating, updating, or deleting multiple entities in a single request, reducing network overhead and improving performance for bulk operations.

Entity querying offers substantial flexibility through a comprehensive set of filtering mechanisms. Type-based filtering allows retrieving all entities of a particular category, such as all buildings or vehicles. Regular expression pattern matching can be applied to entity IDs and attribute values, enabling complex search patterns across the knowledge graph. The query language supports comparison operators, logical combinations, and string matching functions.

Geographic queries enable spatial filtering based on locations, finding entities within specific distances or geographic regions. This spatial dimension adds contextual relevance to queries, connecting digital information with physical locations. Attribute filters can be combined with geographic queries to further refine results, such as finding all vehicles of a specific type within an area.

The comprehensive query capabilities make NGSI-LD suitable for building context-aware applications that adapt to changing conditions. For instance, a smart city application can find all public transport vehicles currently within a district experiencing high pollution levels, or identify buildings with energy consumption patterns correlating with specific weather conditions.

Temporal Interface​

The temporal interface (/ngsi-ld/v1/temporal/entities) manages historical context information, enabling applications to understand how entities evolve over time. This historical perspective is essential for many applications, from performance analysis to predictive maintenance.

The temporal capabilities include retrieving entity states between timestamps, accessing the most recent states, and generating statistical aggregations over time periods. This historical data access captures how context information changes over time.

A building management system might retrieve the average temperature in a room over the past hour to detect anomalies, or analyze the maximum occupancy levels during specific timeframes to optimize space usage. Manufacturing systems can examine equipment performance trends to predict maintenance needs, while environmental monitoring applications can track pollution levels over time to identify patterns.

This temporal dimension transforms static snapshots into dynamic histories, enabling deeper insights and more intelligent decision-making based on trends and patterns.

Subscription Management​

The subscription interface (/ngsi-ld/v1/subscriptions) enables applications to monitor changes in context information and receive notifications when specific conditions are met. This asynchronous approach is fundamental to building reactive, event-driven systems that can respond to changes in real-time without constant polling.

Subscriptions support a comprehensive range of notification triggers from basic entity changes to complex conditions involving attribute thresholds, geographic boundaries, and periodic notifications. This flexible notification system allows applications to receive precisely targeted updates about relevant changes in the context information.

This subscription mechanism creates event-driven architectures where systems respond to real-world changes as they happen. A building automation system might adjust lighting based on occupancy changes, while logistics applications can reroute deliveries when vehicles enter specific areas.

Context Source Registration​

The registration interface (/ngsi-ld/v1/csourceRegistrations) enables managing federation scenarios where context information is distributed across multiple systems. Through this interface, applications can register external context sources, specify what types of information they provide, and manage the lifecycle of these registrations.

This federation approach acknowledges that in complex environments, context information naturally spans organizational and system boundaries. Smart cities involve multiple departments and systems, each managing specialized information. Manufacturing environments combine production systems, supply chain data, and quality monitoring. The registration interface creates bridges between these systems, allowing information to flow while respecting organizational boundaries.

The result is a unified view of context information regardless of where it physically resides. Applications can discover and access relevant information through standard interfaces without needing to know which system actually stores it. This architecture scales more effectively than centralized approaches while respecting the natural distribution of information ownership.

Each interface supports content negotiation, enabling applications to receive data in their preferred format - whether that's the complete normalized representation or more concise formats for efficient processing.

For detailed examples of using these interfaces in practical scenarios, refer to the "Using Garnet" section which demonstrates common implementation patterns and best practices.

JSON-LD Context​

NGSI-LD builds on JSON-LD's context mechanism to give semantic meaning to attributes. A context provides mapping between short terms and their fully qualified URIs, enabling both human-readable representations and precise semantic definitions.

Compaction and Expansion​

JSON-LD defines two key operations: compaction and expansion. Expansion transforms shortened terms into their full URIs, while compaction does the reverse, using the context to create a more concise representation.

For example, a temperature Property in its expanded form:

{
    "id": "urn:ngsi-ld:Room:Room1",
    "type": "Room",
    "https://example.dev/temperature": {
        "type": "Property",
        "value": 21.7
    }
}

The same data in its compacted form using a context:

{
    "id": "urn:ngsi-ld:Room:Room1",
    "type": "Room",
    "temperature": {
        "type": "Property",
        "value": 21.7
    },
    "@context": "https://example.dev/context.jsonld"
}

The context mechanism enables applications to work with concise, readable attribute names while maintaining precise semantic definitions. This balance between human readability and semantic precision forms the foundation for building interoperable knowledge graphs where meaning is preserved across different systems and domains.

Further Reading​

NGSI-LD extends beyond the concepts covered in this introduction. NGSI-ld.org provides detailed technical documentation, including a pointer to the complete ETSI specification.

For practical learning, FIWARE offers educational webinars demonstrating NGSI-LD implementations across different scenarios. The NGSI-LD tutorials provide hands-on examples to reinforce your understanding through practical exercises.

Next Steps​

With this foundation in NGSI-LD, you can begin working with your Garnet Framework instance to create your first dynamic knowledge graph. The "Using Garnet" section guides you through the practical aspects of entity creation, relationship management, and implementing real-time monitoring through subscriptions.