Files

T

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

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

8.0 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

Jackson DeserializationFeature — unknown field & null handling

Layer: raw/official-docs/ — Jackson 2.13 공식 Javadoc 의 DeserializationFeature enum 원문 발췌. ca-tmpl unknown field strict inbound / tolerant outbound + null/empty/missing 의미 분리 결정의 구현 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-schema-serialization-contract	G-F 대안 1 (Jackson default = strict on unknown by default) 의 1차 근거 + `FAIL_ON_NULL_FOR_PRIMITIVES` default=disabled 가 ca-tmpl 의 "null/empty/missing 분리" 요구와 불일치한다는 사실 + 보강 (wrapper / 명시 토글) 필요성

컨텍스트

ca-tmpl Decisionized Work Items 가 request unknown field -> fail-fast + response schema 없는 field 노출 금지 + null/empty/missing 의미 분리 로 정함. Jackson default 가 정확히 이 정책과 어디서 일치/불일치하는지, 어떤 feature 플래그로 보강 가능한지를 확정.

출처 / Source

원본 URL: https://fasterxml.github.io/jackson-databind/javadoc/2.13/com/fasterxml/jackson/databind/DeserializationFeature.html
아카이브 URL: (미수집)
저자 / 조직: FasterXML (Tatu Saloranta 외)
발행일: 2.13 Javadoc (이후 버전 동일 의미)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§FAIL_ON_UNKNOWN_PROPERTIES] "Feature that determines whether encountering of unknown properties (ones that do not map to a property, and there is no 'any setter' or handler that can handle it) should result in a failure (by throwing a JsonMappingException) or not." — Default: Enabled (exception thrown for unknown properties).

[§FAIL_ON_NULL_FOR_PRIMITIVES] "Feature that determines whether encountering of JSON null is an error when deserializing into Java primitive types (like 'int' or 'double')." — Default: Disabled (null values use default primitives like 0 or 0.0).

[§FAIL_ON_IGNORED_PROPERTIES] "Feature that determines what happens when a property that has been explicitly marked as ignorable is encountered in input: if feature is enabled, JsonMappingException is thrown; if false, property is quietly skipped." — Default: Disabled (no exception thrown).

