Skip to main content

​
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. 
kdx validate -f resource.yaml

​
What It Checks

​
Missing Required Keys

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

​
Type Mismatches

Values whose types don’t match what the schema expects: 
  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: 
  Warnings:
    bogusField: key not found in schema
    misspelledDescrption: key not found in schema
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.

​
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): 
  Warnings:
    bogusEnvelope: unknown top-level key (not a recognized envelope field)

​
Usage

​
Basic Validation

# 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: 
  Validating dataForm: My Data Form (data-form.yaml)

  Resource type 'dataForm' found

  Validation passed -- all keys recognized, no type mismatches
Validation with issues: 
  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: 
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): 
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): 
type: taxonomy
slug: my-taxonomy
spec:
  name: My Taxonomy
  description: A taxonomy definition
  taxons: []

​
CI/CD Integration

Use kdx validate in your CI pipeline to catch issues before deployment: 
# 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

Resource Operations

Create, update, and delete resources with kdx apply

Metadata Sync

Set up GitOps workflows for infrastructure as code