Describe the Bug

Hello,

We're seeing a regression upon upgrading from 1.221.0 to 1.225.0 which seems to be caused by a combination of updates over the past few releases, starting with #2749. Despite that PR going out with 1.221.0, we do not see the issue until 1.224.0 due to some changes made in that release and it was made worse with 1.225.0.

Backstory:

I reported #2592 to request automated updates of the atmos online schema and in that issue, I mentioned a failure around required_providers and required_version that happened as a result of trying to pin to the online schema because the schema was missing those 2 fields.

While the actual issue (of the online schema being out of sync with the built-in schema) was resolved by that PR and released with atmos 1.221.0, it seems that the required_providers and required_version fields were left out, as I do not find those fields in the PR manifest.

Investigation:

After upgrading to 1.225.0 we started getting the following from atmos describe stacks:

❯ atmos describe stacks --process-templates=false
⚠ stacks/orgs/clinsphere-fe/azure/eastus/sbx/synaptic.yaml:142:11: warning: components.terraform.postgres-database-basic.settings.depends_on is deprecated; use dependencies.components
⚠ stacks/orgs/clinsphere-fe/azure/eastus/sbx/synaptic.yaml:109:11: warning: components.terraform.postgres-server-basic.settings.depends_on is deprecated; use dependencies.components

   Error

   Error:

    • catalog/api-route.yaml:7:7: error: components.terraform.api-route: additionalProperties 'required_providers' not allowed
    • catalog/azure-ai-search.yaml:8:7: error: components.terraform.azure-ai-search: additionalProperties 'required_providers' not allowed
    • catalog/azure-communications-services.yaml:7:7: error: components.terraform.azure-communications-services: additionalProperties 'required_providers' not allowed
    • catalog/azure-service-bus.yaml:8:7: error: components.terraform.azure-service-bus: additionalProperties 'required_providers' not allowed
    • catalog/azure-web-pubsub.yaml:8:7: error: components.terraform.azure-web-pubsub: additionalProperties 'required_providers' not allowed
    • catalog/static-web-app-defaults.yaml:7:7: error: components.terraform.static-web-app-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-endpoint-defaults.yaml:7:7: error: components.terraform.frontdoor-endpoint-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-origin-acs.yaml:7:7: error: components.terraform.frontdoor-origin-acs: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-origin-api-defaults.yaml:7:7: error: components.terraform.frontdoor-origin-api-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-origin-blob-defaults.yaml:7:7: error: components.terraform.frontdoor-origin-blob-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-origin-swa-defaults.yaml:7:7: error: components.terraform.frontdoor-origin-swa-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-origin-url-defaults.yaml:7:7: error: components.terraform.frontdoor-origin-url-defaults: additionalProperties 'required_providers' not allowed
    • catalog/frontdoor-route-defaults.yaml:9:7: error: components.terraform.frontdoor-route-defaults: additionalProperties 'required_providers' not allowed
    • catalog/key-vault-destruct.yaml:9:7: error: components.terraform.key-vault: additionalProperties 'required_providers' not allowed
    • catalog/key-vault-secrets.yaml:4:7: error: components.terraform.key-vault-secrets: additionalProperties 'required_providers' not allowed
    • catalog/key-vault.yaml:9:7: error: components.terraform.key-vault: additionalProperties 'required_providers' not allowed
    • catalog/managed-disk-common.yaml:4:7: error: components.terraform.managed-disk-common: additionalProperties 'required_version' not allowed
    • catalog/platform-elements.yaml:7:7: error: components.terraform.platform-elements: additionalProperties 'required_providers' not allowed
    • catalog/postgres-database-base.yaml:4:7: error: components.terraform.postgres-database-base: additionalProperties 'required_providers', 'required_version' not allowed
    • catalog/postgres-server-base.yaml:4:7: error: components.terraform.postgres-server-base: additionalProperties 'required_providers' not allowed
    • catalog/static-web-app.yaml:4:7: error: components.terraform.static-web-app: additionalProperties 'required_providers' not allowed
    • catalog/storage-azure-blob-container.yaml:8:7: error: components.terraform.storage-azure-blob-container: additionalProperties 'required_version' not allowed
    • catalog/storage-azure-files-share.yaml:8:7: error: components.terraform.storage-azure-files-share: additionalProperties 'required_version' not allowed
    • catalog/template-component.yaml:4:7: error: components.terraform.template-component: additionalProperties 'required_providers' not allowed
    • catalog/vnet-defaults.yaml:9:7: error: components.terraform.vnet-defaults: additionalProperties 'required_providers', 'required_version' not allowed
    • orgs/clinsphere-fe/azure/_defaults.yaml:111:7: error: components.terraform.azure-defaults: additionalProperties 'required_providers', 'required_version' not allowed
    • orgs/clinsphere-fe/azure/_defaults.yaml:111:7: error: components.terraform.azure-defaults: additionalProperties 'required_version', 'required_providers' not allowed

