JSON Schema를 이용한 AI 캐릭터 설정 검증 최소 예시

이 글은 Pogee용 콘텐츠 기획으로, 생성형 AI를 사용하여 작성된 아티클입니다. 공개 프로필 화면을 실제로 확인하고 있습니다. JSON 샘플은 모두 가상의 교재이며, Pogee의 내부 구현이나 실제 대화 로그가 아닙니다. 게재 코드는 Node.js와 Ajv로 실행 확인했습니다.

AI 캐릭터 설정을 JSON으로 다룰 때, 대화 품질을 검사하기 전에 발견할 수 있는 결함들이 있습니다. 필수 필드 누락, 예상치 못한 키(key), ID 표기 오류 등이 그것입니다. 이번에는 JSON Schema를 이용해 이들을 감지하는 최소 예시를 만들겠습니다.

이 주제의 구체적인 배경으로, 2026년 10월 15일에 Pogee의 공개 캐릭터 'Barnaby'의 프로필을 열어보았습니다. 일본어 UI에는 '채팅 시작하기' 버튼이 있고, 프로필 본문은 영어로 표시되어 있습니다. 공개 본문에는 회전목마를 타고 달리는 작은 반려동물과 투자자에게 자금을 요청하는 기업적인 어투가 묘사되어 있습니다.

이름이나 역할이 빠지지 않았다는 것과, 설정의 의미가 연결되어 있다는 것은 별도의 검사입니다. 예를 들어, 반려동물이라는 설정과 기업적인 말투의 조합은 의도된 캐릭터 표현일 수 있습니다. 구조만으로 '모순'이라고 단정하지 않고, 편집상의 의도를 확인해야 합니다.

아래에서는 이 문제를 독립된 교재용 JSON으로 다룹니다. 링크의 설정, 필드명, 스키마는 본 기사를 위한 예시이며, Barnaby의 설정 파일을 가져온 것도 아니고, Pogee의 내부 데이터 형식이나 공개 API를 나타내는 것도 아닙니다.

Pogee의 공개 캐릭터 Barnaby 실 화면 (2026년 10월 15일, 일본어 UI). 프로필 본문은 영어. JSON 예시는 독립된 교재이며, 제품 내부의 형식이 아닙니다.

대상은 설정 데이터의 구조입니다. ID, 이름, 역할, 말투, 지켜야 할 조건을 정의하고, 미지의 키를 거부합니다. JSON Schema만으로 인격의 일관성, 문장의 의미, 장기 기억까지 검증할 수는 없습니다. 마지막으로, 구조적으로는 올바르지만 의미 확인이 필요한 입력도 시도해 보겠습니다.

그림 1: 합성 설정 5건의 실행 결과와 검증 범위. AI 지원으로 작성한 설명도로, 제품 화면 스크린샷은 아닙니다.

빈 작업 디렉토리에서 다음을 실행합니다. 이 예시는 CommonJS 파일로 저장하므로 확장자를 .cjs로 합니다. 실행 확인 환경은 Node.js v25.2.1, Ajv 8.18.0입니다.

npm init -y
npm install --save-exact [email protected]
# 다음 코드를 validate-character.cjs로 저장
...

Draft 2020-12의 스키마를 사용하므로, Ajv의 2020용 엔트리 포인트를 불러옵니다. 기존 프로젝트에 도입할 때도 스키마 방언과 검증기를 맞춰주세요.

const Ajv2020 = require('ajv/dist/2020.js');
const schema = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
...

additionalProperties: false로 미지의 키를 거부하고, required로 누락을 감지합니다. voice는 열거값(enum)이고, boundaries는 비어있지 않은 문자열 배열입니다. minLength는 빈 문자열을 막지만, 공백만 있는 문자열을 의미 있는 문장으로 바꾸지는 못합니다. 입력의 정규화가 필요하다면 그 방침을 별도로 정의해야 합니다.

valid: VALID
missing_voice: INVALID
/ must have required property 'voice'
...

정상적인 설정은 VALID입니다. voice를 제외하면 필수 항목 오류가 발생하고, 미정의된 secretMemory를 추가하면 미지의 속성(property)으로 거부됩니다. ID에 공백이나 대문자를 사용한 경우도 지정한 패턴에 맞지 않아 실패합니다.

allErrors를 활성화했지만, 표시되는 것은 각 케이스의 첫 번째 오류뿐입니다. 운영 환경에서는 validate.errors 전체를 보존하여 편집 화면에 반환하면 수정할 부분을 모아서 제시할 수 있습니다. 개인 정보나 비공개 설정을 로그에 그대로 출력할지 여부는 별도로 판단이 필요합니다.

semantic_conflict의 경우, 차분한 말투를 지정해 놓은 상태에서 역할 설명을 '항상 큰 소리로 말하는 접객원'으로 변경했습니다. 두 값 모두 스키마를 충족하므로 VALID입니다. 실제로 모순이라고 간주해야 할지는 사양에 따라 다르지만, 적어도 구조 검사만으로는 판단할 수 없습니다.

설정의 구조를 스키마로 검사하고, 의미적 일관성을 편집 리뷰로 확인하며, 생성된 응답을 대화 테스트로 점검합니다. 이 세 단계를 분리하면 설정 누락과 모델의 응답 품질을 혼동하기 어려워집니다. 이번 5가지 사례는 데이터 검증 확인일 뿐, 캐릭터 대화 성능 측정은 아닙니다.

먼저 저장 전에 동일한 스키마를 적용하여 오류를 항목명과 함께 반환하는 간단한 체크부터 시작합니다. 다음으로 설정 파일 변경 시에도 실행하여 필수 항목 추가 등으로 기존 데이터가 실패할 경우의 마이그레이션 방법을 결정합니다. 스키마 버전을 관리하면 이전 설정과의 호환성도 추적하기 쉬워집니다.

캐릭터의 프로필과 대화의 관계라는 배경에는 Pogee의 공개 가이드가 있습니다. 본 기사의 코드는 해당 설명으로부터 특정 내부 구성을 추정한 것이 아니라, 독립적인 교재입니다.