필드 유형 레퍼런스 | EmDash CMS Everything

EmDash는 콘텐츠 스키마를 정의하기 위한 17가지 필드 유형을 지원합니다. 각 유형은 SQLite 열 유형에 매핑되며 적절한 관리 UI를 제공합니다.

개요

다음 표는 모든 필드 유형과 SQLite 열을 나열합니다.

Type	SQLite Column	Description
`string`	TEXT	짧은 텍스트 입력
`text`	TEXT	여러 줄 텍스트
`url`	TEXT	URL 값
`number`	REAL	소수
`integer`	INTEGER	정수
`boolean`	INTEGER	참/거짓
`datetime`	TEXT	날짜와 시간
`select`	TEXT	옵션 중 단일 선택
`multiSelect`	JSON	다중 선택
`portableText`	JSON	리치 텍스트 콘텐츠
`image`	TEXT	이미지 참조
`file`	TEXT	파일 참조
`reference`	none	다른 컬렉션의 항목에 연결
`json`	JSON	임의의 JSON 데이터
`slug`	TEXT	URL-안전 식별자
`repeater`	JSON	반복 필드 그룹
`blocks`	JSON	타입이 지정된 페이지 구성

텍스트 유형

`string`

짧은 한 줄 텍스트. 제목, 이름, 짧은 값에 사용합니다.

{
  slug: "title",
  label: "Title",
  type: "string",
  required: true,
  validation: {
    minLength: 1,
    maxLength: 200,
  },
}

검증 옵션:

minLength — 최소 문자 수
maxLength — 최대 문자 수
pattern — 값이 일치해야 하는 정규식

편집기는 입력을 maxLength로 제한하고 길이 규칙에 대한 실시간 문자 수를 표시합니다.

위젯 옵션:

특정 옵션 없음

`text`

여러 줄 일반 텍스트. 설명, 발췌문, 더 긴 일반 텍스트에 사용합니다.

{
  slug: "excerpt",
  label: "Excerpt",
  type: "text",
  options: {
    rows: 3,
  },
}

검증 옵션:

minLength — 최소 문자 수
maxLength — 최대 문자 수
pattern — 값이 일치해야 하는 정규식

편집기는 입력을 maxLength로 제한하고 길이 규칙에 대한 실시간 문자 수를 표시합니다.

위젯 옵션:

rows — textarea의 행 수(기본값: 3)

`url`

웹 주소. 콘텐츠 API는 유효한 URL이 아닌 값을 거부합니다.

{
  slug: "website",
  label: "Website",
  type: "url",
  required: true,
}

URL 필드는 텍스트로 저장됩니다. 값이 /about 같은 상대 경로일 수 있으면 대신 string 필드를 사용하세요. 상대 경로는 url 필드의 유효한 값이 아닙니다.

`slug`

슬러그 같은 값을 담기 위한 텍스트. 이 사용자 정의 필드 유형은 값을 생성하거나 정리하지 않습니다.

{
  slug: "legacy_slug",
  label: "Legacy Slug",
  type: "slug",
  required: true,
  unique: true,
}

모든 콘텐츠 항목에는 공개 URL용으로 EmDash가 별도로 관리하는 예약된 시스템 slug가 이미 있습니다. 콘텐츠 모델에 다른 저장된 슬러그 같은 값이 필요할 때만 사용자 정의 slug 필드를 사용하세요.

숫자 유형

`number`

소수. 가격, 평점, 측정값에 사용합니다.

{
  slug: "price",
  label: "Price",
  type: "number",
  required: true,
  validation: {
    min: 0,
    max: 999999.99,
  },
}

검증 옵션:

min — 최솟값
max — 최댓값

편집기는 숫자 입력에 min과 max를 설정하고 그 아래에 허용 범위를 표시합니다.

SQLite REAL(64비트 부동소수점)로 저장됩니다.

`integer`

정수. 수량, 카운트, 순서 값에 사용합니다.

{
  slug: "quantity",
  label: "Quantity",
  type: "integer",
  defaultValue: 1,
  validation: {
    min: 0,
    max: 1000,
  },
}

검증 옵션:

min — 최솟값
max — 최댓값

