Document empty-list, 400/422, and GENERATE credential conventions

[clundie-CL]

Problem description

Three small documentation gaps surfaced during review of #120. Each is small enough that an individual issue would be overkill; consolidating here.

1. Empty-collection response shape

The spec does not document what list endpoints return when the underlying collection is empty. Affects:

• GET /trust-domains
• GET /trust-domains/{id}/devices
• GET /network-access-devices
• GET /reboot-requests
• GET /services

CAMARA convention is 200 OK with [], but NAM doesn't say so. Without explicit documentation, test authors can't write reliable assertions and implementers can choose 404 or [] inconsistently.

2. 400 vs 422 error-code boundary

POST /reboot-requests and PATCH /reboot-requests/{id} (and other write endpoints) document both 400 and 422 as possible error responses. The spec has limited specifics — the info.description mentions 422 MISSING_IDENTIFIER for the default-device-inference-failure case, but no general guidance on which class of error triggers which code.

CAMARA convention is roughly:

• 400 = malformed/parse/schema-violation error
• 422 = request is syntactically valid but semantically unprocessable

A short paragraph in info.description (or per affected endpoint) calling out this boundary would unblock test authoring and align with the Commonalities error model.

3. Where the GENERATE credential value goes

updateTrustDomainDevice with credentialAction: "GENERATE" (schema GenerateDeviceCredential) instructs the server to generate a per-device credential. The schema's description says "The generated credential is exchanged with the device during bootstrapping (DPP, Matter, etc.)" — so the credential goes to the device, not to the API caller. The caller only receives selectedType (which credential type was used).

This is the right security model (the caller doesn't need the device's PSK), but it's easy to miss when reading the spec. The PR #120 test reviewer expected a generated value to appear in responses and asserted against it being absent, which under the current model is vacuously true.

The fix is a one-paragraph clarification on GenerateDeviceCredential (or on DeviceCredential overall) making it explicit that under GENERATE:

• The server generates a credential of type selectedType
• The credential value is never returned to the API caller
• The credential is exchanged with the device via the bootstrapping channel (DPP, Matter, WKSO)

If the API ever needs to return a generated value to the caller (some future use case), that's a separate change.

Expected action

1. Add a sentence to the spec's info.description (or to each list operation's description) stating that empty collections are returned as 200 OK with an empty array.
2. Add a paragraph to info.description clarifying the 400-vs-422 boundary for create/update endpoints (malformed vs semantically unprocessable). NAM-specific 422 cases (currently MISSING_IDENTIFIER) can be enumerated under the rule.
3. Add a paragraph to the GenerateDeviceCredential schema description in code/modules/TrustDomainDevices/TrustDomainDevices.yaml making explicit that the generated credential value is exchanged with the device via the bootstrapping channel and is never returned to the API caller. Optionally add the inverse note on AssignDeviceCredential (where the caller provides the value).

Additional context

• All three were surfaced during review of 52 create gherkin feature file #120. None individually warrants a separate issue; the corresponding test scenarios were left in their current state pending these clarifications.
• The empty-collection convention is widely standard across CAMARA APIs but isn't part of a centrally-binding document I can cite; pinning it locally in NAM is appropriate.
• The 400-vs-422 boundary aligns with the Commonalities error model. A larger spec-side change — sub-classifying NAM's 422 cases (today there's just one) — is out of scope here; this issue is just about documenting the boundary, not extending it.
• The GENERATE credential delivery model is already implied by the existing GenerateDeviceCredential.description text but is buried; the fix is making it impossible to miss.
• Related: 52 create gherkin feature file #120 (the PR where these surfaced).
• Related: Document bootstrappingInfo and deviceCredential.value read-back policy #124 (read-back policy for bootstrappingInfo and deviceCredential.value; adjacent to item 3 — value is effectively write-only-from-the-API-caller-perspective in the GENERATE case, which Document bootstrappingInfo and deviceCredential.value read-back policy #124's framing should accommodate).

[clundie-CL]

Add to the list: TrustDomainUpdate.accessDetails description says "To remove all access types, clients MAY provide an empty array," but the schema enforces minItems: 1 (added in #135), so an empty array is rejected. Reconcile the prose with the constraint.