NGSI-LD Models

NKZ OS uses FIWARE Smart Data Models as its canonical vocabulary. Every entity in Orion-LD follows one of these types — custom types are prohibited unless no SDM match exists.

Core entity types

AgriParcel

A parcel of agricultural land. The central entity in the NKZ data model.

{
  "id": "urn:ngsi-ld:AgriParcel:parcel-001",
  "type": "AgriParcel",
  "name": { "type": "Property", "value": "Parcel 42" },
  "location": {
    "type": "GeoProperty",
    "value": { "type": "Polygon", "coordinates": [[[-1.64,42.81],[-1.63,42.81],[-1.63,42.82],[-1.64,42.82],[-1.64,42.81]]] }
  },
  "area": { "type": "Property", "value": 2.4 },
  "cropStatus": { "type": "Property", "value": "sown" },
  "refAgriFarm": { "type": "Relationship", "value": "urn:ngsi-ld:AgriFarm:farm-01" }
}

Key attributes: location (GeoJSON Polygon), area (hectares), cropStatus, refAgriFarm, category (arable/pasture/permanent).

AgriCrop

A crop grown on a specific parcel in a specific season.

{
  "id": "urn:ngsi-ld:AgriCrop:crop-001",
  "type": "AgriCrop",
  "refAgriParcel": { "type": "Relationship", "value": "urn:ngsi-ld:AgriParcel:parcel-001" },
  "species": { "type": "Property", "value": "wheat" },
  "plantingDate": { "type": "Property", "value": "2025-10-15" },
  "harvestDate": { "type": "Property", "value": "2026-06-30" }
}

AgriSoil

Soil properties for a parcel or region.

{
  "id": "urn:ngsi-ld:AgriSoil:soil-001",
  "type": "AgriSoil",
  "refAgriParcel": { "type": "Relationship", "value": "urn:ngsi-ld:AgriParcel:parcel-001" },
  "texture": { "type": "Property", "value": "silt-loam" },
  "organicMatter": { "type": "Property", "value": 2.8 }
}

AgriSensor

IoT device measuring environmental or crop data.

{
  "id": "urn:ngsi-ld:AgriSensor:sensor-001",
  "type": "AgriSensor",
  "refAgriParcel": { "type": "Relationship", "value": "urn:ngsi-ld:AgriParcel:parcel-001" },
  "category": { "type": "Property", "value": "soilMoisture" },
  "controlledProperty": { "type": "Property", "value": ["soilMoisture", "soilTemperature"] }
}

WeatherObserved / WeatherStation

Weather data points and station metadata.

{
  "id": "urn:ngsi-ld:WeatherObserved:obs-001",
  "type": "WeatherObserved",
  "temperature": { "type": "Property", "value": 23.5 },
  "relativeHumidity": { "type": "Property", "value": 0.65 },
  "precipitation": { "type": "Property", "value": 0 },
  "windSpeed": { "type": "Property", "value": 3.2 },
  "dateObserved": { "type": "Property", "value": "2026-05-21T08:00:00Z" }
}

ManufacturingMachine

Tractors, implements, and field machinery.

{
  "id": "urn:ngsi-ld:ManufacturingMachine:tractor-001",
  "type": "ManufacturingMachine",
  "category": { "type": "Property", "value": ["tractor"] },
  "trackWidth": { "type": "Property", "value": 2.1 },
  "wheelbase": { "type": "Property", "value": 2.75 },
  "hitchType": { "type": "Property", "value": "three-point" },
  "gpsOffsetX": { "type": "Property", "value": 0 },
  "gpsOffsetY": { "type": "Property", "value": -1.8 }
}

Machine roles are encoded in category: tractor, implement, harvester, sprayer.

NGSI-LD protocol rules

Content-Type negotiation

Format	Header strategy
application/ld+json	Embed @context in body. No Link header needed
application/json	Send Link header with context URL. No @context in body

Relationship naming

Use ref + target entity type: refAgriParcel, refAgriFarm, refDeviceProfile, refWeatherStation.

Legacy code may use refFarm — this is a bug, use refAgriFarm.

Batch operations

# Create multiple entities atomically
POST /ngsi-ld/v1/entityOperations/create
→ 201 (all OK) or 207 (partial success — check per-entity status)

Adding a new entity type

1. Check if a Smart Data Model exists
2. If yes, use its type name and attribute vocabulary exactly
3. If no, use Property type or a generic entity
4. Register the type in the Entity Wizard’s KNOWN_SCHEMAS (attributeSchemas.ts)
5. If the type has time-series data, add it to DATAHUB_ENTITY_TYPES

Never invent custom entity types without checking SDM first.