편집기는 숫자 입력에 min과 max를 설정하고 그 아래에 허용 범위를 표시합니다.

SQLite INTEGER로 저장됩니다.

`boolean`

참 또는 거짓. 토글과 플래그에 사용합니다.

{
  slug: "featured",
  label: "Featured",
  type: "boolean",
  defaultValue: false,
}

SQLite INTEGER(0 또는 1)로 저장됩니다.

날짜와 시간

`datetime`

시간의 한 순간. API, MCP, CLI 쓰기는 Z 또는 명시적 UTC 오프셋을 포함해야 합니다. 관리는 Settings → General에서 구성한 시간대로 날짜-시간 선택기를 해석합니다.

{
  slug: "publishedAt",
  label: "Published At",
  type: "datetime",
}

저장 형식: 2025-01-24T12:00:00.000Z

EmDash는 수락한 입력을 저장하기 전에 세 자리 밀리초가 있는 UTC로 변환합니다. 예를 들어 2025-01-24T21:00:00+09:00은 2025-01-24T12:00:00.000Z로 저장됩니다. 값이 순간이 아니라 달력 날짜나 로컬 벽시계 시간일 때는 대신 string 필드를 사용하세요.

선택 유형

`select`

미리 정의된 옵션에서 단일 선택.

{
  slug: "status",
  label: "Status",
  type: "select",
  required: true,
  defaultValue: "draft",
  validation: {
    options: ["draft", "published", "archived"],
  },
}

검증 옵션:

options — 허용된 값의 선택적 배열. 미리 정의된 선택지를 제시하고 다른 문자열을 거부하려면 제공하세요. 없으면 검증은 모든 문자열을 허용합니다.

선택된 값을 담은 TEXT로 저장됩니다.

`multiSelect`

미리 정의된 옵션에서 다중 선택.

{
  slug: "tags",
  label: "Tags",
  type: "multiSelect",
  validation: {
    options: ["news", "tutorial", "review", "opinion"],
  },
}

검증 옵션:

options — 허용된 값의 선택적 배열. 미리 정의된 선택지를 제시하고 다른 문자열을 거부하려면 제공하세요. 없으면 검증은 모든 문자열 배열을 허용합니다.

JSON 배열로 저장: ["news", "tutorial"]

리치 콘텐츠

`portableText`

Portable Text 형식의 리치 텍스트 콘텐츠. 제목, 목록, 링크, 이미지, 사용자 정의 블록을 지원합니다.

{
  slug: "content",
  label: "Content",
  type: "portableText",
  required: true,
}

값은 Portable Text 블록의 JSON 배열로 저장됩니다. 예:

[
	{
		"_type": "block",
		"style": "normal",
		"children": [{ "_type": "span", "text": "Hello world" }]
	}
]

플러그인은 사용자 정의 블록 유형(임베드, 위젯 등)을 편집기에 추가할 수 있습니다. 슬래시 명령 메뉴에 표시됩니다. 공개 사이트에서 저장된 블록을 렌더링하려면 네이티브 플러그인 또는 컴패니언 패키지의 Astro 컴포넌트가 필요합니다. Portable Text 렌더링 컴포넌트를 참조하세요.

미디어 유형

`image`

업로드된 이미지에 대한 참조. 치수와 대체 텍스트 같은 메타데이터를 포함합니다.

{
  slug: "featuredImage",
  label: "Featured Image",
  type: "image",
  validation: {
    allowedMimeTypes: ["image/jpeg", "image/png"],
  },
  options: {
    darkVariant: true,
  },
}

위젯 옵션:

darkVariant — 어두운 색 구성표에 표시할 이미지용 두 번째 슬롯을 편집자에게 제공합니다(기본값: false). Dark Mode를 참조하세요.

검증 옵션:

allowedMimeTypes — 선택한 미디어에 대해 허용되는 정확한 MIME 유형의 비어 있지 않은 목록

값은 미디어 참조와 메타데이터를 가진 객체로 저장됩니다:

{
	"id": "01HXK5MZSN...",
	"src": "/_emdash/api/media/file/01HXK5MZSN...",
	"alt": "Description",
	"width": 1920,
	"height": 1080,
	"provider": "local",
	"meta": {
		"storageKey": "01HXK5MZSN....jpg"
	}
}

