clean-architecture-backend-template/docs/registries/headers.yaml

# Registry: HTTP Headers
# SSOT: wiki/projects/ca-tmpl/registries/headers.yaml
# Schema owner: feature-contract-registry-governance
# Last updated: 2026-05-22
#
# Conventions:
# - HTTP header name: kebab-case (X-Request-Id, X-Tenant-Id)
# - W3C standard headers: lowercase (traceparent, tracestate)
# - mdc_key: snake_case (foundation SSOT)
# - envelope_meta_field: camelCase (envelope SSOT)

headers:
  # source: feature-operational-error-observability-foundation.md L97
  #   "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id"
  - name: X-Request-Id
    direction: both
    type: ulid
    required: false
    generated_if_missing: true
    mdc_key: request_id
    envelope_meta_field: requestId
    owner_branch: feature-operational-error-observability-foundation
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:envelope-headers

  # source: feature-api-contract-baseline.md L67
  #   "X-Api-Version은 실험/compatibility 보조 header이며 path version과 충돌하면 path가 우선"
  - name: X-Api-Version
    direction: inbound
    type: string
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-api-contract-baseline
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:api-versioning

  # source: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67
  #   "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)"
  - name: Idempotency-Key
    direction: inbound
    type: string
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-rate-limit-idempotency-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:idempotency-replay

  # source: feature-rate-limit-idempotency-contract.md L85 / foundation L85
  #   "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패"
  - name: Retry-After
    direction: outbound
    type: duration-seconds
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-rate-limit-idempotency-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:rate-limit-headers

  # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
  #   rate-limit 응답 표면 (limit/remaining/reset 3종은 표준 rate-limit signaling)
  - name: X-RateLimit-Limit
    direction: outbound
    type: numeric
    required: false
    generated_if_missing: true
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-rate-limit-idempotency-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:rate-limit-headers

  # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
  - name: X-RateLimit-Remaining
    direction: outbound
    type: numeric
    required: false
    generated_if_missing: true
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-rate-limit-idempotency-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:rate-limit-headers

  # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
  - name: X-RateLimit-Reset
    direction: outbound
    type: rfc3339-date
    required: false
    generated_if_missing: true
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-rate-limit-idempotency-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:rate-limit-headers

  # source: feature-api-compatibility-deprecation-contract.md L87
  #   "deprecation marker | OpenAPI deprecated: true + branch note | response header optional"
  - name: Deprecation
    direction: outbound
    type: rfc3339-date
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-api-compatibility-deprecation-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:deprecation-marker

  # source: feature-api-compatibility-deprecation-contract.md L87
  #   "deprecation marker | OpenAPI deprecated: true + branch note | response header optional" (RFC 8594 Sunset)
  - name: Sunset
    direction: outbound
    type: rfc3339-date
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-api-compatibility-deprecation-contract
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:deprecation-marker

  # source: feature-distributed-tracing-contract.md L64, L85
  #   "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)"
  - name: traceparent
    direction: both
    type: string
    required: false
    generated_if_missing: true
    mdc_key: trace_id
    envelope_meta_field: traceId
    owner_branch: feature-distributed-tracing-contract
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:trace-propagation

  # source: feature-distributed-tracing-contract.md L66, L85
  #   "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden"
  - name: tracestate
    direction: both
    type: comma-separated
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-distributed-tracing-contract
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:trace-propagation

  # source: feature-operational-error-observability-foundation.md L100
  #   "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id"
  - name: X-Correlation-Id
    direction: both
    type: ulid
    required: false
    generated_if_missing: true
    mdc_key: correlation_id
    envelope_meta_field: correlationId
    owner_branch: feature-operational-error-observability-foundation
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:envelope-headers

  # source: feature-tenant-context-policy.md L69, L101 (foundation)
  #   "tenant resolution 우선순위 = ... (2) 명시적 X-Tenant-Id 헤더 (admin/internal API only)" /
  #   "tenant_id | tenant context (활성 시) | downstream HTTP X-Tenant-Id (with allowlist)"
  - name: X-Tenant-Id
    direction: both
    type: ulid
    required: false
    generated_if_missing: false
    mdc_key: tenant_id
    envelope_meta_field: null
    owner_branch: feature-tenant-context-policy
    case_style: kebab
    compatibility_impact: additive
    required_test: contract-verification:tenant-header-policy

  # source: feature-security-operational-baseline.md L66
  #   "JWT Resource Server를 baseline security model로 둠" (Bearer token via Authorization header)
  - name: Authorization
    direction: inbound
    type: bearer-token
    required: false
    generated_if_missing: false
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-security-operational-baseline
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:jwt-resource-server

  # source: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ Decision Matrix)
  #   401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server 표준 challenge header
  - name: WWW-Authenticate
    direction: outbound
    type: string
    required: false
    generated_if_missing: true
    mdc_key: null
    envelope_meta_field: null
    owner_branch: feature-security-operational-baseline
    case_style: kebab
    compatibility_impact: none
    required_test: contract-verification:jwt-resource-server