Subsequent to this, I started installing the intermediate versions to identify which release has the issue first, and simultaneously had claude start checking into the issue by digging through the code here in github.

Claude found that version 1.224.0 was the first release to break atmos validate stacks and 1.225.0 broke atmos describe stacks, and I was able to confirm the same via command line.

It appears that additionalProperties: false was added to the schema and that the fields mentioned were not added.

We heavily use these fields and need this fixed in order to upgrade past 1.224.0.

Copilot analysis

Summary

Since atmos-manifest JSON Schema validation was wired into atmos validate stacks (v1.224.0) and atmos describe stacks (v1.225.0), any stack manifest using the documented
terraform.required_version / terraform.required_providers (or components.terraform.<name>.required_version / required_providers) fields now fails schema validation, even
though these fields are fully implemented, supported, and processed by the stack processor.

Root Cause

Atmos has two independent, drifting JSON Schema copies for stack manifests:

1. pkg/datafetcher/schema/stacks/stack-config/1.0.json — legacy schema
2. pkg/datafetcher/schema/atmos/manifest/1.0.json — the "atmos-manifest" schema, now the sole schema enforced by validate/describe
   feat(dev-3124): Pin Terraform provider versions via required_providers #1841 ("feat(dev-3124): Pin Terraform provider versions via required_providers", merged 2026-05-15, closes feat: add test steps, build controls, and default CLI help #3124) added native required_version/required_providers
   support:

• Go struct fields RequiredVersion / RequiredProviders in pkg/schema/schema.go (still present today)
• Full stack-processor support (merge/inheritance/overrides) — still present today
• JSON Schema $ref entries and definitions.required_version / definitions.required_providers — but only added to pkg/datafetcher/schema/stacks/stack-config/1.0.json,
  not to pkg/datafetcher/schema/atmos/manifest/1.0.json.

#2749 ("Consolidate atmos-manifest schema, publish per-release pins", merged 2026-07-16, closed #2592) made pkg/datafetcher/schema/atmos/manifest/1.0.json the single
source of truth, replacing/removing the separately-drifting website copy — but it never reconciled it against stack-config/1.0.json. The consolidated schema still lacks
required_version/required_providers, and its terraform/terraform_component_manifest object definitions set "additionalProperties": false, enumerating every other
supported key (vars, hooks, backend, providers, generate, dependencies, …) but omitting these two.
This drift was silent and harmless while the schema wasn't actively enforced. It became a breaking regression once schema validation was wired into:

• atmos validate stacks — v1.224.0
• atmos describe stacks — v1.225.0

Hard Evidence

1. The Go implementation still fully supports these fields (pkg/schema/schema.go, current main):

// RequiredVersion is the Terraform version constraint (e.g., ">= 1.10.1").
// This is extracted from terraform.required_version or components.terraform.<name>.required_version.
RequiredVersion string
// RequiredProviders maps provider names to their configuration.
// This is extracted from terraform.required_providers or components.terraform.<name>.required_providers.
RequiredProviders map[string]map[string]any

2. PR #1841 added schema support — but only to the legacy stack-config schema, not atmos-manifest:
Diff from #1841, file pkg/datafetcher/schema/stacks/stack-config/1.0.json:

