doc: NGSI-LD API features not covered by the TP suite (TTF5 input)

# NGSI-LD API features not covered by the ETSI TP test suite

*Coverage-gap analysis — input for the ETSI Testing Task Force (TTF5, September 2026).*

## Purpose

This note identifies **NGSI-LD API operations and behaviours that the current

Test Purpose (TP) suite does not exercise**, so the TTF can prioritise new Test

Purposes. It is organised by NGSI-LD feature and cites TS 104-175 (API) and

TS 104-176 (HTTP binding); implementation internals are deliberately out of

scope.

## Method

The gap list was derived by **differential analysis**, not by reading the TP

tree alone:

1. The full ETSI TP suite (524 Robot Framework Test Purposes) and an independent

   NGSI-LD implementation's own functional suite were each run against the *same*

   conformant broker, under code-coverage instrumentation.

2. The two coverage profiles were compared. Code that the implementation's own

   suite exercises but the TP suite never reaches marks a candidate gap.

3. Each candidate was confirmed against the TP tree: a **confirmed gap** has

   **no Test Purpose** for the operation *and* zero coverage of the corresponding

   API paths under the TP run.

Dual evidence (no TP + never executed) makes the "confirmed" list robust; the

"partial" list is coverage-based and flagged for verification.

At identical measurement scope, the implementation's own functional suite

reached **~80.7 % line / 62.6 % branch** coverage versus the ETSI TP suite's

**~60.8 % line / 45.7 % branch**. The ~20-point line and ~17-point branch gap is

concentrated in the features below.

---

## A. Confirmed gaps — whole features with **zero** Test Purposes

### A1. Snapshot functionality — TS 104-175 §16 (data type §5.2.6.5.4)

No TP exercises any Snapshot operation:

- §16.2 Create Snapshot, §16.3 Clone Snapshot, §16.4 Retrieve Snapshot status,

  §16.5 Update Snapshot status, §16.6 Delete Snapshot, §16.7 Purge Snapshots,

  §16.8 Snapshot status-notification behaviour.

The entire Snapshot chapter is untested.

### A2. Entity Maps — TS 104-175 §14 (concept §9.6)

No TP exercises Entity Map handling, which underpins querying/retrieving

distributed Entities as unitary, paginated operations:

- §14.2 Retrieve Entity Map, §14.3 Update Entity Map, §14.4 Delete Entity Map,

  §14.5 Create Entity Map for Query Entities, §14.6 Create Entity Map for Query

  Temporal Evolution of Entities.

- The associated `NGSILD-EntityMap` request/response header and the

  continuation semantics across pages are consequently untested.

### A3. Attribute Value sub-resource — TS 104-175 §10.4.4 / §10.2.6

No TP addresses the value-only Attribute sub-resource:

- §10.4.4 Retrieve Attribute Value — `GET /entities/{id}/attrs/{attrId}/value`.

- §10.2.6 Set Attribute Value — `PUT /entities/{id}/attrs/{attrId}/value`.

The value representation (bare JSON, no `@context`, native type preserved) has

no conformance check.

### A4. Entity Type & Attribute discovery — TS 104-175 §10.6

No TP exercises the type/attribute discovery endpoints:

- §10.6.3 Retrieve available Entity Types, §10.6.4 details of available Entity

  Types, and the corresponding available-Attributes operations (§10.6.7–§10.6.8):

  `GET /types`, `GET /types/{type}`, `GET /attributes`, `GET /attributes/{attrId}`.

Note: the suite's existing "Discovery" area covers **Context Source Registration**

discovery, which is a distinct feature — the *entity* type/attribute discovery

endpoints above are not covered.

### A5. HTTP binding — selected behaviours — TS 104-176 clause 6

Much of the core binding *is* tested: method handling (including `405` with an

`Allow` header) and pagination `Link` relations are exercised by many TPs. The

following normative behaviours are, however, **not** covered:

- **§6.3.5 `NGSILD-Warning` on distributed abnormal behaviour** — the warning

  codes `110` (stale), `111` (revalidation failed), `199` (timeout / loop) and

  `299` (persistent error, e.g. a source `403`) on distributed `GET`/`HEAD`.

  **No TP asserts the header at all** — the single strongest binding gap.

- **Request-length limits** — `411 Length Required` / `413 Payload Too Large`:

  no TP.

Thin / partial (present but under-exercised, recommended for strengthening):

- **§6.2.2 Content negotiation** — `415` (1 TP) and `406` (2 TPs) are minimally

  exercised; in particular the requirement that a `406` returns the **list of

  supported representations** (rather than the entity) is not clearly asserted.

- **Pagination edge cases (§6.4.7.2 / §7.4.2.2)** — `Link` relations are broadly

  tested, but the boundary rules appear unverified: an empty result set → no

  page links; a response that returns *everything* → no `next`/`prev`; and the

  offset-past-end behaviour.

---

## B. Partial / shallow coverage — Test Purposes exist but exercise only happy paths

*(Coverage-based; recommended for confirmation against the TP set.)*

### B1. Temporal Representation of Entities — TS 104-175 §10.5

Provision and Consumption TPs exist (create / update / retrieve / query

temporal evolution), but the following are thinly or not exercised:

- Delete a single temporal **instance** and delete a temporal **attribute**

  (as opposed to the whole temporal entity).

- Partial update of a specific temporal **instance** (`instanceId` targeting).

- `appendTemporalEntityAttributes` edge cases (e.g. `noOverwrite`, mixed

  new/existing attributes).

### B2. Distributed subscriptions / Context Source notification

Context Source Registration-Subscription TPs exist, but the **notification

delivery** side of distributed subscriptions (matching, forwarded notification

assembly) is thinly covered.

### C. Method notes & limitations

- Coverage from a single implementation is a proxy: a feature could in principle

  be spec-tested through a path this implementation routes differently. The

  **confirmed** (Section A) items do not rely on that proxy — each is

  independently backed by the absence of any Test Purpose.

- Percentages are aggregate line/branch figures at a fixed measurement scope;

  they quantify the size of the gap, not its normative priority.

---

## Suggested TTF5 priority

1. **`NGSILD-Warning` + request-length limits (A5)** — small, high-value; the

   `NGSILD-Warning` codes and `411`/`413` are normative (`shall`) yet have no TP.

2. **Type/Attribute discovery (A4)** and **Attribute Value sub-resource (A3)** —

   small endpoint families with clear request/response shapes; easy, high-yield TPs.

3. **Entity Maps (A2)** — self-contained operation set (§14); important for the

   distributed-query story.

4. **Snapshot functionality (A1)** — larger chapter (§16); schedule once the

   above land.

5. **Content-negotiation & pagination edge cases (A5 thin) + temporal edge cases

   (B1)** — extend existing TPs rather than start fresh.