Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.1 KiB

Raw Permalink 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

JSON:API v1.1 — Error Objects

Layer: raw/official-docs/ — JSON:API v1.1 specification, "Error Objects" section verbatim. ca-tmpl Topic 4 (Error Envelope) 의 대안 3 (JSON:API errors) 비교 근거. source.pointer (JSON Pointer) 로 필드 단위 오류를 가리키는 패턴의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-error-observability-foundation	ca-tmpl Topic 4 (Error Envelope) 대안 비교 — JSON:API `errors[]` array + `source.pointer` 패턴의 표준 근거
raw/branch-notes/feature-boundary-validation-mapping-contract	경계(boundary) 입력 검증 실패 시 field-level 오류 표현 옵션으로 `source.pointer` (JSON Pointer) 비교 근거
raw/branch-notes/feature-business-rule-validation-contract	business rule 실패의 `code`/`title`/`detail` 분리 패턴 비교 — JSON:API 의 `title` (불변) vs `detail` (가변) 모델 근거

컨텍스트 / 왜 저장했는지

RFC 7807 (ProblemDetail) 과 함께 자주 비교되는 또 다른 표준. source.pointer (JSON Pointer) 로 필드 단위 오류를 가리키는 방식이 GitHub 의 errors[].field 와 ca-tmpl 의 details 에 시사점 있음. ca-tmpl 이 custom envelope 을 채택했을 때 JSON:API 의 errors[] array + source.pointer 모델을 왜/얼마나 포기/대체했는지를 평가하기 위한 1차 근거.

출처 / Source

원본 URL: https://jsonapi.org/format/#errors
아카이브 URL: (미수집)
저자 / 조직: JSON:API working group
발행일: JSON:API v1.1 (current stable)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Error Objects — Top-level placement] "Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document."

[§Error Objects — Members list] "An error object MAY have the following members, and MUST contain at least one of: id, links, status, code, title, detail, source, meta"

[§Error Objects — source.pointer] "pointer: a JSON Pointer to the value in the request document that caused the error [e.g. \"/data\" for a primary data object]"

[§Error Objects — source composition] "It SHOULD include one of the following members or be omitted: pointer, parameter, header"

[§Error Objects — title] "title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
JSONAPI-ERR-C1	JSON:API 응답에서 error objects 는 top-level `errors` 키 아래 array 로 반환되어야 함 (단일 오류여도 array)	[§Error Objects — Top-level placement] "Error objects MUST be returned as an array keyed by `errors` in the top level of a JSON:API document."	`official-standard`	JSON:API v1.1 준수 응답	top-level 에 `data` 와 `errors` 가 공존 가능하다는 뜻이 아님 (spec 별도 §)
JSONAPI-ERR-C2	error object 는 다음 멤버 중 최소 1개 를 가져야 함: `id`, `links`, `status`, `code`, `title`, `detail`, `source`, `meta`	[§Error Objects — Members list] "An error object MAY have the following members, and MUST contain at least one of: `id`, `links`, `status`, `code`, `title`, `detail`, `source`, `meta`"	`official-standard`	error object 의 멤버 구성	모든 응답에서 이 8개 필드가 모두 채워져야 한다는 뜻은 아님 (MAY)
JSONAPI-ERR-C3	`source.pointer` 는 JSON Pointer (RFC 6901) 로 request document 안에서 오류 발생 위치를 가리킴 (예: `"/data"`, `"/data/attributes/title"`)	[§Error Objects — source.pointer] "`pointer`: a JSON Pointer to the value in the request document that caused the error [e.g. `\"/data\"` for a primary data object]"	`official-standard`	request body field-level 오류 표현	query string parameter 오류 표현이 아님 — query 는 `source.parameter`, header 는 `source.header`
JSONAPI-ERR-C4	`source` 객체는 `pointer`, `parameter`, `header` 중 하나 를 포함하거나 생략 (SHOULD)	[§Error Objects — source composition] "It SHOULD include one of the following members or be omitted: `pointer`, `parameter`, `header`"	`official-standard`	source 객체 멤버 선택	셋이 동시에 와도 안 되는지 (MUST NOT) 는 본 인용 범위 밖 — SHOULD only
JSONAPI-ERR-C5	`title` 은 같은 종류의 문제에 대해 호출마다 변하지 않는 짧은 사람 대상 요약 (SHOULD NOT change from occurrence to occurrence)	[§Error Objects — title] "`title`: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem"	`official-standard`	`title` vs `detail` 분리 정책	`detail` 의 호출별 가변성 자체를 본 인용이 직접 정의하지 않음 — title 의 불변성만 명시

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- JSONAPI-ERR-C1: top-level errors[] array 구조 (단일/다중 오류 모두 array)
- JSONAPI-ERR-C2: error object 의 허용 멤버 8개와 최소 1개 요구사항
- JSONAPI-ERR-C3: source.pointer 가 JSON Pointer 표기법을 사용한다는 사실
- JSONAPI-ERR-C4: source 가 pointer/parameter/header 중 하나를 가진다는 정책
- JSONAPI-ERR-C5: title 의 occurrence-invariance SHOULD
이 자료가 증명하지 않는 것:
- category / retryable 같은 운영 친화적 1급 필드의 표준 존재 (JSON:API spec 에 없음 → ca-tmpl 의 meta 에 해당)
- HTTP status code 와 error object status (문자열) 의 정확한 동기화 규칙 — status 가 문자열이라는 점은 spec 다른 부분
- 성공 응답 envelope 모양 (별도 §, top-level data 정의)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 단일 error 객체 vs JSON:API 의 errors[] array 전환 시 client 마이그레이션 비용 (별도 평가)
- 부분 채택 (errors 만 JSON:API, success 는 custom) 의 일관성 손실 정도 (실측 필요)
- links.about 의 error catalog URL 운영 (RFC 7807 의 type URI 와 동일 역할인지 별도 ca-error-envelope 비교)

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

