이 페이지의 내용
문서기능 가이드
기능 가이드02

JSON 스키마 가이드

AUTO, DATA, ENTITY 모드로 서버 응답의 구조를 다룹니다.

한국어 문서약 9분

JSON 데이터를 처리하는 과정에서 구조 해석을 자동화하기 위한 스키마 변환 정책에 대해 설명합니다. 기본 모드는 AUTO이며, 대부분의 일반 데이터는 별도 설정 없이 자동으로 처리됩니다. 복잡하거나 구조 충돌이 우려되는 경우에만 DATA 또는 ENTITY 모드를 명시적으로 지정합니다.

엔티티 스키마#

엔티티란? MetaTable 또는 MetaView 로 데이터로 가져오거나, 내보낼때의 스키마 구조입니다.

ts
type DataType = string | number | boolean;

type SingleEntity = { 
	rows: Record<string, DataType> | Record<string, DataType>[],
	columns?: Record<string, ColumnType>
};
type MultiEntity = SingleEntity[];
  • ColumnType 타입은 문서를 하세요.

참조 : 컬럼 타입

명령(BindCommand) 객체의 outputOption 속성을 직접 설정할 수 있습니다.

js
const bm = new BindModel();

// 명령 추가
bm.addCommand('cmd1');
bm.addCommand('cmd2');
bm.addCommand('cmd3');

// outputOption 속성 설정
bm.command['cmd1'].outputOption = 'DATA';
bm.command['cmd2'].outputOption.schema = 'ENTITY';
bm.command['cmd3'].outputOption = { schema: 'AUTO', index: 1 };

// bm.cmd['cmd1'].outOpt === { option: 'SEND', index: 0, schema: 'DATA' }
// bm.cmd['cmd2'].outOpt === { option: 'SEND', index: 0, schema: 'ENTITY' }
// bm.cmd['cmd3'].outOpt === { option: 'SEND', index: 1, schema: 'AUTO' }
  • outOpt 속성은 outputOption 의 별칭입니다.

명령(BindCommand)을 추가할 때, 매개변수를 통해 설정할 수 있습니다.

js
const bm = new BindModel();

// 명령 추가
bm.addCommand('cmd1', 'DATA');
bm.addCommand('cmd2', 'ENTITY');
bm.addCommand('cmd3', { schema: 'AUTO', index: 1 });

// bm.cmd['cmd1'].outOpt === { option: 'SEND', index: 0, schema: 'DATA' }
// bm.cmd['cmd2'].outOpt === { option: 'SEND', index: 0, schema: 'ENTITY' }
// bm.cmd['cmd3'].outOpt === { option: 'SEND', index: 1, schema: 'AUTO' }

execute() 메서드를 호출할 때, 매개변수를 통해 설정할 수 있습니다.

js
const bm = new BindModel();

// 명령 추가
bm.addCommand('cmd1', 'VIEW');
bm.addCommand('cmd2', 'VIEW');
bm.addCommand('cmd3', 'VIEW');

bm.cmd['cmd1'].execute('cmd1', 'DATA');
bm.cmd['cmd2'].execute('cmd2', 'ENTITY');
bm.cmd['cmd3'].execute('cmd3', { schema: 'AUTO', index: 1 });

// bm.cmd['cmd1'].outOpt === { option: 'VIEW', index: 0, schema: 'DATA' }
// bm.cmd['cmd2'].outOpt === { option: 'VIEW', index: 0, schema: 'ENTITY' }
// bm.cmd['cmd3'].outOpt === { option: 'VIEW', index: 1, schema: 'AUTO' }

스키마 모드 요약#

모드 용도 특징
'AUTO' 기본값 데이터를 검사 후 변환
'DATA' 항상 { rows: [...] } 로 래핑 데이터(rows) 속성으로 강제 변환
'ENTITY' 엔티티 스키마 명시적 지정 배열은 복수의 엔티티로 변환

각 모드의 처리 방식#

AUTO 모드#

AUTO 모드는 대상 객체의 구조를 확인하여 자동으로 DATA 구조로 변환합니다. (기본값)

  • 대상이 객체일 경우: rows 속성이 없으면, 해당 객체를 rows 속성으로 래핑함
  • 대상이 배열일 경우: 배열을 빈 객체의 rows 속성에 할당함

단일 객체 데이터#

json
{ "aa": 10 }
json
// 변환 결과
{ "rows": { "aa": 10 } }

배열 객체 데이터#

json
[ 
	{ "aa": 10 }, 
	{ "aa": 20 } 
] 
json
// 변환 결과
{ "rows": [
		{ "aa": 10 }, 
		{ "aa": 20 } 
	]
}

엔티티 구조 데이터#

