Pydantic bytes JSON Schema: validation 형식과 실제 입력 해독 맞추기
API 문서의 입력·출력 방향을 구분해야 클라이언트와 서버가 서로 다른 바이트 표현을 기대하는 일을 막을 수 있다.
Pydantic bytes JSON Schema: validation 형식과 실제 입력 해독 맞추기
바이트 필드의 입력 해독과 출력 직렬화는 서로 다른 방향의 계약이다. 서버가 입력을 올바르게 읽어도 validation 스키마가 출력용 형식을 설명하면 클라이언트는 잘못된 요청을 만들 수 있다. 문서와 실제 동작을 같은 입력 사례로 연결해 어느 방향의 설정이 쓰였는지 확인해야 한다. [1, 2, 3]
공개 원문이 보여 준 범위
Pydantic bytes JSON Schema가 validation 모드에서도 ser_json_bytes를 참조해 실제 val_json_bytes 해독과 다른 format을 설명한다는 보고다. base64 입력을 해독하는 모델이 binary 형식을 표시하는 예시가 있다. [1]
입력과 출력에서 확인할 관계
문서 담당자와 서버 담당자가 같은 사례의 입력 문자열, 해독된 바이트, 출력 문자열을 함께 기록한다. schema_mode와 declared_format, configured_input_format, decoded_hex를 비교하여 validation 스키마가 실제 입력 정책을 설명하는지 확인한다. 올바른 출력 설정만으로 입력 방향의 잘못된 설명을 승인하지 않는다. [1, 3]
승인 기준과 실패 사례
설명용 입력 계약은 base64url이다. validation 스키마도 base64url을 선언해야 하며 binary를 선언하면 이 입력 계약과 다르다. 출력 직렬화 설정이 맞더라도 입력 해독 방식의 차이는 해결되지 않는다. 형식 이름을 맞춘 뒤에는 동일한 원시 입력을 실제로 해독해 기대 바이트와 대사하는 시험을 따로 수행한다. [1, 3]
Truthound를 연결하는 검사 경계
Truthound Core 3.3.2의 ColumnPairValidator로 validation 모드에서 준비한 declared_format과 configured_input_format을 비교할 수 있다. 바이트를 실제로 해독하는 시험은 별도로 수행해 decoded_hex를 남긴다. format 이름이 맞는 것만으로 임의 바이너리 파일의 내용을 승인하지 않는다. [1, 2, 3]
다른 선택이 필요한 조건
format 이름 대조가 base64 decoder의 보안성이나 임의 바이너리 파일 안전성을 보장하지 않는다. 입력·출력 스키마를 분리해 고정하고 실제 바이트 round-trip 시험을 붙인다. 입출력이 모두 같은 포맷이면 방향 혼동이 현재 fixture에서 드러나지 않을 수 있다. [1, 3]
적용 조건
schema_mode, declared_format, configured_input_format, decoded_hex 인계표를 원시 입력과 승인 기준에서 각각 준비하고 행 식별자를 유지한다.
대안
입력·출력 스키마를 분리해 고정하고 실제 바이트 round-trip 시험을 붙인다.
한계
format 이름 대조가 base64 decoder의 보안성이나 임의 바이너리 파일 안전성을 보장하지 않는다.
근거
- 사건 확인일
- 대상 확인일
- 수정일
