JsonSchema에 관해서 알아보자.

JsonSchema에 관해서 알아보자.

안녕하세요!

요즘은 Frontend에서 오는 Request이든 다른 3rd Party Provider에서 받아오는 Response이든 대부분

JSON 형식을 사용하고 있습니다. 이러한 Request 혹은 Response들은 사실상 큰 이변이 없다면,

일정한 파라미터와 값을 줄 것입니다. 하지만 현업에서는 이렇게 가볍게 보이는 것들 조차 정확한 파라미터와 값을 주는지

확인(검증) 할 필요가 있습니다.

오늘은 이를 확인할 때 도움이 되는 JsonSchema에 관해서 알아보도록 하겠습니다.

 

1. JsonSchema란?
2. 사용방법?
3. 마치며.

 

1. JsonSchema란?

JsonSchema란 검증 하고자 하는 Json의 값을 Schema (스키마)로 나타낸 것입니다.

이를 이용한다면 크게 3가지의 장점이 있습니다.

1. 검증하고자 하는 Json의 구조가 정확한지.
2. 검증하고자 하는 Json이 Schema와 일치하는 타입의 값을 가지고 있는지.
3. 검증하고자 하는 Json이 필수로 요구하는 값을 포함하고 있는지.

자 그럼 짧게 사용방법을 알아보겠습니다.

 

2. 사용방법?

JsonSchema는 일반 Json의 구조를 띄고 있습니다.

그리고 각자의 type, properties 그리고 required를 설정하게 되는 게 가장 기본적인 구조입니다.

 

type:  Json 혹은 Properties의 타입을 지정합니다. 타입은 기본적으로 object, number, string, array 등이 존재합니다.

required: 어떠한 Properties들이 필수적으로 포함되어야 하는지 나타냅니다. 기본적으로 array의 형태를 띱니다.

properties: Json이 포함하는 Key를 나타냅니다.

 

먼저 예시를 보기 전에 모듈 한 가지를 추천드리고 싶습니다. 그건 바로 ajv라는 패키지입니다.

이를 이용하여 보다 쉽게 JsonSchema를 이용하여 Json을 검증할 수 있습니다.

후에 시간이 된다면 따로 ajv라는 패키지에 관해서 설명하는 글을 올려보도록 하겠습니다.

자 그럼 이번에는 예시를 보겠습니다.

 

// ajv 패키지
import { JSONSchemaType } from 'ajv';

/** Type of person */
type PersonType = {
  name: string;
  age: number;
  email: string;
  isStudent: boolean;
};

/** 값 */
const person: PersonType = {
  name: 'Mike',
  age: 20,
  email: 'miketest@test.com',
  isStudent: false,
};


/** Schema for json */
const personValidationSchema: JSONSchemaType<PersonType> = {
  type: 'object',
  required: ['name', 'age', 'email', 'isStudent'],
  properties: {
    name: {
      type: 'string',
      minLength: 1,
    },
    age: {
      type: 'number',
    },
    email: {
      type: 'string',
      minLength: 1,
    },
    isStudent: {
      type: 'boolean',
    },
  },
};

자 천천히 살펴보겠습니다.

type은 아까 설명드렸듯이 Json이 포함하는 properties들의 타입을 설정한다고 말씀드렸습니다.

제일 처음에 있는 type: 'object'는 Json자체가 object라는 것을 나타냅니다.

그다음 각자의 type들은 위의 PersonType와 일치하게 각자의 properties에 맞는 타입이 설정되었습니다.

 

그다음은 required를 알아보겠습니다.

이는 기본적으로 array의 형태를 하고 있으며 항상 string으로 필수적은 properties를 작성하셔야 합니다.

 

그리고 properties입니다.

이는 앞서 PersonType에 존재하는 name, age, email 그리고 isStudent를 포함합니다.

그리 곡 각자의 properties들은 다시 타입 혹은 minLength를 포함하게 됩니다.

여기서 minLength는 말 그대로 적어도 값이 하나 이상의 char를 가지고 있어야 된다는 것입니다.

만약 아무 값이 없는 "" 이러한 string을 값으로 받게 되면 곧바로 검증되지 않는 값이라고 뜨게 됩니다.

 

자 모든 값들이 이렇게 쉽게 string, number만 존재한다면 좋겠지만,

우리는 개발할 때 array 혹은 enum 또한 사용하게 됩니다.

이에 관한 간단한 예시를 보겠습니다.

 

/** Enum */
enum DeviceEnum {
  Desktop,
  Tablet,
  Mobile,
}

/** Type of test */
type TestType = {
  test1: string[];
  test2: DeviceEnum;
};

/** Json Value */
const value: TestType = {
  test1: ['test', 'something', 'value'],
  test2: DeviceEnum.Desktop,
};

/** Validation schema */
const validationSchema: JSONSchemaType<TestType> = {
  type: 'object',
  required: ['test1', 'test2'],
  properties: {
    test1: {
      type: 'array',
      items: {
        type: 'string',
        minLength: 1,
      },
      minItems: 1,
    },
    test2: {
      type: 'number',
      enum: [DeviceEnum.Desktop, DeviceEnum.Mobile, DeviceEnum.Tablet],
    },
  },
};

자 array를 사용한다면 test1과 같이 type은 'array'로 지정하실 수 있습니다.

그리고 이때 items를 이용하여 array안에 존재하는 값들이 어떠한 타입을 가지고 있는지 그리고 적어도 몇 개 이상의 char가 필요한지 나타냅니다.

그리고 minItems는 마찬가지로 적어도 몇 개의 값이 array안에 존재해야 하는지 나타냅니다.

이를 지정하지 않는다면 텅 빈 array 즉 [] 또한 문제없이 작동합니다.

 

Enum을 사용하는 경우는 그렇게 많지는 않지만 그렇다고 지나칠 수는 없는 부분입니다.

test2를 보시면 type이 'number'로 지정되었습니다. Enum은 따로 상응하는 값을 지정하지 않는다면 숫자로 인식됩니다.

그렇기에 enum에 Desktop, Tablet, Mobile이라고 적혀있어도 사실상 1,2 그리고 3으로 인식되는 것입니다.

혹시 type을 string으로 지정하고 싶으시다면 아래와 같이 Enum을 조금 바꿔주시면 됩니다.

enum DeviceEnum {
  Desktop= 'Desktop',
  Tablet= 'Tablet',
  Mobile= 'Mobile',
}

이렇게 바꿔주시면 type을 'string'으로 지정할 수 있습니다.

그리고 enum에 존재 가능한 값들을 지정해 줍니다.

 

3. 마치며.

자 오늘은 JsonSchema에 관해서 짧게 알아보았습니다.

사실 그냥 이렇게 선언만 해서는 사용할 수 없습니다!

앞서 언급한 ajv와 같은 패키지를 이용하시면 Json의 값과 Schema를 보다 쉽게 비교할 수 있습니다.

 

개발을 할 때 항상 올바른 값을 주고받는 것은 너무도 중요합니다.

또한 올바르지 않은 값을 서버가 받았을 때 이를 어떻게 처리하는지도 너무 중요합니다.

오늘은 JsonSchema를 통해서 가볍게 Schema를 어떻게 작성하는지 알아보았지만,

다음에는 ajv를 통해서 어떻게 실제로 json의 값을 검증하는지 알아보겠습니다.

 

완벽한 준비란 없다, 완벽한 준비란 영원히 시작하지 않는 것과 같다.

Es gibt keine perfekte Vorbereitung.

Perfekte Vorbereitung ist das Gleiche, wie nie anzufangen.