> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource Validation

> Validate resource YAML files against the Kodexa API schema with kdx validate, catching typos, missing required fields, and type mismatches before deployment.

## Overview

The `kdx validate` command checks a resource YAML file against the platform's OpenAPI schema **without sending anything to the server**. It helps catch errors before you deploy, surfacing typos, missing required fields, and type mismatches.

```bash theme={null}
kdx validate -f resource.yaml
```

## What It Checks

### Missing Required Keys

Fields the API schema marks as required but are missing from your YAML:

```text theme={null}
  Errors:
    version: required key missing
```

### Type Mismatches

Values whose types don't match what the schema expects:

```text theme={null}
  Errors:
    options[1].default: expected object, got boolean
```

### Unknown Keys

Keys in your YAML that don't appear in the API schema. These are reported as **warnings** since the API may accept and ignore them, but they likely indicate a typo or a field that has no effect:

```text theme={null}
  Warnings:
    bogusField: key not found in schema
    misspelledDescrption: key not found in schema
```

<Note>
  Unknown key warnings are only reported when the schema defines properties to compare against. If a schema has `additionalProperties: false`, unknown keys are reported as **errors** instead.
</Note>

### Envelope Key Validation

When using the `spec` wrapper format, top-level keys are checked against the recognized envelope fields (`type`, `slug`, `orgSlug`, `name`, `metadata`, `storeType`, `spec`):

```text theme={null}
  Warnings:
    bogusEnvelope: unknown top-level key (not a recognized envelope field)
```

## Usage

### Basic Validation

```bash theme={null}
# Validate a module definition
kdx validate -f model.yml

# Validate a data form
kdx validate -f data-form.yaml

# Validate any resource type
kdx validate -f resource.yaml
```

### Example Output

**Clean validation:**

```text theme={null}
  Validating dataForm: My Data Form (data-form.yaml)

  Resource type 'dataForm' found

  Validation passed -- all keys recognized, no type mismatches
```

**Validation with issues:**

```text theme={null}
  Validating knowledgeItemType: My Knowledge Type (knowledge-type.yaml)

  Resource type 'knowledgeItemType' found
  Errors:
    version: required key missing
    options[1].default: expected object, got boolean
  Warnings:
    apiVersion: key not found in schema
    bogusField: key not found in schema

  Result: 2 error(s), 2 warning(s)
```

The command exits with a non-zero exit code when there are errors, making it suitable for CI pipelines. Warnings alone do not cause a non-zero exit.

## How It Works

1. **Parses the YAML** file and extracts the `type` field
2. **Resolves the resource type** using the platform's OpenAPI discovery (same as `kdx apply`)
3. **Extracts the JSON schema** from the OpenAPI spec for that resource's create operation
4. **Recursively walks** all keys in the YAML and compares them against the schema properties
5. **Reports** missing required fields, type mismatches, and unknown keys

The OpenAPI spec is cached locally (same cache as `kdx api-resources`). If the cache is stale, refresh it:

```bash theme={null}
kdx api-resources --refresh
```

## Supported YAML Formats

The validate command supports both resource file formats used by the CLI:

### Flat Format

All fields at the top level (used by `kdx apply`):

```yaml theme={null}
type: knowledgeItemType
name: My Knowledge Type
slug: my-knowledge-type
orgSlug: kodexa
description: A knowledge item type
options:
  - name: myOption
    type: text
```

### Spec Wrapper Format

Fields nested under a `spec` key (used by `kdx sync`):

```yaml theme={null}
type: data-definition
slug: invoice-data
spec:
  name: Invoice Data
  description: Invoice extraction and review data model
  attributes: []
```

## CI/CD Integration

Use `kdx validate` in your CI pipeline to catch issues before deployment:

```yaml theme={null}
# GitHub Actions example
- name: Validate resources
  run: |
    for f in resources/*.yaml; do
      kdx validate -f "$f" --profile dev
    done
```

Since the command exits with a non-zero code on errors, your pipeline will fail if any resource file has validation issues.

## Limitations

* Validation depends on the OpenAPI schema published by your platform. If the schema doesn't define properties for a resource type, key-level validation is limited to required field checks.
* Some resource types use permissive schemas where any additional fields are accepted. In these cases, unknown keys are reported as warnings rather than errors.
* The command requires API connectivity for the initial OpenAPI spec fetch (subsequent runs use the cache).

## Next Steps

<CardGroup cols={2}>
  <Card title="Resource Operations" icon="gears" href="/guides/kdx-cli/resource-operations">
    Create, update, and delete resources with `kdx apply`
  </Card>

  <Card title="Metadata Sync" icon="code-branch" href="/guides/kdx-cli/sync/overview">
    Set up GitOps workflows for infrastructure as code
  </Card>
</CardGroup>