Naming Conventions

Clear, consistent naming is essential for maintainable templates. Your templateKey and fieldKey values appear directly in API requests, making them part of your public interface.

Why Naming Matters

Consider these two API requests:

// Unclear naming - what does this do?
{
  "templateKey": "slide-1",
  "content": {
    "f1": "John Smith",
    "f2": "CEO",
    "f3": "https://example.com/photo.jpg"
  }
}

// Clear naming - self-documenting
{
  "templateKey": "employee-profile",
  "content": {
    "employee_name": "John Smith",
    "job_title": "CEO",
    "profile_photo": "https://example.com/photo.jpg"
  }
}

The second example is immediately understandable without documentation.

Template Key Guidelines

Template keys should describe the slide's purpose or content type:

Good	Bad
`title-slide`	`slide-1`
`product-comparison`	`template-a`
`quarterly-report-header`	`header`
`team-member-card`	`card`
`data-chart-fullwidth`	`chart`

Field keys should describe what content they hold:

Good	Bad
`product_name`	`text1`
`price_amount`	`value`
`hero_image`	`img`
`feature_description`	`desc`
`cta_button_text`	`button`

Naming Anti-Patterns

Avoid Generic Names

Bad:  text, image, box, container, wrapper
Good: headline, product_photo, price_card, features_grid

Avoid Positional Names

Bad:  left_text, right_image, top_title, bottom_footer
Good: product_description, product_thumbnail, section_header, copyright_notice

Position may change during redesign; content purpose stays the same.

Avoid Type-Based Names

Bad:  text_field, image_field, group_container
Good: company_name, team_photo, product_specs

The field type is already defined in the template; the key should describe content.

Avoid Numbered Suffixes

Bad:  feature_1, feature_2, feature_3
Good: Use a List field with items containing feature_title, feature_description

If you need numbered items, that's a sign you should use a List.

Real-World Examples

Employee Directory Template

Template Key: employee-card

Fields:
├── employee_name        (Text)
├── job_title            (Text)
├── department           (Text)
├── profile_photo        (Image)
├── contact_info         (Group)
│   ├── email_address    (Text)
│   └── phone_number     (Text)
└── skills_list          (List)
    └── skill_name       (Text)

Product Catalog Template

Template Key: product-showcase

Fields:
├── product_name         (Text)
├── product_tagline      (Text)
├── hero_image           (Image)
├── price_display        (Text)
├── specifications       (Group)
│   ├── spec_label       (Text)
│   └── spec_value       (Text)
└── feature_highlights   (List)
    ├── feature_icon     (Image)
    └── feature_text     (Text)

Financial Report Template

Template Key: quarterly-report

Fields:
├── report_title         (Text)
├── report_period        (Text)
├── revenue_chart        (Chart)
├── key_metrics          (Group)
│   ├── metric_label     (Text)
│   └── metric_value     (Text)
└── executive_summary    (Text)

Naming Conventions

On this page