엔티티 스키마 구조를 갖는 객체는 기존 데이터를 유지합니다.

json
{ "rows": { "aa": 10 } }

DATA 모드#

DATA 모드는 대상 객체를 무조건 데이터(rows)로 변환하는 강제 변환 모드입니다.

  • 대상이 객체일 경우: 무조건 rows 속성으로 래핑함
  • 대상이 배열일 경우: 빈 객체에 rows 속성으로 등록함
    • 단, 배열의 요소가 객체가 아닐 경우 오류가 발생함

단일 객체 데이터#

AUTO 로 지정하여도 같은 같은 결과를 확인할 수 있습니다.

json
{ "aa": 10 }
json
// 변환 결과
{ "rows": { "aa": 10 } }

배열 객체 데이터#

AUTO 로 지정하여도 같은 같은 결과를 확인할 수 있습니다.

json
[ 
	{ "aa": 10 }, 
	{ "aa": 20 } 
] 
json
// 변환 결과
{ "rows": [
		{ "aa": 10 }, 
		{ "aa": 20 } 
	]
}

'rows', 'columns' 속성명을 사용할 때#

'rows', 'columns' 이름의 속성명을 사용하고 할때는 DATA 모드를 지정하면 강제로 rows 래핑하여 'rows', 'columns' 을 데이터로 이용할 수 있습니다.

json
{ "rows": 10, "columns": 20 }
json
// 변환 결과
{ "rows": { "rows": 10, "columns": 20 } }

ENTITY 모드#

ENTITY 모드는 대상 객체를 스키마로 해석하지 않고 독립된 엔티티로 유지합니다.

  • 대상이 객체일 경우: rows 속성이 없으면, 해당 객체를 rows 속성으로 래핑함
  • 대상이 배열일 경우:
    • 각 배열 요소에 rows 속성이 있으면 유지
    • rows 속성이 없을 경우, 해당 요소를 rows 속성으로 래핑함
    • 단, 배열의 요소가 객체가 아닐 경우 오류가 발생함

객체 데이터#

json
{ "aa": 10 }
json
// 변환 결과
{ "rows": { "aa": 10 } }

엔티티 구조 데이터#

엔티티 구조를 갖는 객체는 기존의 구조를 유지합니다.

json
{ "rows": { "aa": 10 } }

배열 객체 데이터#

ENTITY 모드에서 배열 객체 데이터는 독립된 엔티티로 변환합니다.

json
[ 
	{ "aa": 10 }, 
	{ "bb": 20 } 
] 
json
// 변환 결과
[ 
	{ "rows": { "aa": 10 } }, 
	{ "rows": { "bb": 20 } } 
] 

복수 배열 객체 데이터#

json
[ 
	{ "rows": { "aa": 10 } }, 
	{ "rows": { "bb": 20 } } 
] 

엔티티 배열 구조를 유지합니다.

Tip { "rows": { key: vlaue} } 는 { "rows": [ { key: vlaue} ]} 로 내부적으로 변환되므로, "rows" 속성값으로 객체 또는 배열로 표현할 수 있습니다.

스키마 변환표#

JSON 데이터에 따라 적합한 스카마 모드로 지정하여 엔티티로 변환 할 수 있습니다.

JSON 구분 AUTO DATA ENTITY
{ ... } 데이터 객체 확인 후 변환 강제 변환 확인 후 변환
{ rows: {...} } 엔티티 객체 유지 실패 유지
[ {...}, ...] 객체 요소 복수 데이터로 변환 복수 데이터로 변환 복수 엔티티로 변환
[ { rows: {...} }, ...] 엔티티 요소 실패 실패 유지
  • 입력된 데이터는 엔티티 데이터 형식 {rows: {...}}으로 변환되어야 합니다.
  • 엔티티 데이터를 'DATA' 모드로 지정하면, rows 속성으로 강제 래핑하여, 가져오기가 실패합니다.
  • 엔티티 배열 데이터는 'AUTO' 모드로 지정하면, rows 속성으로 래핑하여, 가져오기가 실패합니다.

데이터의 의미에 맞게 적합한 모드를 선택해서 엔티티로 스키타 타입으로 변환할 수 있 수 있습니다. 그 외의 데이터는 cbResult 콜백함수에서 데이터를 변환합니다.

참조 : 흐름 제어 > cbResult

모드를 쉽게 선택하기#

  1. 데이터가 복수 엔티티일 경우에 'entity' 모드 사용합니다.
  2. 데이터에 특수한 컬럼(rows, columns) 를 사용할 경우에 'data' 모드 사용합니다.
  3. 그 외 기본 'auto' 모드 사용합니다.

즉, 대부분의 기본값인 auto 모드로 사용하면 됩니다.

검색어를 입력해 보세요.