darkVariant가 활성화되면 값은 같은 형태로 darkVariant 아래에 어두운 대응물을 가질 수 있습니다:

{
	"id": "01HXK5MZSN...",
	"alt": "Architecture diagram",
	"width": 1920,
	"height": 1080,
	"darkVariant": {
		"id": "01HXK5N2QT...",
		"width": 1920,
		"height": 1080
	}
}

`file`

문서나 PDF 같은 업로드된 파일에 대한 참조.

{
  slug: "document",
  label: "Document",
  type: "file",
  validation: {
    allowedMimeTypes: ["application/pdf"],
  },
}

검증 옵션:

allowedMimeTypes — 선택한 미디어에 대해 허용되는 정확한 MIME 유형의 비어 있지 않은 목록

값은 캐시된 메타데이터가 있는 프로바이더 참조로 저장됩니다:

{
	"id": "01HXK5MZSN...",
	"provider": "local",
	"filename": "report.pdf",
	"mimeType": "application/pdf",
	"meta": {
		"storageKey": "01HXK5MZSN....pdf"
	}
}

url과 size는 다른 캐시된 메타데이터 필드처럼 선택 사항입니다. 콘텐츠 쿼리는 지속된 값을 그대로 반환하며 미디어 라이브러리에서 하이드레이트하지 않습니다. 최신 메타데이터나 프로바이더별 URL이 필요할 때 정규 조회 API는 파일 값과 현재 메타데이터를 참조하세요.

관계형 유형

`reference`

항목을 다른 컬렉션의 항목에 연결하며 관리에서는 항목 선택기로 렌더링됩니다. 그 링크는 관계에 속합니다. 관계는 두 컬렉션을 조인하고 각 쪽에 이름을 붙이며 각 쪽이 연결할 수 있는 항목 수를 제한하는 스키마 객체입니다. Relations는 편집자 및 관리 워크플로를 다룹니다.

다음 필드는 게시물을 authors 컬렉션의 한 항목에 연결합니다:

{
  slug: "author",
  label: "Author",
  type: "reference",
  required: true,
  validation: {
    targetCollection: "authors",
    multiple: false,
  },
}

검증:

targetCollection — 이 필드가 연결하는 컬렉션의 슬러그. 필드를 만들면 그에 대한 관계가 생성됩니다.
multiple — 둘 이상의 연결된 항목 허용(기본값: false). 제한이 그때 새 관계에 속하므로 targetCollection과 함께만 읽으세요.
relation — 새로 만드는 대신 바인딩할 기존 관계의 슬러그.
relationSide — 이 컬렉션이 relation의 어느 끝에 있는지, "parent" 또는 "child". 양 끝이 같은 컬렉션이고 양 끝이 일치하는 관계에만 설정하세요.

targetCollection 또는 relation 중 하나를 지정하세요. targetCollection에서 만든 필드는 {collection}_{field}라는 관계의 부모 끝이 되며, 자식 쪽은 필드의 레이블을 취하고 multiple이 설정되지 않으면 한 항목을 보유합니다. relation에서 만든 필드는 해당 컬렉션이 있는 끝에서 그 관계를 보며, 다른 끝의 컬렉션이 필드의 대상입니다. 한 관계는 끝당 하나의 필드만 허용하므로 같은 끝에 대한 두 번째 필드는 거부됩니다. 두 형태 모두 생성된 필드에 relation, relationSide, targetCollection을 저장하며, 대상 컬렉션은 이후 고정됩니다. 변경하려면 필드를 삭제하고 새 필드를 추가하세요. 필드의 이름 변경은 그것이 보는 관계의 쪽 이름도 바꿉니다.

참조 필드는 컬렉션 테이블에 열을 추가하지 않습니다. 링크는 _emdash_content_references에 있으며 각 항목의 번역 그룹으로 키가 지정되므로, 선택은 로케일별이 아니라 항목의 번역 간에 공유됩니다. 콘텐츠 읽기는 연결된 항목을 data가 아니라 필드 슬러그로 키가 지정된 references 아래에 반환합니다. 템플릿에서는 이름으로 필드를 요청하세요 — 참조 필드 읽기를 참조하세요.

