Quick Comparison

{ "nickname": null }
{}

갈리는 기준

null과 키 부재는 의미가 다르다 — 혼용하면 파싱 코드가 두 경우를 모두 처리해야 한다

{"nickname": null}은 nickname 키가 존재하며 값이 의도적으로 비어 있음을 명시합니다. 반면 {}처럼 키 자체가 없는 경우는 그 필드에 대한 정보가 전달되지 않은 상태입니다. 두 상태를 같은 의미로 처리하면 소비자는 "키가 있는데 null인 경우"와 "키 자체가 없는 경우"를 모두 체크하는 방어 코드를 작성해야 합니다. API 설계 초기에 이 두 상태의 의미를 분리해 문서화하면 소비자 코드의 암묵적 가정을 크게 줄일 수 있습니다.

PATCH에서 null과 missing의 의미는 patch 형식 계약으로 정한다

PATCH 요청에서 {"nickname": null}이 삭제인지 실제 null 저장인지, {}가 미수정인지 빈 object 교체인지는 patch 형식이 정합니다. JSON Merge Patch(RFC 7396)에서는 null이 해당 키를 삭제하라는 신호이고, 키 생략은 변경하지 않는다는 의미입니다. JSON Patch나 도메인 전용 PATCH는 다른 규칙을 가질 수 있으므로, 팀 내 API 문서에 사용하는 media type과 두 상태의 의미를 예제와 함께 명시합니다.

PATCH 해석 예
{ "nickname": null }  →  닉네임을 명시적으로 비운다 (삭제)
{ }                   →  닉네임을 건드리지 않는다 (유지)

JSON Schema에서 required와 null 허용은 서로 다른 관심사다

JSON Schema의 required는 키 존재 여부를 검증합니다. required: ["nickname"]이 선언되어 있으면 키 자체가 없으면 검증 실패입니다. 그러나 키가 있고 값이 null이라면 required는 통과합니다. JSON Schema 2020-12에서 null 허용은 type: ["string", "null"] 또는 anyOf로 표현합니다. nullable은 JSON Schema 키워드가 아니라 OpenAPI 3.0의 Schema Object에서 쓰이던 확장 규칙입니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "nickname": { "type": ["string", "null"] }
  },
  "required": ["nickname"]
}

OpenAPI 문서와 JSON Schema validator가 같은 표현을 항상 같은 방식으로 처리한다고 가정하지 않습니다. 사용하는 OpenAPI 버전, validator dialect, request와 response의 null 의미를 각각 확인합니다.

"없음", "알 수 없음", "의도적 초기화"를 한 값으로 표현하면 소비자마다 해석이 달라진다

좋은 API는 null 하나로 여러 의미를 뭉개지 않습니다. 예를 들어 null이 "데이터가 아직 수집되지 않음"인지, "의도적으로 값을 없앤 것"인지, "해당 없음"인지를 구분하려면 별도 필드나 enum 값을 사용하는 것이 더 명확합니다. GraphQL API에서 null과 필드 부재를 명확히 구분하는 설계가 있는 이유도 여기에 있습니다. 이 구분이 과도하다면 최소한 null의 의미를 API 문서에 하나로 고정해야 합니다.

{ "nickname": null }

선택 기준

주의할 점

{}

null과 키 생략을 같은 의미로 처리하면, PATCH에서 "삭제"와 "유지"를 분리할 수 없게 됩니다. 이 차이는 초반에 문서로 고정해 두는 편이 좋습니다.

응답 설계에서도 마찬가지입니다. nickname: null이 "아직 모름"인지 "일부러 비움"인지 문서가 없으면 소비자마다 다른 화면과 저장 로직이 생깁니다.