SCM 부분 수정 검수: 누락·null·빈 배열의 차이
SCM 부분 수정에서 누락·null·빈 배열을 패치 형식별로 구분합니다. JSON Merge Patch와 JSON Patch의 차이, 필드 존재와 반영 결과를 대조하는 인수표를 제안합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
SCM 부분 수정은 필드 존재와 패치 형식을 함께 검수합니다. 2026-10-31 기준, null을 모든 API의 삭제 지시로 해석하지 않습니다.
품목명만 바꾸려던 요청에서 기존 메모나 태그까지 사라지는 상황을 가정해 보겠습니다. 빈칸을 공통 값으로 치환하면 유지·삭제·비움의 의도가 달라질 수 있습니다. 이 글은 요청 형식과 필드 존재·반영 결과를 연결하는 인수표를 제안합니다.
부분 수정 검수에서 먼저 고정할 조건은 무엇인가요?#
같은 대상과 초기 자료, API 버전, 요청 형식과 수정 권한을 고정합니다. 그 뒤 어떤 필드를 유지하고 바꾸며 비울지 적으세요. 전체 연동의 명세·복구 범위가 정리되지 않았다면 API 연동 개발의 데이터 계약부터 확인합니다.
입력 화면 담당자는 사용자의 변경 의도를, 연동 담당자는 매핑 후 실제 전송 JSON과 Content-Type을 준비합니다. 수신 시스템 담당자는 반영 뒤 표현과 거부 조건을 확인하세요. 이 글의 API와 자료는 가상 설계이며 특정 고객이나 공급자의 구현을 뜻하지 않습니다.
필드를 의도적으로 보내지 않은 경우와 전송 중 빠진 경우도 나눕니다. 한 요청에서 입력이 잘리는 문제는 요청 해석 전후의 상품 누락 검수처럼 별도 경로로 조사합니다. 최종 화면이 비어 있다는 이유만으로 두 문제를 같은 원인으로 묶지 않습니다.
PATCH 메서드만 알면 null의 뜻도 알 수 있나요?#
변경 문서의 형식을 함께 확인해야 합니다. RFC 5789의 PATCH 정의는 미디어타입으로 패치 문서를 식별하며 모든 구현이 지원해야 할 단일 기본 형식을 정하지 않습니다. 아래 두 형식도 같은 JSON 표현을 쓰지만 변경을 기술하는 방법이 다릅니다.
| 구분 | JSON Merge Patch | JSON Patch |
|---|---|---|
| 미디어타입 | application/merge-patch+json | application/json-patch+json |
| 변경 문서 | 변경할 멤버를 담은 JSON 값 | op·path·value 등을 담은 연산 목록 |
| 기존 memo 제거 예 | 객체의 memo 멤버에 null | 기존 /memo 경로에 remove |
| 기존 memo를 JSON null로 | 객체 멤버의 null은 제거 의미 | 기존 /memo에 replace·value:null |
RFC 7396 JSON Merge Patch는 2014년 10월, RFC 6902 JSON Patch는 2013년 4월 발표됐습니다. PATCH 정의는 2010년 3월 문서이며 세 원문의 확인일은 2026-10-31입니다. 이 표는 오늘 새로 나온 기능이나 모든 SCM API의 지원 목록을 설명하지 않습니다.
공급자가 다른 요청 형식을 제공하면 그 명세에서 미전송·null·배열의 뜻을 다시 확인하세요. 클라이언트가 Content-Type만 바꾼다고 서버의 수정 계약도 바뀌지는 않습니다. 지원 형식과 업무 검증 조건이 확인되지 않은 요청은 자동 전송하기 전에 정리합니다.
같은 초기 자료에서 누락·null·빈 배열은 어떻게 달라지나요?#
아래는 가상 품목의 초기 JSON입니다. 각 사례는 이 자료에서 독립적으로 시작하며, 앞 사례의 결과에 다음 요청을 이어 붙이지 않습니다. 실제 품목·재고 수량이나 고객 사고를 사용하지 않았습니다.
{
"label": "기존 품목명",
"memo": "기존 메모",
"tags": ["기존 태그"]
}이 초기 객체에 JSON Merge Patch를 적용한다고 가정합니다. 바꾸려는 품목명만 보내면 메모와 태그는 유지됩니다. 메모를 null로 보낸 경우와 태그를 빈 배열로 보낸 경우는 유지 요청과 나눠 판정합니다.
| 가상 패치 | 반영 뒤 확인할 상태 | 유지할 다른 값 |
|---|---|---|
| label만 새 품목명으로 전송 | label은 새 값·memo는 기존 메모 | tags는 기존 태그 배열 |
| memo:null | memo 멤버가 없음 | label·tags는 기존 값 |
| memo:빈 문자열 | memo 멤버가 있음·값은 빈 문자열 | label·tags는 기존 값 |
| tags:빈 배열 | tags 멤버가 있음·값은 빈 배열 | label·memo는 기존 값 |
| 빈 객체 패치 | 세 멤버가 기존 값으로 유지 | 초기 객체 전체 |
표는 RFC 7396의 의미에 맞춘 자사 합성 기대값입니다. 2026-10-31 임시 Python 대조로 필드 존재와 값을 재현했으며 실제 API·SDK나 전체 RFC 검증기의 실행 결과는 아닙니다. 빈 배열은 원소별 병합이나 자동 무시가 아닌 배열 값 전체 교체라는 전제를 사용합니다.
여기서 null 제거 규칙은 패치 객체의 멤버에 적용됩니다. 패치 문서 전체가 null처럼 객체가 아닌 값이면 대상 문서 전체를 대체하는 별도 경우입니다. 필드 하나를 지우는 요청과 문서 전체를 바꾸는 요청을 혼동하지 마세요.
필드에 JSON null 값 자체를 남기려면 어떻게 하나요?#
필드가 없는 상태와 필드가 있고 값이 null인 상태를 먼저 구별합니다. JSON Merge Patch의 객체 멤버에 null을 넣는 방식은 두 번째 상태를 만드는 값 대입과 다릅니다. null 값이 업무 자료에 필요하다면 API가 지원하는 수정 형식과 표현을 함께 선택하세요.
JSON Patch를 지원한다고 합의한 가상 API에서는 기존 memo를 다음 연산으로 바꿀 수 있습니다. 같은 초기 자료의 memo 멤버를 유지하면서 값을 null로 바꾸는 예시입니다. RFC 6902의 replace는 대상 위치가 존재해야 성공할 수 있습니다.
[
{ "op": "replace", "path": "/memo", "value": null }
]기존 /memo에 remove를 적용하면 해당 위치의 값을 제거합니다. 두 연산의 기대 상태를 UI의 빈칸 표시만으로 비교하지 말고 JSON의 멤버 존재 여부까지 대조하세요. JSON 멤버 제거가 DB 행 삭제를 뜻하거나 JSON null이 반드시 SQL NULL로 저장된다고 해석하지 않습니다. DB 매핑과 업무 규칙은 별도 계약입니다.
부분 수정 인수표에는 어떤 증거를 남기나요?#
변경 의도, 실제 요청, 반영 뒤 필드 존재와 값을 같은 표본으로 연결합니다. 화면·중간 매핑·직렬화 단계에서 의도가 달라지지 않았는지 확인하세요. 아래는 공급자별로 구체화할 자사 인수표 제안입니다.
| 검수 표본 | 대조할 근거 | 판정 기준 |
|---|---|---|
| 미수정 필드 유지 | 변경 의도·전송 필드 목록·초기 값 | 해당 형식의 유지 계약과 일치 |
| null·빈 문자열·빈 배열 | 실제 JSON 타입·필드 존재·반영 결과 | 서로 다른 기대 상태를 구별 |
| 필드 삭제와 null 값 대입 | 미디어타입·연산·대상 경로·최종 JSON | 합의한 표현으로 반영 또는 명확히 거부 |
| 중간 매핑·직렬화 | 입력 필드 존재와 전송 JSON의 필드 존재 | 유지를 삭제·비움으로 바꾸지 않음 |
| 필수 필드·비우기 금지 | 업무 검증 규칙·오류 상태·변경 전후 | 합의한 거부와 보존 조건 확인 |
| 수정 대상 밖의 필드 | 같은 버전의 반영 전후 JSON | 의도하지 않은 멤버 변화 없음 |
문서 형식이 맞아도 필수 필드를 지우거나 수정 권한이 없는 필드를 바꾸는 요청은 업무 검증에서 거부될 수 있습니다. HTTP 성공 여부만으로 끝내지 말고 실제 반영 상태를 확인하세요. 실패 응답을 정상적인 빈 값 처리로 바꾸지 않습니다.
같은 자료 버전으로 비교한 뒤에도 동시 수정이나 응답 유실 문제가 남는다면 원장 반영의 동시 수정·재시도 검수를 별도로 적용합니다. 배치에서 빠진 행의 제공 범위를 회수하는 문제는 AI 연동 데이터 제공 범위 축소와 구분합니다. 이 글의 검수 단위는 단일 객체의 수정 필드와 값입니다.
연동을 의뢰할 때 어떤 요청 자료를 준비하나요?#
민감정보를 제거한 초기 자료, 유지·변경·삭제 의도, 실제 요청 JSON과 Content-Type, 기대하는 필드 존재·값과 공급자 규격을 준비합니다. 이 자료로 부분 수정 인수표 초안을 협의할 수 있습니다. 비용과 소요 시간은 자료·접근·연동 범위를 확인한 뒤 합의합니다.
알파카랩스는 공개 업무 자동화 서비스에서 채널별 자료 수집·대사·시스템 전달, 공식 API 접근 조건과 예외·재처리·수동 전환·운영 인수 범위를 협의한다고 설명합니다. 이는 회사의 제공 범위에 대한 자기표기이며 특정 공급자 API의 패치 형식 지원이나 고객 성과를 뜻하지 않습니다. 공개 서비스 확인일은 2026-10-31입니다.
공급자 API·미디어타입·직렬화·업무 검증 규칙이 바뀌면 표본을 다시 검수합니다. 다음 문서 검토 예정일은 2026-11-30입니다.
SCM 부분 수정에서 자주 묻는 질문은 무엇인가요?#
- SCM API에서 null을 보내면 항상 필드가 삭제되나요?
- API가 채택한 요청 형식과 필드 계약을 확인해야 합니다. JSON Merge Patch의 객체 멤버에서는 null이 해당 멤버의 제거를 뜻하지만, 이를 모든 API의 기본 동작으로 적용하지 않습니다. JSON 표현에서 필드를 제거하는 것과 DB 행 삭제·SQL NULL 저장도 구분하세요.
- 수정하지 않는 필드는 null로 채워 보내도 되나요?
- JSON Merge Patch에서 객체 멤버를 유지하려면 해당 멤버를 패치에서 제외합니다. null로 채우면 유지와 다른 변경을 요청할 수 있습니다. 실제 공급자 명세와 중간 매핑·직렬화가 필드 존재를 어떻게 처리하는지 함께 확인하세요.
- 빈 배열을 보내면 기존 배열을 유지하나요?
- JSON Merge Patch에서는 배열을 통째로 교체하므로 빈 배열은 기존 배열 값의 유지와 다릅니다. 원소별 추가·병합으로 해석하지 않습니다. 실제 API가 배열 비우기를 허용하는지와 필수 항목 검증은 별도로 확인해야 합니다.
- JSON null 값 자체를 저장해야 하면 어떻게 하나요?
- JSON Merge Patch의 객체 멤버 null은 값 대입과 구별해야 합니다. 지원이 합의된 JSON Patch에서는 기존 경로에 replace와 value:null을 사용해 JSON null 값으로 바꿀 수 있으며 remove는 경로의 값을 제거합니다. 실제 API 지원·필드 검증·DB 매핑까지 확인한 뒤 형식을 정하세요.
- 화면에 빈칸이 보이고 API도 성공이면 검수 완료인가요?
- 빈 문자열, null 값, 필드 부재가 화면에서는 비슷하게 보일 수 있습니다. 비식별한 요청 전후 JSON에서 필드 존재와 값을 각각 대조하세요. 다른 필드의 보존 여부와 실제 거부·보류 상태까지 확인해야 합니다.
유지·삭제·비움의 요청을 인수표로 구분하세요
비식별 초기 자료·수정 의도·실제 요청과 미디어타입·기대 필드 상태로 부분 수정 인수표 초안을 협의합니다. 비용과 소요 시간은 자료·접근·연동 범위 확인 후 정합니다.
부분 수정 인수 조건 확인