객체에 선언할 수 있는 모든 필드 타입 — 저장하는 값, 허용하는 옵션, 그리고 REST, Console, AI Builder에 노출되는 방식.

필드 타입

패밀리별로 분류된 48가지 기본 제공 필드 타입. 전체 Zod 스키마는 packages/spec/src/data/field.zod.ts에 있으며, 이 페이지는 실용적인 요약입니다.

핵심 속성 (모든 필드)

속성	타입	기본값	용도
`name`	string (snake_case)	—	머신 식별자 — REST 경로 세그먼트, SQL 컬럼
`label`	string	—	Console에 표시되는 라벨
`type`	FieldType	—	아래 타입 표 참조
`required`	boolean	`false`	NOT NULL 제약
`unique`	boolean	`false`	고유 인덱스
`searchable`	boolean	`false`	`/api/v1/search`용 인덱싱
`multiple`	boolean	`false`	값의 배열로 저장
`defaultValue`	unknown	—	초기값 (리터럴 또는 CEL)
`columnName`	string	= `name`	물리적 DB 컬럼 재정의
`hidden`	boolean	`false`	기본 Console 뷰에서 숨김
`readonly`	boolean	`false`	폼에서 비활성화
`system`	boolean	`false`	자동 주입됨 (id, created_at, …)
`index`	boolean	`false`	DB 인덱스 생성
`externalId`	boolean	`false`	외부 키를 통한 upsert 대상
`inlineHelpText`	string	—	툴팁 / 도움말 텍스트
`conditionalRequired`	`P` 술어	—	CEL이 true일 때 필수
`trackHistory`	boolean	`false`	값 변경을 레코드 활동 타임라인에 사람이 읽을 수 있는 항목으로 렌더링 (ADR-0052)

텍스트 패밀리

타입	용도	주요 옵션
`text`	짧은 문자열	`maxLength`, `minLength`
`textarea`	여러 줄	`maxLength`
`email`	이메일	형식 검증됨, 소문자로 변환
`url`	URL	형식 검증됨
`phone`	전화번호	E.164
`password`	단방향 시크릿	인증 서브시스템이 해시 처리함, GET으로 반환되지 않음
`secret`	가역 시크릿 (API 키, 토큰, DB 비밀번호)	크립토 제공자를 통해 저장 시 암호화되고, 불투명 참조로 저장되며, 읽기 시 마스킹됨. fail-closed — 제공자가 구성되지 않으면 쓰기가 평문을 저장하는 대신 예외를 던짐
`markdown`	마크다운 본문	Console 미리보기에서 렌더링
`html`	새니타이즈된 HTML	쓰기 시 DOMPurify 적용
`richtext`	WYSIWYG	Console 에디터 + 직렬화된 JSON

숫자

타입	용도	주요 옵션
`number`	부동소수점	`min`, `max`, `precision`, `scale`
`currency`	금액	`currencyConfig: { precision, currencyMode: 'fixed' \| 'dynamic', defaultCurrency }`
`percent`	0–100 %	`min`, `max`, `scale`

integer와 decimal은 별도의 타입이 아닙니다 — 정수에는 scale: 0을 사용한 number를, 고정 소수에는 precision+scale을 사용한 number를 쓰세요.

날짜 / 시간

타입	저장 내용	비고
`date`	달력 날짜	시간대 없음
`datetime`	시점	UTC
`time`	벽시계 시각	날짜 없음

논리

타입	비고
`boolean`	체크박스
`toggle`	boolean과 동일, 스위치 UI

선택

타입	비고
`select`	단일 선택 — 옵션을 인라인으로 선언하거나 피크리스트에서 참조
`multiselect`	다중 선택, 배열로 저장
`radio`	라디오 렌더링을 사용하는 `select`의 UI 별칭
`checkboxes`	체크박스 렌더링을 사용하는 `multiselect`의 UI 별칭

옵션 형태:

options: [
  { value: 'low',    label: 'Low' },
  { value: 'high',   label: 'High',   color: '#e02' },
  { value: 'urgent', label: 'Urgent', color: '#c00' }
]

관계

타입	카디널리티	의미
`lookup`	다대일	느슨한 참조, 부모를 삭제해도 기본적으로 자식은 삭제되지 않음
`master_detail`	다대일, 캐스케이딩	부모 없이는 자식이 존재할 수 없음, 권한은 부모로부터 상속
`tree`	자기 참조	계층 구조 (동일 객체의 parent_id)

