[ADP-403] Problem Type Design

Core Principles

1. URI Reference: MUST be a human-readable URI reference.

   TIP

   According to RFC 9457, the type field must be a relative or absolute URI. In practice, the type should be designed to be human-readable. Avoid opaque or meaningless URIs such as /1234088abc—prefer descriptive, hierarchical URIs.

2. Relative URI: When the publication location is uncertain, MAY use a relative URI reference.

Design Process

1. Review existing HTTP status codes, referencing ADP-200.
2. For exact matches, use type: about:blank or the URI reference conversion of the HTTP status code (e.g., /problems/not-found).
3. Use the detail field to provide methods for correcting errors.
4. If there is no matching status, consult the predefined problem type list.
5. Propose new types when necessary, ensuring they are general enough.
6. Use the errors field to describe multiple errors.

[DEPRECATED] Subtype/extraType Design

Note: This section is historical. The use of an extraType field is now discouraged. All problem classification should be done via the type URI, using hierarchical or descriptive paths as needed.

Previously, it was considered to introduce an extraType field for more granular subtypes. The recommended practice now is to encode all specificity into the type URI, for example:

{
  "type": "https://example.com/problems/authentication-error/user-not-found",
  "title": "Authentication Error",
  "status": 409,
  "detail": "Your session has expired due to JWT",
  "errors": []
}

Do not use extraType. Always use a descriptive type URI to represent all levels of problem classification.

RFC 9457 Compliance Guidelines

1. Problem types MUST be general, not product-specific.
2. SHOULD maximize reuse of existing problem types.
3. Use about:blank when HTTP status codes are sufficient. Refer to ADP-402.
4. Refer to ADP-406 for more examples of types.

References

• Problem Details Registry
• RFC 9457

Changelog

• 2025.05.09: Remove product specific type design