llm-wiki/raw/official-docs/schema-jackson-unknown-field-handling.md

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

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
Jackson DeserializationFeature — unknown field & null handling	official-doc	https://fasterxml.github.io/jackson-databind/javadoc/2.13/com/fasterxml/jackson/databind/DeserializationFeature.html		raw	high	ca-tmpl schema serialization jackson json unknown-field	ca-tmpl	feature-schema-serialization-contract	2026-05-22	2026-05-27

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 에서 잡힘.

Related / 관련

• 같은 주제 다른 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: (미작성)