# cms-edit — Taxonomy Field Reference

Taxonomy entries (`tagType`, `articleType`, `tag`) can be created as **drafts** with the CLI. Use `--json-file` for full field control, or `--slug` / `--name` for minimal creates.

```bash
cms-edit create tag-type --slug conference-venue --name "Conference Venue"
cms-edit create article-type --slug resources/publications --name "Publications"
cms-edit create tag --slug poster-presentation --name "Poster Presentation" --tag-type presentation-type
cms-edit create tag --slug easl-congress-2026 --name "EASL Congress 2026" --tag-type publication-source \
  --description "Research presented at EASL Congress 2026." --featured-image <logoAssetId>

# Idempotent import helpers
cms-edit create tag-type --slug conference-venue --name "Conference Venue" --if-not-exists
cms-edit resolve --tag-type-slug presentation-type
```

All creates are draft-only. See `cms-edit help taxonomy-from-json` for batch bootstrap.

---

## tagType fields

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | Text | Yes | Display name |
| `slug` | Text | No | URL slug without leading or trailing slash. Example: `part1/part2`. Optional. |
| `show` | Boolean | No | Whether tags of this type show visually on cards/detail |
| `template` | Link (Entry) | No | Template for tag detail pages |
| `topContent` | Array of Links | No | Content above main area on tag detail |
| `menu` | Link (Entry) | No | Navigation entry |
| `footer` | Link (Entry) | No | Footer navigation entry |
| `indexPageTemplate` | Link (Entry) | No | Template for tag-type index page |
| `indexPageTopContent` | Array of Links | No | Top content on tag-type index |

---

## articleType fields

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | Text | Yes | Display name |
| `cmsLabel` | Text | Yes | Label in Contentful entry list (defaults to `--name`) |
| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2/part3`. Use `index` for the home page. |
| `indexPageTitle` | Text | Yes | Title on article index page (defaults to `--name`) |
| `indexPageDescription` | Text | Yes | Description on article index (defaults to `""`) |
| `featuredImage` | Link (Asset) | No | Featured image for index/social |
| `menu` | Link (Entry) | No | Navigation entry |
| `footer` | Link (Entry) | No | Footer navigation entry |
| `indexPageTemplate` | Link (Entry) | No | Template for article index |
| `indexPageTopContent` | Array of Links | No | Top content on article index |
| `indexPageStructuredData` | Array of Links | No | Schema entries for index page |
| `visuals` | Array of Links | No | Media/externalVideo entries |
| `articleTemplate` | Link (Entry) | No | Template for article detail pages |
| `articlePageTopContent` | Array of Links | No | Top content on article detail |
| `structuredData` | Array of Links | No | Schema entries for article pages |
| `backgroundColour` | Symbol | No | Valid values: `cms-edit schema colours` |
| `textColour` | Symbol | No | Valid values: `cms-edit schema colours` |
| `indexed` | Boolean | Yes | Search indexing (default: `true`) |
| `hidden` | Boolean | Yes | Sitemap visibility (default: `false`) |
| `indexPageHidden` | Boolean | No | Hide article index page |
| `articlePageHidden` | Boolean | No | Hide article detail pages |
| `flags` | Array of Symbols | No | e.g. `"Sticky nav"` |
| `searchTemplate` | Link (Entry) | No | Template for search results |
| `searchTopContent` | Array of Links | No | Top content on search results |
| `breadcrumbTitle` | Text | No | Override for breadcrumb label |

---

## tag fields

| Field | Type | Required | Description |
|---|---|---|---|
| `cmsLabel` | Text | Yes | Label in Contentful (defaults to `--name`) |
| `name` | Text | Yes | Display name |
| `tagType` | Link (Entry) | Yes | Parent tagType entry |
| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2`. |
| `description` | Text | No | Short description |
| `featuredImage` | Link (Asset) | No | Featured image |
| `visuals` | Array of Links | No | Media/externalVideo entries |
| `menu` | Link (Entry) | No | Navigation entry |
| `footer` | Link (Entry) | No | Footer navigation entry |
| `template` | Link (Entry) | No | Template for tag detail |
| `topContent` | Array of Links | No | Top content on tag detail |
| `structuredData` | Array of Links | No | Schema entries |
| `backgroundColour` | Symbol | No | Valid values: `cms-edit schema colours` |
| `textColour` | Symbol | No | Valid values: `cms-edit schema colours` |
| `indexed` | Boolean | Yes | Search indexing (default: `true`) |
| `hidden` | Boolean | Yes | Sitemap visibility (default: `false`) |
| `show` | Boolean | No | Visual display on cards/detail |
| `breadcrumbTitle` | Text | No | Override for breadcrumb label |

Tags require `--tag-type <slug>` or `--tag-type-id <id>` (or `tagTypeSlug` / `tagTypeId` in JSON).

---

## JSON file shape

Use `--json-file` with any taxonomy create command. CLI flags override JSON values.

```jsonc
{
  "fields": {
    "name": "Poster Presentation",
    "slug": "poster-presentation",
    "description": "Poster session at ASCO 2025",
    "show": true,
    "indexed": true,
    "hidden": false,
    "backgroundColour": "White",
    "textColour": "Navy"
  },
  "tagTypeSlug": "presentation-type",
  "featuredImageId": "abc123",
  "templateId": "tmpl456",
  "topContentIds": ["comp1", "comp2"]
}
```

### Link shorthands

These top-level keys resolve to Contentful Entry/Asset links (same conventions as `create from-json`):

| Shorthand | Resolves to field |
|---|---|
| `tagTypeId`, `tagTypeSlug` | `tagType` (tags only) |
| `templateId` | `template` |
| `indexPageTemplateId` | `indexPageTemplate` |
| `articleTemplateId` | `articleTemplate` |
| `searchTemplateId` | `searchTemplate` |
| `menuId` | `menu` |
| `footerId` | `footer` |
| `featuredImageId` | `featuredImage` |
| `topContentIds` | `topContent` |
| `indexPageTopContentIds` | `indexPageTopContent` |
| `articlePageTopContentIds` | `articlePageTopContent` |
| `searchTopContentIds` | `searchTopContent` |
| `structuredDataIds` | `structuredData` |
| `indexPageStructuredDataIds` | `indexPageStructuredData` |
| `visualsIds` | `visuals` |

---

## Common options

| Option | Description |
|---|---|
| `--slug <slug>` | Required URL slug |
| `--name <name>` | Required display name |
| `--cms-label <label>` | CMS label (articleType/tag; defaults to name) |
| `--description <desc>` | Short description (tags only) |
| `--featured-image <asset-id>` | Asset ID for featured image (tags only) |
| `--json-file <path>` | Full field spec (see above) |
| `--if-not-exists` | Return existing entry ID when slug matches (exit 0) |
| `--dry-run` | Validate field build and link resolution without writing |

**Idempotency:** `--if-not-exists` checks Contentful then creates. They work for **sequential** import scripts. Do not run two creates for the same slug in parallel — both may succeed. Re-run with `--if-not-exists` to converge.

Use `CMS_EDIT_JSON=1` or `--json-output` for machine-readable output: `{ ok, id, slug, contentType, status: "created"|"existing"|"dry-run" }` (`id` is empty on dry-run).