# Validate a definition (/en/docs/api/native/automation/validateDefinition)





Check source without executing it when you need diagnostics, inferred schemas or references. This is optional before praxis.automation.runs.create, which also validates source before execution. Actions, scripts and workflows are supported; results include validity without saving. Invalid source is reported with valid=false. Script/action output schemas are inferred from return types: Promise unwrapping, Record, intersections and Date. Unknown types yield an empty schema and a warning in warnings. Source diagnostics use /source or /implementation/source with 1-based line/column. For kind=action the same admission checks as action creation apply (no external imports, platform operations only as direct call(praxis/<api>.<op>, input) calls, no agent or automation calls), so source that validates is not rejected at creation.

`POST /automation/v1/validate`

## Authentication [#authentication]

`Authorization: Bearer $PRAXIS_API_KEY`

## Request fields [#request-fields]

### application/json [#applicationjson]

no additional fields.

| Field | Type | Description |
| --- | --- | --- |
| kind | `"action"` / `"script"` / `"workflow"` | required; Source kind: action, script or workflow. |
| source | `string` | required; Source to validate: TypeScript for action/script, YAML for workflow. |

## Examples [#examples]

[SDK installation and example environment](/en/docs/api/native/automation)

```bash
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/validate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "kind": "script",
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'
```

```typescript
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.validate.create({
  "body": {
    "kind": "script",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
});
console.log(result);
```

## Response [#response]

### HTTP 200 [#http-200]

Success

`application/json`

| Field | Type | Description |
| --- | --- | --- |
| valid | `boolean` | required; Whether the source passed validation: true means it can be published or run, false means see errors. |
| errors | `object[]` | required; Validation errors, each with pointer and a Chinese detail; empty when valid is true. |
| errors[].pointer | `string` | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| errors[].detail | `string` | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| errors[].hint | `string` | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| errors[].line | `integer` | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| errors[].column | `integer` | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| input_schema | `null` / `object` | required; Input JSON Schema derived from the source, or null when the source cannot be parsed. |
| input_schema (variant 2).* (variant 5) | `object` | Recursive JSON value. |
| input_schema (variant 2).* (variant 6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | Recursive JSON value. |
| output_schema | `null` / `object` | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema (variant 2).* (variant 5) | `object` | Recursive JSON value. |
| output_schema (variant 2).* (variant 6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | Recursive JSON value. |
| references | `object[]` | required; Actions, platform APIs, scripts and workflows the source depends on. |
| references[].kind | `"action"` / `"script"` / `"workflow"` / `"platform_api"` / `"run"` | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | `string` | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | `string` | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | `string` | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | `null` / `object[]` | required; Workflow step outline; null for scripts and actions. |
| outline (variant 2)[].name | `string` | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | `string` | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | `"run"` / `"call"` / `"wait"` / `"set"` / `"for"` / `"fork"` / `"try"` / `"switch"` / `"emit"` / `"raise"` / `"listen"` / `"do"` | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | `string` | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | `object` | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | `string` | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | `number` | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | `string` | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | `string` | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | `object` | optional; Loop information &#123;each, in&#125; of a for step. no additional fields. |
| outline (variant 2)[].loop.each | `string` | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | `string` | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | `object[]` | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | `object` | Recursive JSON value. |
| warnings | `object[]` | optional; Non-blocking script/action analysis diagnostics; an unknown type yields an empty schema and a warning. Workflow analysis may omit this field. |
| warnings[].pointer | `string` | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| warnings[].detail | `string` | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| warnings[].hint | `string` | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| warnings[].line | `integer` | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| warnings[].column | `integer` | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| platform_apis | `string[]` | optional; Platform API names referenced by script/action analysis, as a string array; workflow analysis may omit this field. |

### Measured response [#measured-response]

HTTP 200

```json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ]
  },
  "references": [],
  "outline": null,
  "platform_apis": []
}
```

## Errors [#errors]

| HTTP | Codes and description |
| --- | --- |
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

[Authentication and common errors](/en/docs/api/errors) · Retain the `X-Request-Id` response header for troubleshooting.