JSON 객체에서 Python 클래스 생성하기: python-jsonschema-objects 활용 가이드

JSON 스키마로부터 Python 클래스 자동 생성

JSON 데이터를 다루다 보면 객체를 파이썬 클래스처럼 속성 기반으로 접근하고 싶을 때가 많습니다. 이럴 때 python-jsonschema-objects 라이브러리를 사용하면 매우 편리합니다. 이 라이브러리는 널리 쓰이는 jsonschema 패키지 위에 구축되어 있으며, JSON 스키마로부터 자동으로 클래스 기반 바인딩(class-based binding)을 생성해 줍니다.

즉, JSON 스키마만 정의해 두면 별도의 클래스 코드를 직접 작성하지 않고도 타입 검증이 포함된 파이썬 객체를 즉시 사용할 수 있습니다.

1. 샘플 JSON 스키마 정의

먼저 예제로 사용할 JSON 스키마를 살펴보겠습니다. 이름, 나이, 반려견 목록, 성별 등의 속성과 각 필드의 타입 및 제약 조건이 정의되어 있습니다.

schema = '''{
    "title": "Example Schema",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        },
        "dogs": {
            "type": "array",
            "items": {"type": "string"},
            "maxItems": 4
        },
        "gender": {
            "type": "string",
            "enum": ["male", "female"]
        },
        "deceased": {
            "enum": ["yes", "no", 1, 0, "true", "false"]
        }
    },
    "required": ["firstName", "lastName"]
} '''

이 스키마의 주요 특징은 다음과 같습니다.

firstName, lastName: 필수(required) 문자열 필드입니다.
age: 0 이상의 정수만 허용됩니다.
dogs: 최대 4개 항목을 가질 수 있는 문자열 배열입니다.
gender: "male" 또는 "female" 값만 허용됩니다.

2. 스키마 객체를 클래스로 변환

스키마가 준비되었다면 ObjectBuilder를 사용해 클래스를 생성할 수 있습니다. 빌더가 스키마를 분석하여 자동으로 클래스 네임스페이스를 만들어 줍니다.

import python_jsonschema_objects as pjs

# 스키마로 객체 빌더 생성
builder = pjs.ObjectBuilder(schema)

# 클래스 빌드
ns = builder.build_classes()

# 스키마 제목(Example Schema)에 해당하는 클래스 가져오기
Person = ns.ExampleSchema

# 인스턴스 생성
jack = Person(firstName="Jack", lastName="Sparrow")

# 속성 확인
jack.lastName
# 출력: example_schema lastName=Sparrow age=None firstName=Jack

생성된 Person 클래스는 일반 파이썬 클래스처럼 키워드 인자를 통해 인스턴스화할 수 있으며, 정의하지 않은 선택적 필드(예: age)는 None으로 초기화됩니다.

3. 자동 유효성 검증(Validation)

이 방식의 가장 큰 장점은 스키마에 정의된 제약 조건이 객체에 자동으로 적용된다는 점입니다. 예를 들어 나이에 음수를 할당하려 하면 즉시 검증 오류가 발생합니다.

jack.age = -2
# python_jsonschema_objects.validators.ValidationError:
# -2 was less or equal to than 0

스키마에서 age의 최솟값을 0으로 지정했기 때문에, -2라는 값은 유효하지 않다고 판단되어 ValidationError가 발생합니다. 덕분에 런타임에 잘못된 데이터가 들어오는 것을 사전에 차단할 수 있습니다.

정리

python-jsonschema-objects를 활용하면 다음과 같은 이점을 얻을 수 있습니다.

JSON 스키마만으로 클래스를 자동 생성하므로 보일러플레이트 코드가 크게 줄어듭니다.
타입, 최솟값/최댓값, enum, 배열 크기 등 스키마 제약 조건이 객체 수준에서 강제됩니다.
API 응답이나 설정 파일처럼 구조가 정해진 JSON 데이터를 안전하게 다룰 수 있습니다.

JSON 스키마를 이미 관리하고 있는 프로젝트라면, 이 라이브러리를 통해 데이터 검증 로직과 객체 모델을 한 번에 해결할 수 있습니다.