Spec

Spec is the schema system underneath every YAML file on the platform. Entities, workflows, routes, policies, datastores, bots, service configuration — all of it is a kind with a registered schema, and Spec is what defines, validates and generates from those schemas.

This matters more here than in most platforms, because on kis.ai the YAML is the application. A schema system that catches an error at authoring time is catching it before it becomes generated code, a deployment, and an incident.

One system, three interfaces

                    ┌──────────────────────────┐
                    │          Spec            │
                    │  kinds · schemas ·       │
                    │  validation · linting ·  │
                    │  scaffolding · codegen   │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
        `kis spec`        language server      platform services
        author, check     validate as you      validate their own
        and generate      type in the editor   config at load

The CLI and the IDE language server are thin interfaces over the same schema registry, and so are the services themselves. That is the property worth relying on: one definition of correct, so your editor, your CI and the running service agree about what a valid file is. There is no second schema to drift.

The kinds registry

128 registered kinds in two categories:

Category	Count	Examples
Definitions	107	Entity, Workflow, Route, Policy, Bot, Datastore, Access
Configuration	21	Service and block configuration

Every kind is versioned, so a schema can evolve without invalidating files written against the previous version.

kis spec list                 # every registered kind and version
kis spec schema --kind Entity # the schema for one kind

The authoring loop

kis spec new policy my-policy    # scaffold from a template
kis spec validate authz/         # check against the schema
kis spec lint authz/             # best practice beyond schema compliance

Validate and lint answer different questions. Validation asks whether the file is legal — required fields, types, enum values. Linting asks whether it is sensible — patterns that parse fine and cause trouble later. A file can validate and still fail lint, and that is usually the more interesting failure.

Generating from schemas

kis spec generate jsonschema --output ./schemas
kis spec generate jsonschema --kind Entity --output ./schemas
kis spec generate docs --output ./docs

jsonschema is the one to reach for when something outside the platform needs to understand your definitions — an editor that is not the supplied language server, a validation step in a pipeline you do not control, a form builder generating UI from a schema.

Where it shows up

Surface	Uses Spec for
IDE	Diagnostics, completion and hover, from the same schemas
Automate	Validating definitions in the pipeline before deploy
Every block	Validating its own configuration at load

If a service rejects your configuration at startup, it is rejecting it against the same schema kis spec validate would have used. Running validation in CI turns that startup failure into a build failure, which is a much cheaper place to find it.

Next

• CLI Reference — every kis spec command and flag
• IDE — the same validation, live in your editor