관계에 바인딩된 필드는 인덱싱할 열을 저장하지 않으므로 indexed를 설정할 수 없으며, 사이트 검색도 다루지 않습니다.

관계가 없는 필드

관계도 대상 컬렉션도 지정하지 않는 참조 필드는 TEXT 열을 유지하고 그 안에 항목 ID 하나를 담습니다:

"01HXK5MZSN..."

options.allowMultiple이 설정된 필드는 같은 열에 항목 ID의 JSON 배열을 담습니다:

["01HXK5MZSN...", "01HXK6NATS..."]

열은 다른 텍스트 열처럼 읽고 쓰며, 컬렉션 스키마는 값을 문자열로 검증하고, 필드는 indexed를 설정하고 콘텐츠 목록 필터로 작동할 수 있습니다. 선택기가 아니라 텍스트 상자로 렌더링됩니다.

선택기로 만들려면 Content Types에서 필드를 열고 참조 컬렉션을 선택하세요. EmDash는 관계를 만들고, 열의 항목 ID를 링크로 복사하며, 필드의 searchable과 indexed 플래그를 지우므로 콘텐츠 목록 필터와 사이트 검색이 더 이상 다루지 않습니다. 열은 그대로 남고 쓰기가 중단됩니다. Relations 는 편집자 쪽에서 같은 단계를 다룹니다.

이전 릴리스에서 업데이트된 사이트는 이 상태의 필드를 보유할 수 있습니다. 업데이트가 무엇을 바인딩하고 무엇이 직접 바인딩해야 하는지는 참조 필드가 관계에 바인딩됨 을 참조하세요.

유연한 유형

`json`

임의의 JSON 데이터. 복잡한 중첩 구조, 서드파티 통합, 고정 스키마가 없는 데이터에 사용합니다.

{
  slug: "metadata",
  label: "Metadata",
  type: "json",
}

SQLite JSON 열에 그대로 저장됩니다.

`repeater`

구조화된 행의 반복 목록. validation.subFields에 하나 이상의 하위 필드를 정의하세요. 편집자는 원시 JSON을 입력하지 않고 행을 추가, 제거, 재정렬, 편집할 수 있습니다.

다음 필드는 제품 사양 목록을 저장합니다:

{
  slug: "specifications",
  label: "Specifications",
  type: "repeater",
  validation: {
    minItems: 1,
    maxItems: 12,
    subFields: [
      { slug: "label", label: "Label", type: "string", required: true },
      { slug: "value", label: "Value", type: "text", required: true },
      { slug: "source", label: "Source", type: "url" },
    ],
  },
}

Repeater 값은 객체 배열로 저장됩니다:

[
	{
		"label": "Weight",
		"value": "1.2 kg",
		"source": "https://example.com/specifications"
	}
]

허용되는 하위 필드 유형은 string, text, url, number, integer, boolean, datetime, select, image입니다. Repeater는 다른 repeater나 portableText, reference, file 같은 복잡한 필드를 포함할 수 없습니다.

Repeater 검증은 다음 속성을 허용합니다:

subFields — 하나 이상의 하위 필드 정의. 각 정의에는 slug, label, type이 필요하며 required도 설정할 수 있습니다. select 하위 필드는 options로 선택지를 제공합니다.
minItems — 최소 행 수. 0 이상이어야 합니다.
maxItems — 최대 행 수. 1 이상이어야 하며 minItems보다 작을 수 없습니다.

`blocks`

타입이 지정된 콘텐츠 블록의 순서가 있는 목록. 각 블록 유형에는 자체 필드가 있으며 번호가 매겨진 버전을 유지합니다. 컬렉션 필드에 추가하기 전에 스키마 API, MCP 또는 시드 파일로 블록 유형을 정의하세요.

다음 필드는 편집자가 히어로와 콜투액션 블록으로 페이지를 구성할 수 있게 합니다:

{
  slug: "layout",
  label: "Layout",
  type: "blocks",
  validation: {
    allowedTypes: ["hero", "call_to_action"],
    maxItems: 20,
  },
}

