Schema Design

Module 4: Schema Design

Welcome to Module 4! Schema design is one of the most important aspects of provider development. A well-designed schema creates an intuitive, type-safe interface that users love to work with.

In this module, you’ll learn how to design schemas that are both powerful and easy to use.

What is a Schema?

A schema defines the structure of your provider’s configuration—what attributes users can set, their types, and validation rules.

Example:

resource "mycloud_environment" "prod" {
  name     = "production"     # String attribute
  region   = "us-east-1"      # String attribute
  replicas = 3                # Number attribute
  
  config {                    # Block
    memory_gb = 4
    cpu_cores = 2
  }
}

The schema defines:

• name is a required string
• region is an optional string with default
• replicas is a number
• config is a nested block with sub-attributes

Why Schema Design Matters

Good schema design:

• ✅ User Experience — Intuitive, self-documenting configurations
• ✅ Type Safety — Catches errors at plan time, not apply
• ✅ Validation — Enforces business rules automatically
• ✅ Documentation — Auto-generates clear docs
• ✅ Backwards Compatibility — Enables smooth upgrades

Poor schema design:

• ❌ Confusing attribute names
• ❌ Unclear requirements
• ❌ Runtime errors instead of plan-time validation
• ❌ Breaking changes in updates

Module Learning Objectives

By the end of this module, you will:

1. Understand attribute types — String, Number, Bool, List, Map, Set, Object
2. Design block structures — Single, list, and set blocks
3. Implement validation — Built-in and custom validators
4. Handle sensitive data — Mark and protect secrets
5. Use computed attributes — Values determined by provider
6. Create optional vs required fields — Proper defaults
7. Design nested schemas — Complex configurations
8. Follow best practices — Schema design patterns

Module Chapters

Chapter 1: Attribute Types

Time: 45 minutes

Learn about all available attribute types in the Plugin Framework and when to use each.

• Primitive types (String, Number, Bool)
• Collection types (List, Map, Set)
• Complex types (Object)
• Type coercion and conversion

Start Chapter →

---

Chapter 2: Blocks vs Attributes

Time: 30 minutes

Understand the difference between blocks and attributes, and when to use each pattern.

• Block syntax vs attribute syntax
• Single blocks
• List blocks
• Set blocks
• Design considerations

Continue →

---

Chapter 3: Required, Optional, and Computed

Time: 40 minutes

Master the three attribute configurations and their combinations.

• Required attributes
• Optional attributes
• Computed attributes
• Optional + Computed patterns
• Default values

Continue →

---

Chapter 4: Validation and Constraints

Time: 50 minutes

Implement robust validation to catch errors early.

• Built-in validators
• Custom validators
• Attribute-level validation
• Cross-attribute validation
• Error messages

Continue →

---

Chapter 5: Sensitive Attributes

Time: 30 minutes

Properly handle secrets and sensitive data.

• Marking attributes as sensitive
• State file implications
• Logging considerations
• Best practices

Continue →

---

Chapter 6: Nested Schemas

Time: 45 minutes

Design complex nested configurations.

• Single nested attributes
• List nested attributes
• Set nested attributes
• Map nested attributes
• Deep nesting patterns

Continue →

---

Chapter 7: Schema Best Practices

Time: 40 minutes

Learn industry best practices for schema design.

• Naming conventions
• Backwards compatibility
• Deprecation strategies
• Common anti-patterns
• Real-world examples

Continue →

---

Chapter 8: Hands-On Lab

Time: 60 minutes

Build a complete resource schema with validation.

• Design multi-level schema
• Implement all attribute types
• Add comprehensive validation
• Test schema behavior

Continue →

---

Chapter 9: Practice Questions

Time: 30 minutes

Test your schema design knowledge.

• Multiple choice questions
• Schema design exercises
• Troubleshooting scenarios
• Best practice identification

Continue →

---

Module Prerequisites

Before starting this module:

• ✅ Completed Module 3: Development Setup
• ✅ Go development environment configured
• ✅ Basic provider project created
• ✅ Familiar with Terraform HCL syntax

Tools & Concepts

This module covers:

• terraform-plugin-framework schema package
• Attribute and block types
• Validators and validation
• Type system fundamentals
• HCL syntax and semantics

Estimated Time

Total module time: ~6 hours

• Reading and examples: ~4 hours
• Hands-on lab: ~1 hour
• Practice questions: ~30 minutes
• Review and exploration: ~30 minutes

What You’ll Build

In this module’s lab, you’ll create a complete resource schema for a fictional “Application” resource:

resource "mycloud_application" "web" {
  name        = "web-frontend"
  description = "Production web application"
  environment = "production"
  
  runtime {
    language = "nodejs"
    version  = "20.x"
  }
  
  scaling {
    min_instances = 2
    max_instances = 10
    target_cpu    = 70
  }
  
  env_vars = {
    NODE_ENV = "production"
    LOG_LEVEL = "info"
  }
  
  secrets = {
    api_key = "sensitive-value"
  }
  
  health_check {
    path     = "/health"
    interval = 30
    timeout  = 5
  }
  
  tags = ["web", "frontend", "production"]
}

This schema demonstrates:

• Multiple attribute types
• Nested blocks
• Validation rules
• Sensitive data handling
• Optional vs required fields
• Computed values

Learning Path

Schema Fundamentals
    ↓
Attribute Types
    ↓
Blocks & Nesting
    ↓
Validation
    ↓
Best Practices
    ↓
Hands-On Lab
    ↓
Assessment

Key Takeaways Preview

After this module, you’ll understand:

• ✅ How to choose the right attribute types
• ✅ When to use blocks vs attributes
• ✅ How to implement effective validation
• ✅ Best practices for user-friendly schemas
• ✅ Common schema design patterns
• ✅ How to handle complex nested structures

Development Environment

You’ll need:

• Provider project from Module 3
• Text editor or IDE
• Terraform CLI for testing
• Terminal access

Next Steps

Ready to dive into attribute types? Let’s start with Chapter 1!

Begin Chapter 1: Attribute Types →

---

Previous Module: ← Development Setup

Last updated: June 30, 2026