JSON Schema 글자 수 검수JSON Schema maxLength 한글 이모지문자열 길이 코드포인트 grapheme프런트 서버 글자 수 불일치

JSON Schema 글자 수 검수, 한 글자인데 왜 길이 초과일까

JSON Schema의 길이는 화면 글자 수와 다를 수 있습니다. 한글 자모·결합문자·이모지 8표본으로 코드포인트, JavaScript 길이, 분절 수를 대조하고 화면·서버 인수 기준을 정리합니다.

이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스

발행 ·알파카랩스

JSON Schema의 길이는 코드포인트 수입니다. 2026-11-20 확인 기준, 화면에서 보이는 한 글자와 다를 수 있습니다.

입력 화면은 한 글자라고 안내하는데 서버는 길이 초과로 거절할 수 있습니다. 한글이 조합된 방식, 악센트의 결합, 여러 문자를 이은 이모지 때문에 길이 계산 단위가 달라지는 경우입니다. 허용치를 늘리기 전에 같은 원문을 화면과 서버에서 비교해야 합니다.

이 글은 업무도구의 입력 필드나 AI가 반환한 JSON 문자열을 인수할 때 쓸 검수 기준입니다. 아래 제한과 입력은 설명용 합성 예시이며 실제 고객 장애나 수행 성과가 아닙니다. 고립된 surrogate 같은 비정상 문자열은 이번 표본에서 제외했습니다.

한 글자인데 maxLength를 넘는 이유는 무엇인가요?#

화면에서 한 덩어리로 읽히는 문자와 코드포인트는 같은 단위가 아닙니다. JSON Schema의 길이 제한은 코드포인트를 기준으로 비교하고, JavaScript 문자열의 기본 길이는 UTF-16 코드 단위로 셉니다. 사용자에게 안내할 글자 수를 어느 기준으로 정했는지 먼저 확인합니다.

JSON Schema Core 2020-12는 문자열을 Unicode 코드포인트의 문자열로 설명합니다. Validation의 maxLength·minLength는 문자열 길이의 상한·하한을 정합니다. 글자처럼 보이는 묶음마다 하나로 세거나 자동으로 정규화하라는 설정은 아닙니다.

ECMAScript 2026의 String 길이와 혼동하면 이모지를 화면에서 먼저 거절할 수도 있습니다. 예를 들어 아래 웃는 얼굴은 코드포인트 1개지만 JavaScript의 length는 2입니다. 화면과 서버가 같은 숫자 제한을 갖고 있어도 서로 다른 길이를 비교하면 결과가 달라집니다.

사용자가 인식하는 문자 경계가 필요하면 Unicode UAX #29의 grapheme cluster를 별도로 확인합니다. 분절 수는 그 경계를 기준으로 센 묶음 수입니다. 글꼴에 보이는 모양을 무조건 하나로 세는 방식이나 JSON Schema 길이의 대체 정의로 해석하지 않습니다.

어떤 문자열을 같은 조건으로 대조하나요?#

합성 스키마의 상한을 1로 고정하고 같은 입력을 길이 단위별로 비교합니다. 아래 스키마는 문자열 값 하나를 검증하는 예시입니다. 실제 업무의 필수 여부·공백 처리·필드 구조는 별도로 정해야 합니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "maxLength": 1
}

아래 가운데 열은 코드포인트 / JavaScript length / 확장 grapheme 분절 수 순서입니다. maxLength 판정은 Python jsonschema 4.26.0의 Draft202012Validator로 실행했습니다. JavaScript 길이와 분절 수는 Node.js 25.2.1·ICU 78.1·Unicode 17.0에서 관측했습니다. Unicode 18 전체 적합성 시험이나 운영 브라우저의 결과를 대신하지 않습니다.

합성 문자열코드포인트 / JS.length / 분절 수상한 1 판정
영문 A1 / 1 / 1적합
완성형 가: U+AC001 / 1 / 1적합
자모 ᄀ+ᅡ: U+1100 U+11612 / 2 / 1부적합
완성형 é: U+00E91 / 1 / 1적합
e+결합 악센트: U+0065 U+03012 / 2 / 1부적합
웃는 얼굴: U+1F6001 / 2 / 1적합
가족 ZWJ 이모지7 / 11 / 1부적합
빈 문자열0 / 0 / 0적합
출처: 알파카랩스 로컬 합성 검증 8표본, 2026-11-20. 길이 단위와 실행 버전을 고정한 관측이며 실제 고객 데이터·성능 수치가 아닙니다.

자모 행의 더하기 기호는 문자 구성 설명이며 입력에는 넣지 않았습니다. 가족 행은 남성·여성·소녀·소년을 ZWJ 3개로 잇는 문자열입니다. 분절이 1개여도 maxLength 1을 통과하지 않는 예시입니다. 빈 문자열은 상한만 검사하면 적합하므로 빈값을 금지할 때는 최소 길이와 업무 규칙도 확인해야 합니다.

