핵심 정리
| keyword | 의미 |
|---|---|
contentEncoding | 문자열 payload가 어떤 방식으로 인코딩됐는지 |
contentMediaType | 디코딩한 내용의 미디어 타입 |
contentSchema | 디코딩한 내용이 JSON일 때 적용할 schema |
format | 값의 일반 형식 힌트 |
pattern | 문자열 자체의 정규식 검증 |
{
"type": "string",
"contentEncoding": "base64",
"contentMediaType": "image/png"
}표현 경계
JSON 문자열 안에 JSON이 아닌 데이터를 넣을 때 쓴다
JSON은 binary 값을 직접 담지 않습니다. 이미지, 압축 데이터, 인증서, 첨부 파일 같은 binary payload를 넣어야 한다면 보통 base64 문자열로 인코딩합니다. contentEncoding과 contentMediaType은 이 문자열이 단순 text가 아니라 어떤 방식으로 인코딩된 어떤 종류의 데이터인지 설명합니다.
{
"avatar": {
"type": "string",
"contentEncoding": "base64",
"contentMediaType": "image/png"
}
}이 정보는 문서화, UI 생성, API 클라이언트 생성에 유용합니다. 다만 validator가 실제 base64 디코딩이나 PNG 검증까지 수행하는지는 구현마다 다를 수 있습니다.
contentSchema는 문자열 안의 JSON 문서에 쓰인다
문자열 값 안에 다시 JSON document가 들어가는 경우가 있습니다. 예를 들어 메시지 payload가 문자열로 감싸진 JSON이라면 contentMediaType: "application/json"과 contentSchema로 내부 JSON의 구조를 설명할 수 있습니다.
{
"type": "string",
"contentMediaType": "application/json",
"contentSchema": {
"type": "object",
"required": ["event"],
"properties": {
"event": { "type": "string" }
}
}
}가능하다면 JSON 안에 JSON 문자열을 넣기보다 object로 직접 표현하는 편이 낫습니다. 문자열 안 JSON은 escape, 이중 parse, 오류 위치 추적을 어렵게 만듭니다.
검증 keyword와 annotation 성격을 구분한다
contentEncoding과 contentMediaType은 많은 도구에서 주석이나 힌트처럼 취급됩니다. pattern처럼 문자열 자체를 직접 검사하는 keyword와 다릅니다. 실제로 base64 형식이 맞는지, 디코딩한 결과가 미디어 타입과 일치하는지는 애플리케이션 검증 단계에서 추가 확인이 필요할 수 있습니다.
선택 기준
| 상황 | 선택 |
|---|---|
| binary를 JSON에 포함 | base64 string + contentEncoding |
| 파일 종류를 설명 | contentMediaType |
| 문자열 안 JSON 구조 설명 | contentSchema |
| 단순 이메일, URI 형식 | format |
| 문자열 패턴을 강제 | pattern |
| 큰 파일 전송 | JSON 본문보다 별도 업로드 URL 검토 |
주의할 점
contentEncoding을 선언했다고 해서 모든 validator가 실제 디코딩 검증을 수행하는 것은 아닙니다. 보안이나 파일 처리에 중요한 payload라면 애플리케이션에서 크기, media type, magic number, decoding 실패를 별도로 확인해야 합니다.
큰 binary를 base64로 JSON에 넣으면 크기가 커지고 streaming 처리도 어려워집니다. 대용량 파일은 JSON에 직접 넣기보다 object storage URL, multipart upload, 별도 attachment API로 분리하는 편이 안정적입니다.
참고 링크
1 sources