[§READ_UNKNOWN_ENUM_VALUES_AS_NULL] "Feature that allows unknown Enum values to be parsed as null values. If disabled, unknown Enum values will throw exceptions." — Default: Disabled (exceptions thrown for unknown enum values).

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SJUF-C1	`FAIL_ON_UNKNOWN_PROPERTIES` 의 Jackson 2.13 default 는 enabled — unknown property 발견 시 `JsonMappingException` 발생	[§FAIL_ON_UNKNOWN_PROPERTIES] "...should result in a failure (by throwing a JsonMappingException) or not." Default: Enabled	`official-vendor-doc`	Jackson databind 2.13+ default 동작	Spring Boot 의 `JacksonProperties` / `@JsonIgnoreProperties` 가 이 default 를 override 하지 않는다는 뜻 아님
SJUF-C2	`FAIL_ON_NULL_FOR_PRIMITIVES` 의 default 는 disabled — JSON null 이 Java primitive 로 deserialize 될 때 silently 0 / 0.0 / false 로 변환됨	[§FAIL_ON_NULL_FOR_PRIMITIVES] "...JSON null is an error when deserializing into Java primitive types..." Default: Disabled	`official-vendor-doc`	Jackson 의 null → primitive 변환 default	wrapper type (Integer / Double) 사용 시 동일한 silent 변환이 일어난다는 뜻 아님 (wrapper 는 null 자체 보존)
SJUF-C3	`FAIL_ON_IGNORED_PROPERTIES` 의 default 는 disabled — `@JsonIgnore` 로 표시된 property 가 input 에 등장해도 조용히 skip	[§FAIL_ON_IGNORED_PROPERTIES] "...if feature is enabled, JsonMappingException is thrown; if false, property is quietly skipped." Default: Disabled	`official-vendor-doc`	Jackson 의 ignored property 처리 default	`@JsonIgnoreProperties(ignoreUnknown=true)` 와는 별개 feature — 이름 유사하나 작동 영역 다름
SJUF-C4	`READ_UNKNOWN_ENUM_VALUES_AS_NULL` 의 default 는 disabled — 알 수 없는 enum value 는 예외 발생	[§READ_UNKNOWN_ENUM_VALUES_AS_NULL] "...If disabled, unknown Enum values will throw exceptions." Default: Disabled	`official-vendor-doc`	Jackson enum deserialization default	`READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE` 등 별도 feature 의 동작은 본 인용 범위 밖

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SJUF-C1 ~ C4: Jackson 2.13 의 4가지 DeserializationFeature default 값과 정확한 작동 설명
이 자료가 증명하지 않는 것:
- Spring Boot 의 auto-configuration 이 위 default 를 어떻게 override 하는지 (spring.jackson.deserialization.* 키 별도 확인 필요)
- @JsonIgnoreProperties(ignoreUnknown=true) 가 class 단위로 FAIL_ON_UNKNOWN_PROPERTIES 를 우회하는 정확한 메커니즘 (annotation 처리 우선순위)
- 응답 serialization 시 schema 강제 (OpenAPI drift 검출) — Jackson 만으로는 부족, 별도 도구 필요
- Jackson 의 더 신버전 (2.14+ / 3.x) 에서 default 가 동일하게 유지되는지
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 ObjectMapper 빈 설정 (Spring Boot starter 의 Jackson2ObjectMapperBuilder customizer)
- FAIL_ON_NULL_FOR_PRIMITIVES=true 토글 시 기존 DTO 가 primitive vs wrapper 어느 쪽인지의 코드 스캔
- ArchUnit 등으로 @JsonIgnoreProperties(ignoreUnknown=true) 의 무분별한 사용을 금지하는 rule 설정 가능성

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

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

ca-tmpl 정합/불일치:

ca-tmpl 결정	Jackson default	정합
request unknown field → fail	`FAIL_ON_UNKNOWN_PROPERTIES=true` (default)	일치
response schema 없는 field 노출 금지	Jackson 은 직렬화 자동 — schema 강제는 OpenAPI 영역	Jackson 만으론 부족. OpenAPI drift 검증 필요
null/empty/missing 의미 분리	`FAIL_ON_NULL_FOR_PRIMITIVES=false` default → null → 0 silently	불일치: ca-tmpl 이 명시적으로 분리 요구. → `FAIL_ON_NULL_FOR_PRIMITIVES=true` 또는 wrapper (Integer) 사용 강제
enum unknown → validation failure	`READ_UNKNOWN_ENUM_VALUES_AS_NULL=false` (default) — exception	일치

실제 함정:
- Spring Boot 의 JacksonProperties 는 일부 default 를 override 할 수 있음. spring.jackson.deserialization.fail-on-unknown-properties 명시 권장.
- @JsonIgnoreProperties(ignoreUnknown=true) 가 클래스에 붙어 있으면 ca-tmpl 정책을 우회. 정적 분석 / ArchUnit 으로 금지하는 것이 좋음.
Trade-off:
- Jackson default (lenient: ignoreUnknown=true) 를 쓰면 client integration 이 쉬움. 다만 silent drift 가 누적.
- Jackson strict (default) 는 ca-tmpl 과 정합. client 변경 시 즉시 깨짐 → CI 에서 잡힘.

같은 주제 다른 official-doc:
- raw/official-docs/schema-bigdecimal-money-serialization-java (Jackson + BigDecimal)
- raw/official-docs/schema-avro-evolution-rules (Avro 의 자동 unknown-ignore 와 대조)
- raw/official-docs/schema-protobuf-vs-json-evolution (Protobuf 의 unknown 자동 보존과 대조)
인용하는 branch:
- raw/branch-notes/feature-schema-serialization-contract (G-F 대안 1)
인용하는 wiki: (미작성)

8.0 KiB Raw Blame History