저장된 모든 블록은 해당 버전이 선언한 필드와 함께 유형, 버전, 안정적인 키를 가집니다:

[
	{
		"_type": "hero",
		"_version": 1,
		"_key": "01K5AB3F7M9QZ2X8W4V6T1R0YH",
		"heading": "Bread made slowly, by hand."
	}
]

Blocks 검증은 다음 속성을 허용합니다:

allowedTypes — 새 블록에 사용 가능한 순서 있는 블록 유형 슬러그.
retiredTypes — 저장된 콘텐츠용으로 유지되지만 새 블록에는 사용할 수 없는 서버 관리 블록 유형.
minItems — 최소 블록 수. 데이터가 있는 컬렉션에서 0보다 크게 올리면 콘텐츠 마이그레이션이 필요합니다.
maxItems — 최대 블록 수(최대 100).

blocks 필드는 선택 사항이며 기본값은 빈 배열입니다. required, unique, searchable, indexed일 수 없으며 사용자 정의 필드 위젯으로 렌더링할 수 없습니다. 블록 정의는 스칼라, 텍스트, 선택, Portable Text, 이미지, 파일, repeater 필드를 사용할 수 있습니다. 참조, JSON, 슬러그, 중첩 blocks는 포함할 수 없습니다.

저장된 배열은 emdash/ui의 <Blocks value components fallback>으로 렌더링하세요. 시드, 컴포넌트 맵, 누락 렌더러, 활성화, 마이그레이션 예는 blocks로 페이지 만들기를 참조하세요.

필드 속성

모든 필드는 다음 공통 속성을 지원합니다:

Property	Type	Description
`slug`	`string`	고유 식별자(필수)
`label`	`string`	표시 이름(필수)
`type`	`FieldType`	필드 유형(필수)
`required`	`boolean`	값 필수(기본값: false)
`unique`	`boolean`	고유성 강제(기본값: false)
`searchable`	`boolean`	전체 텍스트 검색에 필드 포함(기본값: false)
`indexed`	`boolean`	인덱싱된 정렬/필터 활성화
`translatable`	`boolean`	로케일별 값 저장(기본값: true)
`defaultValue`	`unknown`	새 항목의 기본값
`validation`	`object`	유형별 검증 규칙
`widget`	`string`	사용자 정의 위젯 재정의
`options`	`object`	위젯 구성
`sortOrder`	`number`	관리에서의 표시 순서

indexed는 스칼라 필드에서 사용할 수 있습니다: string, url, number, integer, boolean, datetime, select, reference, slug. 인덱싱된 필드는 콘텐츠 목록 쿼리에서 orderBy 필드로 전달하거나 fieldFilters에 사용할 수 있습니다. 정렬이나 필터에 사용하지 않는 필드를 인덱싱하지 마세요. 인덱스마다 저장과 쓰기 오버헤드가 늘어납니다.

searchable은 필드의 텍스트를 컬렉션의 전체 텍스트 검색 인덱스에 추가합니다. 식별자, 가격, 플래그 등 항목의 모든 번역에서 같아야 하는 값에는 translatable: false를 설정하세요. 한 로케일이 번역 불가 필드를 변경하면 EmDash는 그 값을 번역된 항목에 동기화합니다.

blocks 유형은 이 공통 집합에서 slug, label, type, translatable, validation, sortOrder만 사용합니다. 그 배열은 열 필수로 요구되지 않으며 항상 기본값이 []입니다.

예약된 필드 슬러그

다음 슬러그는 예약되어 사용할 수 없습니다:

id
slug
status
author_id
primary_byline_id
created_at
updated_at
published_at
scheduled_at
deleted_at
version
live_revision_id
draft_revision_id
terms
bylines
byline

TypeScript 유형

프로그래밍 방식 사용을 위해 필드 유형 정의를 가져오세요:

import type { FieldType, Field, CreateFieldInput } from "emdash";

const fieldTypes: FieldType[] = [
	"string",
	"text",
	"url",
	"number",
	"integer",
	"boolean",
	"datetime",
	"select",
	"multiSelect",
	"portableText",
	"image",
	"file",
	"reference",
	"json",
	"slug",
	"repeater",
	"blocks",
];