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

---
title: Jackson DeserializationFeature — unknown field & null handling
source_type: official-doc
url: https://fasterxml.github.io/jackson-databind/javadoc/2.13/com/fasterxml/jackson/databind/DeserializationFeature.html
archive_url:
status: raw
confidence: high
tags: [ca-tmpl, schema, serialization, jackson, json, unknown-field]
related_projects: [ca-tmpl]
related_branches: [feature-schema-serialization-contract]
created: 2026-05-22
last_reviewed: 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: (미작성)