Problem: Ambiguity between Field/Missing and Field/Invalid error handling across parameter types

[ThalysGomes]

The current CDR error definitions for:

• urn:au-cds:error:cds-all:Field/Missing
• urn:au-cds:error:cds-all:Field/Invalid

are logically consistent, but lack clarity when applied to different parameter types (path, query, body), which can lead to inconsistent implementations and interpretation.

---

Description of the ambiguity

The specification defines:

• Field/Missing as:

  “The request is missing a mandatory field required for the API” [consumerda....github.io]

• Field/Invalid as:

  “Applies when the value of the URL parameter or request body parameter is an invalid type or violates constraints” [consumerda....github.io]

However, the specification:

• explicitly references query parameters and request body fields
• does not clearly define how these rules apply to path parameters

---

Key issues

1. Lack of clarity for path parameters

Path parameters (e.g. /payees/{payeeId}) behave differently from query/body fields:

• They are required for route matching
• If absent, the request typically does not reach the endpoint (often resulting in 404)

This raises ambiguity:

• Can a path parameter ever result in Field/Missing?
• Or should it always result in 404 (endpoint not matched)?

The current specification does not address this.

---

2. Ambiguity between validation errors and resource errors

There is no explicit guidance on when to use:

• 400 Field/Invalid
• vs 404 Resource/Invalid / Resource/NotFound

For example:

• A malformed identifier → clearly Field/Invalid
• A well-formed but non-existent identifier → unclear boundary (often treated inconsistently)

While resource errors are defined elsewhere, the decision boundary is not clearly documented.

---

Impact

This ambiguity can lead to:

• inconsistent error handling across implementations
• difficulty in validating API behaviour programmatically
• confusion when mapping between APIs with different designs (e.g. strict vs flexible endpoints)
• divergent interpretations of the same scenario between implementers

---

Suggested improvements

To improve clarity and consistency, the specification could:

1. Explicitly define behaviour per parameter type

   • Clarify how Field/Missing applies to:
     • query parameters
     • request body fields
     • path parameters (or explicitly state it does not apply)

2. Clarify validation vs resource error boundaries

   • Define clear guidance:
     • Field/Invalid → syntactic/format validation issues
     • Resource/Invalid / NotFound → valid identifier but no matching resource

3. Provide concrete examples

   • Especially for endpoints using path parameters (e.g. /resource/{id}), covering:
     • missing parameter scenario
     • invalid format
     • valid but non-existent resource

---

Summary

The current definitions are not incorrect, but they are underspecified for real-world REST usage, particularly with respect to path parameters and validation vs resource resolution.

Clarifying these areas would significantly improve consistency and developer experience across CDR implementations.