Files

T

DongHyeonka 6c53ded9cb init: llm-wiki-haness 하네스 설계

2026-07-24 14:21:35 +09:00

11 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

RFC 7807 — Problem Details for HTTP APIs

Layer: raw/official-docs/ — IETF RFC 7807 의 HTTP API error envelope 표준. ca-tmpl 이 명시적으로 forbidden 으로 둔 표준 — 채택 안한 결정의 trade-off 평가 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-error-observability-foundation	ca-tmpl custom envelope vs RFC 7807 ProblemDetail 채택 결정의 표준 reference
raw/branch-notes/feature-boundary-validation-mapping-contract	boundary validation error 시 응답 shape 결정 (RFC 7807 미채택 근거)
raw/branch-notes/feature-business-rule-validation-contract	business rule violation 응답 shape 결정 (RFC 7807 미채택 근거)
raw/project-notes/ca-skeleton-operational-contract	§3. Structured API Response Contract + §6. Operational Error Category — 미채택 표준 reference

컨텍스트 / 왜 저장했는지

ca-tmpl 이 명시적으로 forbidden 으로 둔 표준. custom envelope ({success, data, error.{code,category,message,retryable,details}, meta}) 결정의 trade-off 를 평가하려면 표준의 정확한 shape, 확장 메커니즘, 한계를 먼저 알아야 함. RFC 7807 은 현재 RFC 9457 로 obsolete 되었으나 본 문서는 7807 기준 정리.

출처 / Source

원본 URL: https://datatracker.ietf.org/doc/html/rfc7807
후속 RFC (obsolete 시킴): RFC 9457 (Problem Details for HTTP APIs — 2023 revision)
Media type: application/problem+json, application/problem+xml
아카이브 URL: (미수집)
저자 / 조직: IETF (Editors: M. Nottingham, E. Wilde)
발행일: RFC 7807 — March 2016
마지막 확인일: 2026-05-27 (WebFetch 재검증 성공 — 5개 quote 모두 verbatim 일치. strength needs-confirmation → official-standard 으로 upgrade. [2026-05-25 capture] verbatim 보존본 유지)

핵심 인용 / Key quotes (verbatim)

[§3.1, captured 2026-05-22] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type."

[§3.1, captured 2026-05-22] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI."

[§3.2 — Extension Members, captured 2026-05-22] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize."

[§3.1 — status, captured 2026-05-22] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly."

[§3.1 — detail, captured 2026-05-22] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information."

