OpenAPI NDJSON 검수, 한 줄이 통과하면 전체도 끝난 걸까요

2026년 11월 기준, itemSchema는 NDJSON 항목에, schema는 응답 전체에 적용합니다. 항목이 유효해도 전체 기준은 실패할 수 있습니다.

상태 목록을 NDJSON으로 내려주는 가상 API를 생각해 보겠습니다. 먼저 도착한 항목은 형식이 맞지만, 예시 인수 조건이 두 건 이상이라면 한 건만 수신한 응답은 완료 기준을 충족하지 못합니다. 항목이 유효한 시점과 전체 응답을 완료로 표시하는 시점을 구분합니다.

OpenAPI에서 항목과 전체는 어떻게 검수하나요?#

OpenAPI 3.2.1에서 itemSchema는 순차 응답의 각 항목에 독립적으로 적용됩니다. schema는 같은 항목들을 순서대로 배열로 해석해 응답 전체에 적용합니다. 둘 다 쓸 수 있습니다. 아래 예시의 전체 스키마는 items에 같은 항목 규칙을 두고 minItems: 2와 uniqueItems: true를 추가합니다. 두 건과 중복 기준은 예시에서 정한 조건입니다. OpenAPI 3.2.1 순차 매체

NDJSON은 개행으로 JSON 항목을 구분합니다. 수신 바이트를 버퍼에 모아 개행까지 읽은 뒤 해석하면, UTF-8 글자 중간에서 수신 조각이 나뉘어도 한 항목으로 처리할 수 있습니다. 아래 예시에서 각 항목에는 문자열 ID와 ready 또는 hold 상태가 필요합니다. NDJSON 1.0.0 §3

어떤 입력으로 인수 기준을 확인하나요?#

아래 표는 NDJSON 수신 구조, 항목 스키마를 통과한 개수, 응답 전체 스키마 판정을 각각 보여줍니다. 구조를 읽을 수 없는 경우 앞서 읽은 정상 항목 수만 남기고 전체 스키마 검사는 실행하지 않습니다.

첫 행의 응답 본문입니다. 각 줄의 끝에는 개행이 있습니다.

{"id":"가","state":"ready"}
{"id":"B","state":"hold"}

인수표에는 수신 구조 판정, 항목별 검수 결과, 전체 판정, 저장 여부를 적습니다. 예시에서는 전체 판정이 나오기 전까지 결과를 임시 상태로 둡니다. 정상 줄 뒤에 연결이 끊겨도 전체 스키마를 통과할 수 있습니다. 실제 인수에서는 HTTP 전송이 정상 종료됐는지와 업무에서 기대한 종료 조건을 따로 확인합니다. 형식 오류나 전체 조건 위반이 발생하면 완료 처리를 보류합니다.

항목이 계속 오는 스트림에도 전체 검사가 필요한가요?#

끝이 정해지지 않은 스트림은 운영에서 의미 있는 구간이나 창을 정해 검수할 수 있습니다. 전체 검사를 적용하려면 어떤 응답이나 구간을 배열로 비교할지 합의합니다. 일부 저장을 허용하는 업무라면 저장한 위치와 재개 기준을 따로 정합니다.

uniqueItems는 객체 전체가 같은지를 봅니다. 상태가 다르면 같은 ID를 가진 두 객체도 예시 스키마를 통과합니다. ID 단위 중복은 별도의 업무 규칙에서 검수합니다. 상태 결과를 항목별로 대조하는 방법은 SCM 일괄 처리 검수, 줄과 레코드가 어긋나는 다른 사례는 SCM CSV 검수에서 확인할 수 있습니다.

어떤 자료로 확인했나요?#

• OpenAPI 3.2.1 2026년 9월 10일 공개. 항목 검사와 배열로 해석한 전체 검사의 범위를 확인했습니다.
• OpenAPI 순차 JSON 레지스트리와 NDJSON 1.0.0에서 매체 유형과 개행·인코딩 규칙을 대조했습니다.
• 알파카랩스 업무 자동화·API 연동 서비스는 예외·재처리와 운영 인수 조건의 협의 범위를 안내합니다.

공개 문서는 2026년 11월 12일 확인했습니다. 시험은 합성 데이터와 로컬 조립·검사 코드로 진행했습니다. 실제 HTTP 연결, 생성 SDK, 적재 동작은 시험 범위에서 제외했습니다.

자주 묻는 질문#

NDJSON 적재 인수 범위를 정할 때#