https://github.com/fiware/tutorials.ngsi-ld
:tractor: :cow: NGSI-LD Tutorials based around a Smart Farm
https://github.com/fiware/tutorials.ngsi-ld
contextual-data fiware ngsi-ld tutorial
Last synced: 5 months ago
JSON representation
:tractor: :cow: NGSI-LD Tutorials based around a Smart Farm
- Host: GitHub
- URL: https://github.com/fiware/tutorials.ngsi-ld
- Owner: FIWARE
- License: mit
- Created: 2020-06-02T08:57:05.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-08-13T08:34:42.000Z (5 months ago)
- Last Synced: 2025-08-13T10:24:23.772Z (5 months ago)
- Topics: contextual-data, fiware, ngsi-ld, tutorial
- Language: JavaScript
- Homepage: http://ngsi-ld-tutorials.rtfd.io/
- Size: 3.63 MB
- Stars: 31
- Watchers: 8
- Forks: 25
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Smart Farm Tutorials[
](https://cim.etsi.org/NGSI-LD/official/0--1.html) [
](https://www.fiware.org/)
[](https://ngsi-ld-tutorials.rtfd.io)
[](https://opensource.org/licenses/MIT)
[](https://stackoverflow.com/questions/tagged/fiware)
[](https://quay.io/repository/fiware/tutorials.ngsi-ld)
[](https://ngsi-ld-tutorials.rtfd.io)
[](https://github.com/FIWARE/tutorials.NGSI-LD/actions?query=workflow%3ACI)
This is a collection of tutorials for the FIWARE ecosystem designed for **NGSI-LD** developers. Each tutorial consists
of a series of exercises to demonstrate the correct use of individual FIWARE components and shows the flow of context
data within a simple Smart Solution either by connecting to a series of dummy IoT devices or manipulating the context
directly or programmatically.
| :books:
[NGSI-LD
Documentation](https://ngsi-ld-tutorials.rtfd.io/) | 
[Postman
Collections](https://explore.postman.com/team/3mM5EY6ChBYp9D) | [](https://hub.docker.com/u/fiware)
[](https://quay.io/organization/fiware)
[](https://artifacthub.io/packages/search?repo=fiware) | 
[**developer.​fiware.org**](https://www.fiware.org/developers/) |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
> [!NOTE]
>
> **Should I use NGSI-LD or NGSI-v2?**
>
> FIWARE offers two flavours of the NGSI interfaces:
>
> - **NGSI-v2** offers JSON based interoperability used in individual Smart Systems
> - **NGSI-LD** offers JSON-LD based interoperability used for Federations and Data Spaces
>
> Of the two, NGSI-LD is more complex and relies on the introduction of a JSON-LD `@context`. A full understanding of
> JSON-LD (Linked Data) is required to obtain the benefits of NGSI-LD , which allows for interoperability across apps
> and organisations.
>
> In general, you should use NGSI-LD when creating a data space or introducing a system of systems aproach.
>
> Use NGSI-v2 for simpler isolated systems. More information about NGSI-v2 can be found
> [here](https://fiware-tutorials.readthedocs.io)
Data models
The tutorials define a series of data-models to be used within the `@context`. More information about the classes and
attributes used can be found in the following:
- 
Tutorial-specific Data Models.
-
Smart Data Models.
## Install
To download the full set of tutorials, simply clone this repository:
```console
git clone https://github.com/FIWARE/tutorials.NGSI-LD.git
cd tutorials.NGSI-LD/
git submodule update --init --recursive
```
### Swagger 
The OpenAPI Specification (commonly known as Swagger) is an API description format for REST APIs. A Swagger spec allows
you to describe an entire API (such as NGSI-LD itself) however in this tutorial we shall be concentrating on using
Swagger to define data models.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines.
The complete OpenAPI Specification can be found on GitHub:
[OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md). This is
important since we will need a well-defined structure to be able to generate `@context` files.
### Docker and Docker Compose 
The NGSI-LD tutorials are designed to run under any Unix environment, the tested configuration and GitPod environment is
currently based on Ubuntu 22.04.2 LTS. However, there may be some minor issues when running the tutorials directly on
Windows machines or Apple M1 Silicon amd64 systems, and the following [Virtual Box set-up](docs/virtual-box.md) or
[WSL set-up](docs/wsl.md) can be used when facing issues.
Each tutorial runs all components using [Docker](https://www.docker.com). **Docker** is a container technology which
allows to different components isolated into their respective environments.
- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/).
- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/).
- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/).
**Docker Compose** is a tool for defining and running multi-container Docker applications. A series of `*.yaml` files
are used configure the required services for the application. This means all container services can be brought up in a
single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux
users will need to follow the instructions found [here](https://docs.docker.com/compose/install/).
You can check your current **Docker** and **Docker Compose** versions using the following commands:
```console
docker-compose -v
docker version
```
Please ensure that you are using Docker version 24.0.x or higher and Docker Compose 2.24.x or higher and upgrade if
necessary.
Although not officially supported, older versions of docker without an integrated docker-compose can be run by adding
`legacy` to all bash script commands:
```console
./services start legacy
```
### Postman 
The tutorials which use HTTP requests supply a collection for use with the Postman utility. Postman is a testing
framework for REST APIs. The tool can be downloaded from [www.postman.com](https://www.postman.com/downloads/). All the
FIWARE Postman collections can be downloaded directly from the
[Postman API network](https://explore.postman.com/team/3mM5EY6ChBYp9D).
### GitPod 
[Gitpod](https://github.com/gitpod-io/gitpod) is an open-source Kubernetes application for ready-to-code cloud
development environments that spins up an automated dev environment for each task, in the cloud. It enables you to run
the tutorials in a cloud development environment directly from your browser or your Desktop IDE.
### Windows Subsystem for Linux
We will start up our services using a simple bash script. Windows users should download the
[Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line
functionality similar to a Linux distribution on Windows.
## Tutorials List[](https://cim.etsi.org/NGSI-LD/official/0--1.html)
### Core Context Management: NGSI-LD Fundamentals
101. [Understanding `@context`](https://github.com/FIWARE/tutorials.Understanding-At-Context)
102. [Working with `@context`](https://github.com/FIWARE/tutorials.Getting-Started/tree/NGSI-LD)
103. [CRUD Operations](https://github.com/FIWARE/tutorials.CRUD-Operations/tree/NGSI-LD)
104. [Concise Payloads](https://github.com/FIWARE/tutorials.Concise-Format/tree/NGSI-LD)
105. [Merge-Patch and Put](https://github.com/FIWARE/tutorials.Merge-Patch-Put/tree/NGSI-LD)
106. [Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships/tree/NGSI-LD)
107. [Subscriptions](https://github.com/FIWARE/tutorials.Subscriptions/tree/NGSI-LD)
108. [Registrations](https://github.com/FIWARE/tutorials.Context-Providers/tree/NGSI-LD)
109. [Temporal Operations](https://github.com/FIWARE/tutorials.Short-Term-History/tree/NGSI-LD)
110. [Extended Properties](https://github.com/FIWARE/tutorials.Extended-Properties/tree/NGSI-LD)
### Internet of Things, Robots and third-party systems
201. [Introduction to IoT Sensors](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD)
202. [Provisioning the Ultralight IoT Agent](https://github.com/FIWARE/tutorials.IoT-Agent/tree/NGSI-LD)
203. [Provisioning the JSON IoT Agent](https://github.com/FIWARE/tutorials.IoT-Agent-JSON/tree/NGSI-LD)
### Core Context Management: Manipulating Context Data and Persisting Historic Data
304. [Querying Time Series Data (QuantumLeap)](https://github.com/FIWARE/tutorials.Time-Series-Data/tree/NGSI-LD)
305. [Big Data Analysis (Flink)](https://github.com/FIWARE/tutorials.Big-Data-Flink/tree/NGSI-LD)
306. [Big Data Analysis (Spark)](https://github.com/FIWARE/tutorials.Big-Data-Spark/tree/NGSI-LD)
### Security: Identity Management
401. [Managing Users and Organizations](https://github.com/FIWARE/tutorials.Identity-Management/tree/NGSI-LD)
402. [Roles and Permissions](https://github.com/FIWARE/tutorials.Roles-Permissions/tree/NGSI-LD)
### Processing, Analysis and Visualization
507. [Cloud-Edge Computing](https://github.com/FIWARE/tutorials.Edge-Computing/tree/NGSI-LD)
### Integrating NGSI-v2 Systems:
601. [Federative Data Spaces](https://github.com/FIWARE/tutorials.Linked-Data/tree/NGSI-LD)
## Usage
Most tutorials supply a `services` script to start the containers:
```console
cd
git checkout NGSI-LD
./services start
```
### Following the tutorial exercises via Postman
Each tutorial submodule contains one or more `docker-compose.yml` files, along with a Postman collection containing the
necessary HTTP requests: import the collection into Postman and follow the instructions.
### Following the tutorial exercises from the command-line
Each submodule contains full instructions in README which details the appropriate bash commands (cUrl and Docker
Compose) to run.
Full instructions can be found within the [documentation](https://ngsi-ld-tutorials.rtfd.io/)
---
## License
[MIT](LICENSE) © 2020-2025 FIWARE Foundation e.V.