Validate a Packet

Validation is the foundation of UKS interoperability — the CLI, TypeScript SDK, and Python SDK all bundle the same normative schema and agree on results.

Locally (CLI)

uks validate my-packet.uks.json
# ✓ my-packet.uks.json
#   conformance level: L1 ✓

A packet that declares a level it doesn't satisfy fails — e.g. an L3 packet missing actions. See Conformance Levels.

In code

import { validate } from '@uks/sdk';
const { valid, errors } = validate(packet);

from uks_sdk import validate
result = validate(packet_dict)

In CI (GitHub Action)

Gate every .uks.json change on a valid schema with the composite action:

# .github/workflows/uks.yml
name: UKS
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: uks/uks-action@v1   # annotates failures + writes a job summary

The action validates changed packets and annotates failures inline on the PR.

Common failures

Symptom	Fix
topic rejected	topic is an object { "title": "…" }, not a string
missing created_at	required at the top level (ISO 8601 datetime)
source_type rejected	use a valid SourceType or an x--prefixed value
unknown top-level key	the schema is strict — put extra data under _extensions

→ Next: Publish to the registry · JSON Schema