공통 옵션:

{
  type: 'lookup',
  reference: 'account',                       // target object name
  referenceFilters: ['status:active'],        // narrow the lookup picker
  deleteBehavior: 'set_null'                  // 'set_null' | 'cascade' | 'restrict'
}

계산형

타입	동작	주요 옵션
`formula`	파생 값, 읽기 또는 재계산 시 평가됨	`expression: F\`record.qty * record.unit_price`` — CEL 참조
`summary`	자식 관계에 대한 롤업	`summaryOperations: { object, field, function }` (`count` \| `sum` \| `avg` \| `min` \| `max`)
`autonumber`	자동 증가 표시 번호	`format` (예: `TKT-{0000}`), `startAt`

수식 예시:

{
  name: 'profit_margin',
  type: 'formula',
  expression: F`(record.revenue - record.cost) / record.revenue * 100`
}

미디어

타입	용도	주요 옵션
`image`	이미지 첨부	`fileAttachmentConfig` (아래 참조)
`file`	모든 파일	동일
`avatar`	프로필 사진	정사각형 크롭, 합리적인 기본값
`video`	비디오 업로드	재생 시간 + 썸네일 캡처
`audio`	오디오	파형 미리보기

fileAttachmentConfig: {
  maxSize: 10_000_000,                        // bytes
  allowedTypes: ['image/png','image/jpeg'],
  virusScan: true,
  storageProvider: 's3',                       // see Configure → Storage
  imageValidation: { minWidth: 200, maxWidth: 4096, generateThumbnails: ['sm','md','lg'] }
}

구조형

타입	저장 내용	비고
`json`	임의의 JSON	Postgres에서 JSONB로 저장
`composite`	명명된 필드를 가진 하위 레코드	인라인 구조체, 별도 테이블이 아님
`repeater`	composite 값의 배열	자식 객체 없는 일대다

향상된 UI

타입	비고
`location`	위도/경도 + 정확도
`address`	도로명 / 시 / 지역 / 우편번호 / 국가
`code`	소스 코드 필드 — `language`, `theme`, `lineNumbers`
`color`	`colorFormat: 'hex' \| 'rgb' \| 'rgba' \| 'hsl'`, `presetColors[]`
`rating`	1–N 별점 — `max`, `icon`
`slider`	슬라이더 UI를 갖춘 범위 제한 숫자
`signature`	그려진 서명, 이미지로 저장
`qrcode`	값을 QR 또는 바코드(EAN / UPC / Code128)로 렌더링
`progress`	막대로 렌더링되는 파생 백분율
`tags`	자동 완성이 있는 자유 형식 태그 배열
`vector`	임베딩 컬럼 — `vectorConfig: { dimensions, distanceMetric: 'cosine' \| 'euclidean', indexed, indexType: 'hnsw' \| 'ivfflat' }`

시스템 필드 (모든 객체에 자동 주입됨)

필드	타입	비고
`id`	text (ULID)	기본 키
`created_at`	datetime	UTC 삽입 시각
`updated_at`	datetime	UTC 마지막 쓰기 시각
`created_by`	lookup → `user`	삽입한 사람
`updated_by`	lookup → `user`	마지막으로 쓴 사람
`version`	integer	낙관적 동시성 토큰

이 필드들은 직접 선언하지 않습니다 — 객체별로 ObjectSpec.systemFields: false로 옵트아웃할 수 있습니다 (대개 좋은 생각은 아닙니다).

필드가 스택을 통해 흐르는 방식

*.object.ts (field spec)
   │
   ├─► Postgres / MySQL / SQLite column + index + constraint
   ├─► REST: validated on POST/PATCH, exposed on GET
   ├─► Console: form widget + list column
   ├─► AI Builder: tool argument schema (so the AI knows what to ask)
   └─► Audit: change-tracked if `trackHistory: true`

함께 보기

Build → 데이터 모델 — 필드를 객체로 구성하기
CEL — expression, conditionalRequired, 검증
ObjectQL — 이 필드들을 쿼리하기
REST API — 이를 생성/소비하는 엔드포인트
@objectstack/spec/data/field.zod.ts — 권위 있는 스키마

필드 타입

On this page