---
title: "Validate a formation template"
method: POST
path: "/v1/projects/{project_id}/formations/validate"
tags: ["Formations"]
---

# Validate a formation template

`POST /v1/projects/{project_id}/formations/validate`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/formations/validate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.

## Request body

- object
  - `template` union: A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing.
    - FormationTemplate
      - `parameters` object, nullable: Declared parameters for this template. Each parameter may have a default value and an optional description. Parameters without a default must be supplied in the `parameters` field of the deploy request.
      - `resources` object, required: Map of logical resource IDs to resource declarations
      - `outputs` object, nullable: Map of output names to values. Values may use `{ "ref": "logicalId" }` to reference physical IDs of created resources, or `{ "param": "ParamName" }` and `{ "sub": "text ${ParamName}" }` to embed parameter values. `{ "ref_attr": "LogicalId.attribute" }` resolves a named attribute of a created resource, except one carrying credential material — a trigger's or webhook's `secret` is refused with 400 VALIDATION_FAILED, since a formation is readable by anyone holding `formations:GetFormation`. Read those from the resource's own secret route instead.
      - `metadata` NullableMetadataBag, nullable: A `MetadataBag` on a request field where `null` is meaningful: a full-replacement update that clears the bag. A record whose bag is unset leaves the field out.
    - string: YAML or JSON string representation of a FormationTemplate
  - `parameters` object, nullable: Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. When provided, the validation result also reports required parameters that are still missing after applying these values.

## Response `200`

Validation result

- ValidationResult
  - `valid` boolean
  - `errors` ValidationError[]
    - `path` string: JSON path to the field with the error
    - `message` string: Error description
  - `warnings` ValidationError[]
    - `path` string: JSON path to the field with the error
    - `message` string: Error description

## Other responses

- `401`: Unauthorized

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)