doc: notes towards a typed ProblemDetails discussion at TC DATA

[kzangeli]

Material for an ice-breaker at the Athens meeting, October 2026. Same register and placement as bridge-channels.md — working notes, off-nav, not a contribution and not a CR.

Unrelated to #70 in substance; it is where the @referredType bug led.

The provocation

An NGSI-LD error carries five members, of which exactly one — type, with twelve values for the whole API — is machine-readable. Everything below that is prose inside detail, whose content TS 104-175 § 8.3.3 explicitly leaves to the implementation.

So a client cannot decide between fix / drop / give up without string-matching an implementation-defined sentence, and the conformance suite cannot tell a right answer from a right status code for the wrong reason.

What's in it

• The evidence, including that we already emit three unregistered members (attributeName, registrationId, statusCode) — the window for agreeing a common vocabulary is open only while the count is small.
• Why prose clause references rot silently, with our own § 4.6.2 strings as the exhibit: GS CIM 009 numbering, all wrong the day TS 104-175 publishes, and nothing detects it.
• A menu of candidate members grouped by class — identity, offending input, diagnostics, advice, spec clause — because the classes have different rules about who reads them and whether they can be switched off.
• A recommendation against recursive error stacking: flatten and carry provenance per element, the way a stack trace is a flat list rather than a tree.

Two findings along the way

Both also filed in the spec-doubts log:

• errors/Conflict has no HTTP status code. TS 104-175 § 8.3.2 defines it and clause 10 mandates it at shall level in 27 places; TS 104-176 § 6.3.2 maps the other eleven types and omits this one, while § 6.3.3 says the status is "as per clause 6.3.2 depending on error type". Checked against GS CIM 009 V1.9.1 — identical gap, so not a TS 104 conversion artefact. (#126)
• Reference [n.6] is RFC 7807, obsoleted by RFC 9457 (2023), which is where the extension-member rules this all rests on were sharpened.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mo7DQD14mrErQD4N2v99d2

[read-the-docs-community]

Documentation build overview

📚 coraine | 🛠️ Build #34510205 | 📁 Comparing 18678fa against latest (b0682e3)

  🔍 Preview build  

1 file changed

+ problem-details.html