> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Schema Overview

> The structured data a case collects

A data schema defines what information the case tracks — organized into sections containing individual data points. Each data point has a type (Text, Number, Currency, Date, File, Multiple Choice, etc.) and visibility settings.

Cases created from templates inherit the template's data schema. Cases created from scratch start with a blank schema. You can modify a case's data schema at any time by adding, modifying, or removing fields and sections. Structure changes apply only to that individual case and do not affect the template.

<Info>
  Each data point has a unique key that can be referenced throughout the
  platform. Keys are explained conceptually here — for the technical notation
  and variable syntax, see the penscript documentation.
</Info>

## Field Types

Cases support 10 field types, each with specific configuration options and use cases. Click any field type below to see detailed configuration, examples, and best practices.

<CardGroup cols={2}>
  <Card title="Text" icon="text" href="/cases/data_schema/text">
    Single or multi-line text input for names, descriptions, and IDs
  </Card>

  <Card title="Number" icon="hashtag" href="/cases/data_schema/number">
    Numeric values for quantities, scores, and measurements
  </Card>

  <Card title="Currency" icon="coins" href="/cases/data_schema/currency">
    Monetary values with currency formatting for financial amounts
  </Card>

  <Card title="Date" icon="calendar" href="/cases/data_schema/date">
    Date picker for birth dates, deadlines, and timestamps
  </Card>

  <Card title="Checkbox" icon="square-check" href="/cases/data_schema/checkbox">
    Single yes/no option for agreements and consent flags
  </Card>

  <Card title="Multiple Choice" icon="list-check" href="/cases/data_schema/multiple_choice">
    Multiple selections for services, features, and categories
  </Card>

  <Card title="Choices" icon="circle-dot" href="/cases/data_schema/choices">
    Single selection for country, priority, and status
  </Card>

  <Card title="File" icon="file-arrow-up" href="/cases/data_schema/file">
    File upload for documents, images, and contracts
  </Card>

  <Card title="Signature" icon="pen-to-square" href="/cases/data_schema/signature">
    Digital signatures with authentication for legally binding agreements
  </Card>

  <Card title="API Call" icon="globe" href="/cases/data_schema/api_call">
    External API data fetch for credit checks and verification
  </Card>
</CardGroup>

## Field Properties

Each field in a case has several properties:

| Property        | Description       | Example                              |
| --------------- | ----------------- | ------------------------------------ |
| **Key**         | Unique identifier | `company_name`, `birth_date`         |
| **Type**        | Field data type   | `text`, `number`, `date`             |
| **Name**        | Display label     | "Company Name", "Date of Birth"      |
| **Description** | Help text         | "Legal name of your company"         |
| **Value**       | Current data      | "Acme Corp", "1990-01-15"            |
| **Visibility**  | Display setting   | Always, hide when empty, always hide |
| **Section**     | Grouping          | "Company Information" section        |

## Visibility Settings

Fields can have different visibility settings to control when they appear:

**Always visible** - Field always appears in the case view, whether it has a value or not. Use for essential fields, required information, and key data points.

**Hidden if empty** - Field only shows when it has a value. Empty fields are hidden. Use for optional fields, conditional data, and supplementary information. This keeps case views clean and focused on relevant information.

**Always hidden** - Field is hidden from view but data is still stored. Use for technical fields, IDs, system data, and calculated values used in automations.

<Tip>
  Use "hidden if empty" for optional fields to keep the case view uncluttered
  while maintaining complete data storage for compliance.
</Tip>

## Sections

Sections organize related fields together, making cases easier to navigate and understand. Sections are groups of fields with a common purpose or theme.

**Example case structure:**

```
📁 Company Information
   - Company Name (text)
   - Registration Number (text)
   - Industry (choices)
   - Website (text)

📁 Financial Data
   - Annual Revenue (number)
   - IBAN (text)
   - Tax ID (text)

📁 Documents
   - Company Registration (file)
   - ID Document (file)
   - Proof of Address (file)
```

**Benefits of sections:**

* **Organization** - Group related fields logically
* **Navigation** - Easier to find specific information
* **Clarity** - Clear separation of different data types
* **Presentation** - Better visual organization
* **Workflow** - Align sections with process steps

<Info>
  Sections are defined in the case template. You cannot add or remove sections
  from existing cases, but you can add or remove fields within sections.
</Info>

## Data Updates

Case data can be updated through multiple channels:

### Manual Updates

Team members can update case fields directly:

* Edit fields in the case view
* Change values as needed
* Updates are tracked in timeline
* Changes can trigger automations

### Form Responses

When contacts submit forms, data flows into the case:

* Form fields map to case fields (based on configuration)
* Responses automatically update case data
* Files are attached to case
* Timeline shows form submission

### Automations

Automated workflows can update fields:

* Calculated values based on other fields
* Status updates based on conditions
* Data transformations
* External API responses

### API Call Fields

API Call fields fetch data from external sources:

* Credit checks from financial services
* Company data from business registries
* Verification services
* Real-time data lookups

## Data Validation

Field values are validated based on their type:

| Field Type   | Validation                      |
| ------------ | ------------------------------- |
| **Text**     | Length limits, pattern matching |
| **Number**   | Numeric values, min/max ranges  |
| **Date**     | Valid dates, date ranges        |
| **Checkbox** | Boolean (true/false)            |
| **Choices**  | Must be from defined options    |
| **File**     | File type, size limits          |

<Note>
  Validation rules are defined in the case template and cannot be changed for
  individual cases.
</Note>

## Keys and References

Each data point has a unique key that identifies it throughout the platform. These keys allow you to:

* Reference data in steps and automations
* Map form responses to case fields
* Use data in email and document templates
* Create calculated fields based on other data
* Trigger automations based on data changes

Keys are typically lowercase with underscores (e.g., `company_name`, `annual_revenue`, `birth_date`) and must be unique within the case template.

<Info>
  Keys are described conceptually here. For the full technical syntax including
  dot notation and variable references, see the penscript documentation.
</Info>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Case Templates" icon="file-lines" href="/cases/case_templates">
    Design data schemas in templates
  </Card>

  {" "}

  <Card title="Contacts" icon="users" href="/cases/contacts">
    Learn about case contacts
  </Card>

  {" "}

  <Card title="Automations" icon="bolt" href="/cases/automations">
    Automate based on data changes
  </Card>

  <Card title="Forms" icon="rectangle-list" href="/forms/introduction">
    Collect data through forms
  </Card>
</CardGroup>