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

# Schema Design Guide

> Best practices for designing effective dataset schemas

A well-designed schema is the foundation of a successful dataset. This guide covers best practices and common patterns.

## Core Principles

### 1. Be Descriptive

Every table, property, and relationship needs clear descriptions. Our AI agents use these to understand what data to extract.

<CodeGroup>
  ```python Good theme={null}
  Property(
      name="revenue",
      description="Annual revenue in USD for the most recent fiscal year",
      prop_type="Money"
  )
  ```

  ```python Bad theme={null}
  Property(
      name="revenue",
      description="Revenue"  # Too vague
  )
  ```
</CodeGroup>

### 2. Use Strong Typing

Leverage our type system to ensure data quality:

```python theme={null}
from structify.types.property_type import Enum

# Available types
Property(name="website", prop_type="URL")
Property(name="employee_count", prop_type="Integer")
Property(name="valuation", prop_type="Money")
Property(name="founded_date", prop_type="Date")
Property(name="is_public", prop_type="Boolean")
Property(name="revenue", prop_type="Float")
Property(name="logo", prop_type="Image")

# Enums for controlled vocabularies
Property(
    name="status",
    description="Current company status",
    prop_type=Enum(Enum=["Active", "Acquired", "Closed", "IPO"])
)
```

### 3. Model Relationships Thoughtfully

Relationships should represent meaningful connections:

```python theme={null}
Relationship(
    name="acquired_by",
    description="The acquiring company in an M&A transaction",
    source_table="company",
    target_table="company",
    properties=[
        RelationshipProperty(
            name="acquisition_date",
            description="Date the acquisition was completed",
            prop_type="Date"
        ),
        RelationshipProperty(
            name="price",
            description="Acquisition price in USD",
            prop_type="Money"
        )
    ]
)
```

## Common Patterns

### Hierarchical Relationships

For parent-child structures:

```python theme={null}
# Company subsidiaries
Relationship(
    name="subsidiary_of",
    description="Child company owned by parent",
    source_table="company",
    target_table="company",
    properties=[
        RelationshipProperty(
            name="ownership_percentage",
            prop_type="Float"
        )
    ]
)
```

### Time-Series Data

For tracking changes over time:

```python theme={null}
Table(
    name="funding_round",
    description="A funding event for a company",
    properties=[
        Property(name="round_type", prop_type=Enum(Enum=["Seed", "Series A", "Series B", "Series C+"])),
        Property(name="amount", prop_type="Money"),
        Property(name="date", prop_type="Date"),
        Property(name="valuation", prop_type="Money")
    ]
)

Relationship(
    name="raised_in",
    description="Company that raised funds in this round",
    source_table="funding_round",
    target_table="company"
)
```

### Many-to-Many Relationships

When entities can have multiple connections:

```python theme={null}
# Board members serving multiple companies
Table(
    name="person",
    description="An individual person",
    properties=[
        Property(name="name", description="Full name"),
        Property(name="title", description="Current professional title")
    ]
)

Relationship(
    name="board_member_of",
    description="Person serves on company board",
    source_table="person",
    target_table="company",
    properties=[
        RelationshipProperty(name="start_date", prop_type="Date"),
        RelationshipProperty(name="end_date", prop_type="Date"),
        RelationshipProperty(name="role", prop_type=Enum(Enum=["Director", "Chairman", "Observer"]))
    ]
)
```

## Schema Examples by Industry

### Financial Services

```python theme={null}
tables = [
    Table(
        name="fund",
        description="Investment fund or vehicle",
        properties=[
            Property(name="name"),
            Property(name="aum", description="Assets under management", prop_type="Money"),
            Property(name="strategy", prop_type=Enum(Enum=["Equity", "Debt", "Hybrid", "Crypto"]))
        ]
    ),
    Table(
        name="portfolio_company",
        description="Company in fund's portfolio",
        properties=[
            Property(name="name"),
            Property(name="sector"),
            Property(name="entry_valuation", prop_type="Money")
        ]
    )
]
```

### Healthcare

```python theme={null}
tables = [
    Table(
        name="clinical_trial",
        description="Medical research study",
        properties=[
            Property(name="trial_id", description="ClinicalTrials.gov ID"),
            Property(name="phase", prop_type=Enum(Enum=["Phase 1", "Phase 2", "Phase 3", "Phase 4"])),
            Property(name="status", prop_type=Enum(Enum=["Recruiting", "Active", "Completed", "Terminated"])),
            Property(name="start_date", prop_type="Date"),
            Property(name="primary_outcome")
        ]
    )
]
```

### E-Commerce

```python theme={null}
tables = [
    Table(
        name="product",
        description="Item for sale",
        properties=[
            Property(name="sku", description="Stock keeping unit"),
            Property(name="name"),
            Property(name="price", prop_type="Money"),
            Property(name="in_stock", prop_type="Boolean"),
            Property(name="category", prop_type=Enum(Enum=["Electronics", "Clothing", "Home", "Books"]))
        ]
    ),
    Table(
        name="vendor",
        description="Product supplier",
        properties=[
            Property(name="name"),
            Property(name="rating", prop_type="Float"),
            Property(name="location")
        ]
    )
]
```

## Advanced Tips

### 1. Plan for Growth

Design schemas that can evolve:

* Start with core properties
* Add detail incrementally
* Use consistent naming conventions

### 2. Balance Normalization

Find the right level of detail:

* Too normalized: Complex to query
* Too denormalized: Redundant data
* Just right: Natural entity boundaries

### 3. Consider Your Sources

Design for the data you can actually get:

* Public web data: Keep it simple
* Internal documents: Can be detailed
* APIs: Match their structure

### 4. Validate Early

Test your schema with sample data:

```python theme={null}
# Create a test dataset
client.datasets.create(
    name="test_schema",
    description="Testing schema design",
    tables=tables,
    relationships=relationships
)

# Add sample entities
test_entity = client.entities.add(
    dataset="test_schema",
    kg=KnowledgeGraphParam(
        entities=[EntityParam(
            id=0,
            type="company",
            properties={"name": "Test Corp"}
        )]
    )
)

# Try enrichment
client.structure.enhance_property(
    entity_id=test_entity.id,
    property_name="description"
)
```

## Common Mistakes to Avoid

<Warning>
  **Don't forget descriptions** - Properties without clear descriptions produce poor extraction results
</Warning>

<Warning>
  **Don't over-constrain enums** - Leave room for edge cases with an "Other" option
</Warning>

<Warning>
  **Don't create circular dependencies** - Be careful with self-referential relationships
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Financial Schema" icon="chart-line" href="/schema-cookbook/financial-schema">
    Ready-to-use financial dataset schema
  </Card>

  <Card title="E-Commerce Schema" icon="shopping-cart" href="/schema-cookbook/ecommerce-schema">
    Product and vendor tracking
  </Card>
</CardGroup>