인수표에는 원문 코드포인트, 화면 안내의 길이 단위, 서버 스키마, 실행 버전, 정규화 적용 시점과 기대 판정을 함께 적습니다. 사용자 화면은 허용한 입력을 서버가 거절하는지, 화면이 미리 막은 입력을 서버는 허용하는지 양쪽을 대조하세요. 글자 수 경고와 실제 전송 차단을 같은 동작으로 간주하지 않습니다.

정규화하거나 한 글자로 자르면 해결되나요?#

자동 보정 전에 원문과 적용 정책을 확인해야 합니다. 이 합성 표본의 자모와 결합 악센트는 NFC 뒤 코드포인트 수가 줄지만, 가족 ZWJ 이모지는 NFC 뒤에도 7개였습니다. 정규화가 화면 글자 수와 모든 길이 제약을 같게 만들지는 않습니다.

식별자에 적용할 변환·충돌 판정은 품목 코드 Unicode 정규화 검수에서 별도로 다룹니다. 이번 길이 검수만으로 원문을 덮어쓰거나 코드의 업무 동일성을 결정하지 않습니다. 잘라내기를 도입한다면 분절 경계를 깨뜨리지 않는지와 변경된 값의 업무 의미를 별도로 검수해야 합니다.

또한 분절 수 제한만으로 저장 크기를 제한할 수는 없습니다. UAX #29 rev49는 문자 수 제한과 데이터 크기 제한을 구별하는 주의를 추가했습니다. 저장·전송의 바이트 한도는 인코딩을 정해 따로 검사합니다. 같은 완성형 가가 코드포인트 1개, UTF-8 3바이트인 것도 이번 재현에서 확인했습니다.

문자열 길이 하나를 맞추는 데 온톨로지나 그래프 저장소가 필요한 것은 아닙니다. 원천 필드 정의와 화면·서버 계약을 먼저 맞출 수 있습니다. 알파카랩스 온톨로지 구축 서비스는 원천 필드·변환 규칙·표본 대사·검수 범위 협의를 공개 제공 방식으로 설명합니다. 이 회사 설명을 특정 오류의 해결 실적이나 정확도 보장으로 확대하지 않습니다.

어떤 문서와 실행 버전을 확인했나요?#

2026-11-20에 JSON Schema 2020-12 Core·Validation, ECMAScript 2026, Unicode UAX #29 rev49를 확인했습니다. JSON Schema 본문의 게시일은 2022-06-16, UAX 문서일은 2026-09-01이며 Unicode 공개 이력에 기록된 Unicode 18 공개일은 2026-09-16입니다. 확인일과 새 규격의 발표일을 구분합니다.

Python jsonschema v4.26.0 구현과 합성 실행을 대조했습니다. 분절 관측에 쓴 Node 런타임의 Unicode는 17.0이므로 Unicode 18의 새 문자·전체 분절 규칙 지원을 검증했다고 주장하지 않습니다. 브라우저·서버·검증기나 Unicode 버전이 바뀌면 실제 업무 문자열로 기대값을 다시 확인해야 합니다.

JSON Schema 날짜 형식 검수는 형식 검사기의 실행 조건을 다룹니다. 이번 길이 비교가 통과해도 날짜·식별자 존재·업무 의미까지 맞는다는 뜻은 아닙니다. 각 제약이 무엇을 검사했는지 인수표에 나눠 남깁니다.

자주 묻는 질문#

JSON Schema maxLength는 화면 글자 수인가요?

이 글에서 다루는 정상 Unicode 문자열에서는 코드포인트 수를 기준으로 비교합니다. 사용자가 한 글자로 인식하는 grapheme 묶음 수와 다를 수 있습니다.

JavaScript length와 서버 검증이 왜 다른가요?

JavaScript의 기본 길이는 UTF-16 코드 단위 수입니다. 웃는 얼굴 이모지처럼 코드포인트 1개가 코드 단위 2개인 입력을 같은 표본으로 대조해야 합니다.

NFC로 바꾸면 길이 문제가 모두 해결되나요?

아닙니다. 합성 자모·악센트 표본은 줄었지만 가족 ZWJ 문자열은 NFC 뒤에도 코드포인트 7개였습니다. 정규화와 허용 길이 단위는 각각 정해야 합니다.

maxLength만 있으면 빈 문자열도 통과하나요?

이 글의 type string과 maxLength 1 스키마에서는 빈 문자열이 적합했습니다. 빈값 금지는 최소 길이와 필수 필드·공백 정책을 별도로 확인해야 합니다.

grapheme 수를 제한하면 저장 용량도 제한되나요?

문자 묶음의 개수와 인코딩된 바이트 수는 다릅니다. 저장·전송 한도가 있다면 인코딩과 바이트 한도를 별도 인수 조건으로 정합니다.

문자열 길이 인수표 초안을 정리합니다#

비식별 정상·거절 문자열과 현재 화면의 안내 문구, 서버 스키마를 준비하세요.

문자열 길이 인수표 초안을 정리합니다

첫 범위 협의에서 비식별 문자열·화면 안내·스키마를 대조해 문자열 길이 인수표 초안을 정리합니다. 소요 시간은 원천·실행 환경·표본 범위를 확인한 뒤 안내합니다.

문자열 길이 인수표 초안 협의