`ptkl validate-idl`

Validate a value against any IDL from the command line. Useful for testing IDL definitions before wiring them up, gating deployments in CI, or debugging unexpected validation failures.

Overview

ptkl validate-idl calls POST /v1/system/idl/validate and reports whether the provided value satisfies the requested IDL. The command exits with code 0 when valid and 1 when invalid (or on any request-level error).

Usage

ptkl validate-idl [options]

Either --ref or --idl-file must be provided. Exactly one of --value or --value-file must supply the value to validate.

Options

Option	Description
`--ref <ref>`	Compound ref identifying which IDL to validate against. See ref formats.
`--idl-file <path>`	Path to a JSON file containing an inline IDL definition.
`--field <key>`	Field key to validate against (required for `component` and `extension` refs).
`--value <json>`	Inline JSON value to validate.
`--value-file <path>`	Path to a JSON file containing the value to validate.
`--env <env>`	Target environment (`dev`, `live`). Defaults to `dev`.
`--profile <name>`	Authentication profile to use.

Ref Formats

Ref	Resolves
`component:{namespace}::{name}`	Base component IDL (default schema)
`component:{namespace}::{name}.{schema}`	Named schema on a base component
`extension:{namespace}::{name}/{extName}`	Extension IDL attached to a component
`pfn:{functionName}`	Platform function — validates `value` against `signature.input`

Exit Codes

Code	Meaning
`0`	Value is valid
`1`	Value is invalid, or a request-level error occurred

Examples

Validate a component field by ref:

ptkl validate-idl \
  --ref component:ecommerce::order \
  --field items \
  --value '[{"sku":"ABC","quantity":2,"price":9.99}]'

Validate a named schema field:

ptkl validate-idl \
  --ref component:ecommerce::order.premium \
  --field shipping \
  --value-file ./test-data/shipping.json

Validate an extension field:

ptkl validate-idl \
  --ref extension:ecommerce::order/premium \
  --field flagged_items \
  --value '[]'

Validate a platform function input:

ptkl validate-idl \
  --ref pfn:calculate_vat \
  --value '{"amount":100,"currency":"EUR"}'

Validate against an inline IDL file:

ptkl validate-idl \
  --idl-file ./my-idl.json \
  --field name \
  --value '"hello"'

my-idl.json:

{
  "version": "1.0",
  "types": {},
  "functions": [],
  "schemas": {
    "default": {
      "types": {},
      "fields": {
        "name": { "type": "string", "required": true }
      }
    }
  }
}

Output

Valid:

✓ valid

Invalid:

✗ invalid

  items[0].sku: expected string, got number
  items[0].quantity: required field missing

Request error (exit 1):

error: unknown ref "component:missing::ref"

CI Usage

Gate a deployment on IDL validity:

ptkl validate-idl \
  --ref component:ecommerce::order \
  --field items \
  --value-file ./fixtures/sample-order-items.json \
  --env live || exit 1

ptkl validate-idl