응답 shape 예시 (해석/구성):

{
  "errors": [
    {
      "id": "8c4f7b...",
      "status": "422",
      "code": "INVALID_TITLE",
      "title": "Invalid Attribute",
      "detail": "Title must be at least 3 characters.",
      "source": { "pointer": "/data/attributes/title" },
      "links": { "about": "https://example.com/docs/errors/INVALID_TITLE" },
      "meta": { "retryable": false }
    }
  ]
}

장점 (해석):
- source.pointer 로 form 필드 매핑이 가장 표준적
- title (불변) vs detail (가변) 분리 — 카탈로그링 친화적
- 다중 오류 표현이 자연스러움 (errors[])
단점 (해석):
- 전체 JSON:API spec (리소스 객체 구조, sparse fieldsets 등) 채택 부담 → 부분 채택 시 일관성 깨짐
- category, retryable 이 1급 아님 — meta 로 빠짐
- 성공 응답은 별도 data 레이아웃 강제 → ca-tmpl 의 envelope 과 직접 충돌
ca-tmpl custom envelope 와의 차이 (해석):
- JSON:API: errors[] array, ca-tmpl: 단일 error 객체. 다중 오류 표현이 ca-tmpl 은 details 에 의존
- category/retryable 을 JSON:API 는 1급 X → ca-tmpl 이 더 운영 친화적
표준 준수 / lock-in / client 호환성 (해석):
- 표준 준수 ↑, 부분 채택 시 표준성 손실. JS 진영의 client lib (ember-data 등) 풍부
localization / i18n 지원 여부 (해석):
- spec 자체에 i18n 없음. meta 로 처리

같은 주제 다른 official-doc / company-tech-blog:
- raw/official-docs/spring-problem-detail (대안 1 구현체 — RFC 7807/9457)
- raw/official-docs/google-api-error-format (대안 2 — gRPC google.rpc.Status)
- raw/official-docs/graphql-errors-spec (대안 4 — GraphQL errors)
- raw/company-tech-blogs/stripe-error-format (대안 5 — Stripe custom envelope)
canonical contract 섹션:
- raw/project-notes/ca-skeleton-operational-contract §3 Structured API Response Contract, §6 Operational Error Category
본 source 의 위치: ca-tmpl Topic 4 — Error Envelope, 대안 3: JSON:API errors
인용하는 wiki: (미작성)

9.1 KiB Raw Permalink Blame History