Resource Validation - Kodexa Developer Portal

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

Parses the YAML file and extracts the type field
Resolves the resource type using the platform’s OpenAPI discovery (same as kdx apply)
Extracts the JSON schema from the OpenAPI spec for that resource’s create operation
Recursively walks all keys in the YAML and compares them against the schema properties
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: 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:

# 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

​Overview

​What It Checks

​Missing Required Keys

​Type Mismatches

​Unknown Keys

​Envelope Key Validation

​Usage

​Basic Validation

​Example Output

​How It Works

​Supported YAML Formats

​Flat Format

​Spec Wrapper Format

​CI/CD Integration

​Limitations

​Next Steps

Resource Operations

Metadata Sync

Overview

What It Checks

Missing Required Keys

Type Mismatches

Unknown Keys

Envelope Key Validation

Usage

Basic Validation

Example Output

How It Works

Supported YAML Formats

Flat Format

Spec Wrapper Format

CI/CD Integration

Limitations

Next Steps