Entities

You write entities one at a time under /ngsi-ld/v1/entities, or many at once under /ngsi-ld/v1/entityOperations. The operations differ in what they do with attributes the entity already has, and the difference matters, because a write that looks like another one can remove data you meant to keep. Create makes a new entity. Append and update change attributes, and merge and replace change the entity as a whole. Delete removes an attribute or an entity. This page covers what the operations share, and each of them has a page of its own.

Choosing a verb

Update, merge and replace differ in how much they throw away. An update or a replace of an attribute swaps a whole attribute instance. A merge descends into what is there and changes only the members you name. A replace of the entity takes the body as the whole entity. Sending the wrong one does not fail. It answers 204 and quietly drops data you meant to keep.

• To change one value and keep the rest of the attribute, use a partial attribute update, or a merge when the value is an object you want to change inside.
• When the new reading is the whole truth, use update or replace attribute. A stale sub-attribute dies with it, which is usually what you want and occasionally not.
• To remove individual members, merge with the NGSI-LD Null on each one.
• To start the entity over, replace the entity, because nothing survives that the body does not name.
• To add something, append, or merge, which also adds what it does not find.

Sending a write

Every write carries a body, a Content-Length and a Content-Type. The body is application/json, or application/ld+json with the @context in the body. A merge also takes application/merge-patch+json.

• A missing Content-Length is refused with 411.
• A missing or unsupported Content-Type is refused with 415 and no body.

With application/json, your own @context, if you have one, goes in a Link header. In Rust the client carries the context and sends the header on every request.

http

POST /ngsi-ld/v1/entities
Content-Type: application/json
Link: <https://example.org/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

{
    "id": "urn:ngsi-ld:Vehicle:A4567",
    "type": "Vehicle",
    "speed": {
        "type": "Property",
        "value": 52
    }
}

curl

curl -i http://localhost:1056/ngsi-ld/v1/entities \
  -H 'Content-Type: application/json' \
  -H 'Link: <https://example.org/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
  -d '{
    "id": "urn:ngsi-ld:Vehicle:A4567",
    "type": "Vehicle",
    "speed": {
        "type": "Property",
        "value": 52
    }
}'

rust

let contextual = client.with_context(IriRefBuf::new("https://example.org/context.jsonld")?)?;

let vehicle = Entity::builder()
    .id(iri!("urn:ngsi-ld:Vehicle:A4567"))
    .entity_type("Vehicle")
    .property("speed", 52)
    .build()?;

let outcome = contextual.entities().create(&vehicle).send().await?;

python

response = requests.post(
    f"{BASE}/entities",
    headers={
        "Link": '<https://example.org/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"',
    },
    json={
        "id": "urn:ngsi-ld:Vehicle:A4567",
        "type": "Vehicle",
        "speed": {
            "type": "Property",
            "value": 52,
        },
    },
)
assert response.status_code == 201

The examples below leave the Link header out. JSON-LD @context covers both ways of sending a @context.

What a write stores

A write stores exactly what it validated. Numbers keep their value, date-times must be in UTC, and units must be UN/CEFACT codes. Values has the details.

A write that leaves the entity as it was answers as a success, stores nothing and notifies nobody. Writes explains what counts as a change. Writes that change something are also recorded in the entity's history, which the temporal guide shows how to read.

What gets refused

• 400 BadRequestData when the body breaks a rule of the data model, such as an id that isn't a URI or a JSON null. The detail names the member. Strictness lists the rules.
• 404 ResourceNotFound when the entity, or the attribute, doesn't exist.
• 411 when the Content-Length header is missing.
• 415 with no body when the Content-Type is missing, or the operation doesn't take it.

Each operation page lists what else it refuses.