+            "required_version": {
+              "$ref": "#/definitions/required_version"
+            },
+            "required_providers": {
+              "$ref": "#/definitions/required_providers"
+            },
...
+    "required_version": {
+      "title": "required_version",
+      "description": "Terraform required version constraint (e.g., '>= 1.10.1')",
+      "type": "string"
+    },
+    "required_providers": {
+      "title": "required_providers",
+      "description": "Terraform required providers section for version pinning",
+      ...

This file (pkg/datafetcher/schema/stacks/stack-config/1.0.json) still contains these definitions today on main.
3. pkg/datafetcher/schema/atmos/manifest/1.0.json — the schema actually enforced by validate/describe — has never had these fields, before or after #2749:

• At commit 6b3b0ef (base of PR Consolidate atmos-manifest schema, publish per-release pins #2749, pre-consolidation): no required_version/required_providers.
• At current main (post-Consolidate atmos-manifest schema, publish per-release pins #2749): still no required_version/required_providers.
• Same result confirmed against the live published copy at https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json.
  Its terraform and terraform_component_manifest definitions are "additionalProperties": false and enumerate every other supported key except these two:

"terraform": {
  ...
  "additionalProperties": false,
  "properties": {
    "vars": {...}, "hooks": {...}, "env": {...}, "settings": {...},
    "locals": {...}, "command": {...}, "backend_type": {...}, "backend": {...},
    "remote_state_backend_type": {...}, "remote_state_backend": {...},
    "overrides": {...}, "providers": {...}, "generate": {...},
    "dependencies": {...}, "depends_on": {...}, "provision": {...}
    // required_version / required_providers: absent
  }
}

4. Real-world impact — our repo (clinsphere-iac) uses required_providers under a component today, e.g. stacks/catalog/key-vault.yaml:

components:
  terraform:
    key-vault:
      metadata: {...}
      required_providers:
        cloudsmith:
          source: cloudsmith-io/cloudsmith
          version: "~> 0.0"
        time:
          source: hashicorp/time
          version: "~> 0.13.1"

Because the enforced schema's additionalProperties: false list doesn't include required_providers, this now fails validation under atmos validate stacks (1.224.0+) and
atmos describe stacks (1.225.0+).

Timeline

Date	Event
2025-12-05	PR #1841 opened (required_providers/required_version feature)
2026-05-15	PR #1841 merged — feature + stack-config schema updated, atmos-manifest schema left behind
2026-06-10	Issue #2592 filed, citing this exact drift as evidence the schema needs versioning
2026-07-16	PR #2749 merged — consolidates atmos-manifest schema as sole source of truth, but doesn't inherit the fields from stack-config; still no required_version/required_providers
v1.224.0	Schema validation wired into atmos validate stacks
v1.225.0	Schema validation wired into atmos describe stacks

Suggested Fix

Port the required_version / required_providers $refs and definitions from pkg/datafetcher/schema/stacks/stack-config/1.0.json into
pkg/datafetcher/schema/atmos/manifest/1.0.json, in all three locations they're needed: the stack-level terraform section, terraform_component_manifest, and any other
component-type sections with additionalProperties: false. Ideally also retire/merge the redundant stack-config schema entirely to prevent this class of drift from recurring, matching the spirit of #2749's original consolidation goal.

Expected Behavior

No regression; required_providers and required_version work properly.

Steps to Reproduce

Steps to Reproduce

Minimal project — four files:

atmos.yaml

base_path: "."
components:
  terraform:
    base_path: "components/terraform"
stacks:
  base_path: "stacks"
  included_paths:
    - "deploy/**/*"
  name_pattern: "{stage}"
logs:
  level: Info

components/terraform/foo/main.tf

variable "x" {
  type    = string
  default = "y"
}

stacks/deploy/dev.yaml — component-level placement (what the generator reads)

vars:
  stage: dev
components:
  terraform:
    foo:
      required_version: ">= 1.9.0"
      required_providers:
        azurerm:
          source: hashicorp/azurerm
          version: "~> 4.12.0"
      vars:
        x: hello

stacks/deploy/qa.yaml — same keys nested under settings (what the schema permits)

vars:
  stage: qa
components:
  terraform:
    foo:
      settings:
        required_version: ">= 1.9.0"
        required_providers:
          azurerm:
            source: hashicorp/azurerm
            version: "~> 4.12.0"
      vars:
        x: hello

1. Validation rejects the placement the generator needs

$ atmos validate stacks
✗ Stack validation failed
 
# Error
 
**Error:**
 
  • deploy/dev.yaml:6:7: error: components.terraform.foo: additionalProperties
    'required_providers', 'required_version' not allowed

atmos describe stacks fails the same way on 1.225.0 and exits 1.

2. …yet the generator reads exactly that placement

$ atmos terraform generate required-providers foo -s dev
$ cat components/terraform/foo/terraform_override.tf.json
{
  "terraform": {
    "required_providers": {
      "azurerm": {
        "source": "hashicorp/azurerm",
        "version": "~> 4.12.0"
      }
    },
    "required_version": ">= 1.9.0"
  }
}

3. The schema-legal placement silently produces nothing

$ atmos terraform generate required-providers foo -s qa
INFO  No required_version or required_providers configured for component component=foo stack=qa
 
$ ls components/terraform/foo
main.tf          # no terraform_override.tf.json

Screenshots

No response

Environment

No response

Additional Context

No response