Terraform Provider for Schematic

Manage Schematic configuration — features, flags, plans, and plan entitlements — declaratively with Terraform or OpenTofu, instead of clicking through the UI. Configuration lives in version control, survives data loss, and bad changes can be reviewed before they ship and reverted after.

Resources & data sources

Type	Name	Purpose
Resource	schematic_feature	Boolean, event-based, or trait-based features
Resource	schematic_flag	Feature flags, including targeting rules
Resource	schematic_plan	Plans and add-ons
Resource	schematic_plan_entitlement	Feature values granted by a plan
Data source	schematic_feature	Look up a feature by ID or name
Data source	schematic_flag	Look up a flag by ID or key
Data source	schematic_plan	Look up a plan by ID or name

All resources support terraform import <address> <id>.

Deliberately out of scope (for now): billing/pricing fields on entitlements (Stripe-linked prices, tiers, overage products), company overrides, and plan version publishing.

Usage

terraform {
  required_providers {
    schematic = {
      source  = "sema4ai/schematic"
      version = "~> 0.1"
    }
  }
}

provider "schematic" {
  # or set SCHEMATIC_API_KEY
  api_key = var.schematic_api_key
}

resource "schematic_feature" "api_requests" {
  name          = "API Requests"
  feature_type  = "event"
  event_subtype = "api-request"
}

resource "schematic_plan" "pro" {
  name      = "Pro"
  plan_type = "plan"
}

resource "schematic_plan_entitlement" "pro_api_requests" {
  plan_id       = schematic_plan.pro.id
  feature_id    = schematic_feature.api_requests.id
  value_type    = "numeric"
  value_numeric = 10000
  metric_period = "current_month"
}

See docs/ for full resource documentation and examples/ for more examples.

Authentication

Create a secret API key in Schematic (Settings → API Keys) for the environment you want to manage. API keys are environment-scoped, so use one provider configuration (with an alias) per environment.

Importing existing configuration

To snapshot an entire hand-built environment into Terraform code, use the bundled exporter. It reads every feature, flag, plan, and plan entitlement through the API and generates both the resource definitions (cross-referenced, with flag targeting rules) and the matching import blocks:

export SCHEMATIC_API_KEY=sch_...      # secret key for the source environment
go run ./tools/export -out ./snapshot
cd ./snapshot
tofu plan                             # expect: N to import, 0 to add/change
tofu apply                            # adopts everything into state, changes nothing
rm imports.tf                         # one-shot; not needed after adoption

Anything the provider doesn't manage (billing/pricing entitlement fields, non-standard flag rules, unpublished draft-version nuances) is reported as a warning on stderr rather than silently dropped. Individual objects can also be imported by hand:

terraform import schematic_feature.api_requests feat_...
terraform import schematic_flag.sso flag_...
terraform import schematic_plan.pro plan_...
terraform import schematic_plan_entitlement.pro_api_requests pltl_...

Flag targeting rules

• Rules are evaluated in list order; the first rule in rules has the highest priority.
• Only standard targeting rules are managed. Rules that Schematic generates from plan entitlements are left alone and never appear in state.
• Omitting rules leaves existing rules unmanaged; set rules = [] to delete all targeting rules.

Development

go build ./...          # build
go test ./...           # unit tests
make e2e                # full lifecycle test against a local mock of the Schematic API
make testacc            # acceptance tests against a real environment (needs SCHEMATIC_API_KEY)
make docs               # regenerate docs/ from schema + examples

Acceptance tests create and destroy real objects — point SCHEMATIC_API_KEY at a disposable environment.

To use a locally built provider, add a dev override to your CLI config:

provider_installation {
  dev_overrides {
    "sema4ai/schematic" = "/path/to/terraform-provider-schematic"
  }
  direct {}
}

Releasing

Releases are built by GoReleaser via GitHub Actions when a v* tag is pushed. Publishing to the Terraform Registry requires the GPG_PRIVATE_KEY and PASSPHRASE repository secrets and a one-time registry namespace setup.