[2026-05-27 verified — WebFetch 재검증 성공]: 본 5개 quote (RFC7807-C1 ~ C5) 모두 https://datatracker.ietf.org/doc/html/rfc7807 live 페이지에서 FOUND VERBATIM. §번호 확인: C1 = §3, C2/C4/C5 = §3.1, C3 = §3.2. strength needs-confirmation → official-standard (IETF RFC) 으로 upgrade. [2026-05-25 capture] verbatim 본문 유지. RFC 9457 (후속) 과의 차이는 별도 raw 작성 시 검증.

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
RFC7807-C1	problem details 의 canonical model 은 JSON object 이며, `application/problem+json` media type 으로 식별	[§3, captured 2026-05-22 + 2026-05-27 verified verbatim] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type."	`official-standard` [2026-05-27 verified, IETF RFC]	HTTP API 의 error 응답 shape	XML 응답 (`application/problem+xml`) 도 동등하게 정의되어 있으나 본 인용 범위 밖
RFC7807-C2	consumer 는 `type` string 을 problem type 의 primary identifier 로 사용해야 하며 (`MUST`), `title` 은 advisory	[§3.1, captured 2026-05-22 + 2026-05-27 verified verbatim] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI."	`official-standard` [2026-05-27 verified, IETF RFC]	RFC 7807 consumer 구현	`code` 같은 짧은 머신리더블 식별자가 표준에 1급 필드로 있다는 뜻은 아님 — `type` URI 가 식별자 역할
RFC7807-C3	problem type 정의는 추가 member 로 확장 가능 (`MAY`), client 는 알 수 없는 확장을 무시해야 함 (`MUST`)	[§3.2 — Extension Members, captured 2026-05-22 + 2026-05-27 verified verbatim] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize."	`official-standard` [2026-05-27 verified, IETF RFC]	RFC 7807 의 확장 메커니즘 (예: `balance`, `retryable` 등)	어떤 확장 필드를 표준이 권장한다는 뜻은 아님 — `code`/`category`/`retryable` 모두 확장 영역
RFC7807-C4	generator 는 problem details body 의 `status` 필드와 실제 HTTP response 의 status code 를 동일하게 사용해야 함 (`MUST`)	[§3.1 — status, captured 2026-05-22 + 2026-05-27 verified verbatim] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly."	`official-standard` [2026-05-27 verified, IETF RFC]	RFC 7807 generator 구현	HTTP status code 의 정확한 mapping (404 vs 422 등) 은 별도 표준. 본 인용은 일치 요구만
RFC7807-C5	`detail` member 는 client 가 문제를 정정하는 데 도움을 주는 데 초점을 두어야 하며, debugging 정보 제공이 아닌 (`ought to`)	[§3.1 — detail, captured 2026-05-22 + 2026-05-27 verified verbatim] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information."	`official-standard` [2026-05-27 verified, IETF RFC]	`detail` 필드의 의도된 용도	i18n / localization 표준은 별도 — `detail` 의 언어 정책은 본 인용 범위 밖. `ought to` 는 `SHOULD` 보다 약한 어조
RFC7807-C6	i18n / `Accept-Language` 기반 message localization 은 RFC 7807 표준에 명시 없음	(부재 자체가 claim — 2026-05-27 WebFetch 재검증 시에도 i18n / Accept-Language 관련 normative 진술 발견되지 않음)	`official-standard` [2026-05-27 verified — 부재 사실 확인]	다국어 error message 정책	RFC 7807 이 i18n 을 금지한다는 뜻 아님 — 구현자 책임

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것 (2026-05-22 capture + 2026-05-27 WebFetch verbatim 재검증):
- RFC7807-C1: media type application/problem+json 이 정식 IANA 등록 type
- RFC7807-C2: type URI 가 primary identifier (= 짧은 code 필드는 표준 1급 아님)
- RFC7807-C3: 확장 메커니즘 + unknown extension ignore 규칙
- RFC7807-C4: body status 와 HTTP status 일치 의무
- RFC7807-C5: detail 의 의도된 용도 (디버깅 정보 아님)
이 자료가 증명하지 않는 것:
- 성공 응답 shape (RFC 7807 은 실패 전용 — 성공/실패 비대칭)
- 짧은 머신리더블 code 필드의 표준 부재 (RFC7807-C2 의 함의 — 확장 필드 사용 필요)
- category / retryable / correlation-id 같은 운영 메타데이터 (C3 의 확장 영역)
- i18n / Accept-Language 정책 (C6)
- 외부 client 라이브러리의 실제 application/problem+json 지원 범위
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 2026-05-27 시점 재확인 + RFC 9457 (후속) 과의 차이 검토 (특히 type URI 의 안정성 요구사항, instance URI 동작)
- ca-tmpl 의 {success, data, error.{code,category,message,retryable,details}, meta} 균일 shape 가 RFC7807-C2 의 type URI primary identifier 와 어떻게 충돌하는지 (custom code 채택 trade-off)
- Spring Boot ProblemDetail API (Spring Framework 6+) 와 ca-tmpl custom envelope 의 호환성

ca-tmpl 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.

표준 vs custom 의 trade-off:
- 표준 준수도 ↑ (RFC 7807), client lock-in ↓. 단 application/problem+json content negotiation 처리 client 가 드뭄 → 실질 호환성은 custom 과 큰 차이 없음 (해석).
- 성공/실패 shape 비대칭 (실패 전용) vs ca-tmpl 균일 shape (success: false 분기) — DX 트레이드오프.
- type URI 카탈로그 운영 부담 vs custom code enum 단순성.
운영 메타데이터: category / retryable / code 모두 RFC 7807 확장 영역 (RFC7807-C3). custom envelope 으로 1급 필드 승격하는 것이 ca-tmpl 결정.
상태 코드 정합: ca-tmpl 도 RFC7807-C4 와 동일하게 HTTP status code 와 body 상태 일치 의무 (직접적 표준 인용은 아니지만 동일 원칙).

응답 shape 예시 (RFC 7807)

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc"
}

모든 필드 optional. type 미지정 시 "about:blank".
확장: top-level 에 임의 필드 추가 가능 (예: balance, accounts) — RFC7807-C3.

메모 / Notes

재검증 완료: 2026-05-27 datatracker WebFetch 재검증 성공 (5/5 verbatim, §번호 확인 — C1=§3, C2/C4/C5=§3.1, C3=§3.2).
RFC 9457 후속: 7807 은 obsolete. wiki 승급 시 9457 기준으로 업데이트할지 결정 필요.
단점 (해석): i18n 미지원, code 필드 없음 (확장 영역), 성공 응답 별도 — custom envelope 대비 운영 부담 큼.

같은 주제 다른 raw / 표준:
- RFC 9457 (Problem Details — 2023 revision) — 별도 raw 작성 후보
- Spring ProblemDetail API (Spring Framework 6+) — 별도 raw 작성 후보
인용하는 branch:
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§3, §6)
인용한 wiki 요약: (미작성)

11 KiB Raw Blame History