name: schematic-define description: Expert knowledge for defining REST and WebSocket APIs with schematic-define. Use when creating or editing RestApi/Endpoint models, auth and env mappings, request or response shapes, and OpenAPI extension behavior that drives generated clients.

schematic-define

Use this skill when working in schematic/define or when updating docs/tests that describe schematic-define behavior.

Scope

schematic-define is the definition layer for Schematic:

• RestApi, Endpoint, RestMethod
• AuthStrategy, ApiKeyLocation, UpdateStrategy
• ApiRequest, ApiResponse, FormField, Schema
• Headers, EnvMapping, EnvList, SensitiveString
• OpenAPI vendor extension models (x-schematic)

Code generation and runtime clients live in schematic-gen and schematic-schema, but this crate defines the contracts they consume.

High-Signal Rules

1) Response Type Selection Is Runtime-Critical

Pick the right ApiResponse, because generated method shape depends on it:

If an endpoint returns bytes/text but is modeled as JSON, generated clients call the wrong response parser.

2) Auth Strategies Include Query/Cookie API Keys

AuthStrategy is broader than bearer/header-only patterns:

• BearerToken { header: Option<String> }
• ApiKey { header: String }
• ApiKeyParam { location: ApiKeyLocation, name: String }
• Basic
• None

ApiKeyLocation supports:

• Query
• Cookie

3) Public Enums Are #[non_exhaustive]

Match statements must include a wildcard arm for forward compatibility.

Key enums: AuthStrategy, ApiKeyLocation, UpdateStrategy, ApiRequest, FormFieldKind, ApiResponse, RestMethod.

4) Env Mapping Field Names

Use current EnvMapping names:

• bearer_token
• basic_user
• basic_pass
• api_key

Do not document or introduce legacy basic_auth object shapes.

5) Basic Auth Source of Truth

For AuthStrategy::Basic:

• Username: env_username (or env_mapping.basic_user)
• Password: env_auth[0] (or env_mapping.basic_pass)

Generated-Client Contracts To Keep In Sync

When updating docs or examples that touch generated clients:

• OpenAI::new() returns Self (no ?)
• Variant APIs are:
  • variant() builder
  • variant_with(base_url, env_auth, strategy)
  • variant_with_headers(headers)
• Headers::use_bearer_token() / use_basic_auth() bypass env credential lookup when auth is already set programmatically.

Canonical pattern:

use schematic_define::Headers;
use schematic_schema::openai::{ListModelsRequest, ListModelsResponse, OpenAI};

let client = OpenAI::new()
    .variant()
    .headers_builder(Headers::default().use_bearer_token("token"))
    .build();

let _models: ListModelsResponse = client
    .request(ListModelsRequest::default())
    .await?;

OpenAPI Extension Reality (Current Exporter)

Schematic defines three extension structs, but exporter emission is currently:

• emitted: document-level x-schematic
• emitted: operation-level x-schematic
• defined but not emitted: schema-level x-schematic (SchematicSchemaExtension)

Document-level extension carries API-wide config (module_path, request_suffix, env_mapping, headers). Operation-level extension carries endpoint config (request, response, headers).

Current serialized response shape uses enum tagging, e.g.:

x-schematic:
  response:
    Json:
      type_name: ListModelsResponse
      module_path: null

Text/Binary/Empty appear as scalar enum values.

Schematic Definitions Facts That Frequently Drift

Keep these aligned when docs/examples mention built-in APIs:

• LM Studio: 6 endpoints, bearer auth via LM_API_TOKEN
• EMQX Basic: 36 endpoints, basic auth via EMQX_API_KEY + EMQX_API_SECRET
• EMQX Bearer: 38 endpoints, bearer auth via EMQX_TOKEN
• GitHub: 14 endpoints, bearer auth via GITHUB_TOKEN or GH_TOKEN
• Gitea: 14 endpoints, API key auth via GITEA_TOKEN (uses token prefix, not Bearer)

Update Workflow

1. Edit definition types/docs in schematic/define.
2. Verify behavior in generator/runtime contracts when the change affects response/auth/env mapping.
3. Update related docs in:
   • schematic/README.md
   • schematic/define/README.md
   • schematic/definitions/README.md
   • schematic/docs/headers/README.md
   • schematic/docs/io/openapi-extensions.md
   • schematic/gen/README.md
   • schematic/schema/README.md
4. Re-run focused tests before broad checks.

Verification Commands

Focused response-method generation coverage:

cargo test -p schematic-gen --test e2e_generation binary_response_generates_request_bytes_method
cargo test -p schematic-gen --test e2e_generation text_response_generates_request_text_method
cargo test -p schematic-gen --test e2e_generation empty_response_generates_request_empty_method

Definitions/auth sanity checks:

cargo test -p schematic-definitions api_uses_bearer_token_auth
cargo test -p schematic-definitions basic_api_has_expected_endpoint_count
cargo test -p schematic-definitions bearer_api_has_more_endpoints

End-to-end regeneration safety pass:

cargo test -p schematic-gen
just -f schematic/justfile generate
cargo check -p schematic-schema

Remaining Testing Gap

Current tests validate generation logic, emitted methods, and compile-time structure. They do not validate live provider HTTP integration behavior.

Reference Map

Read these as needed:

• schematic/define/README.md (authoritative type-level behavior)
• schematic/docs/headers/README.md (programmatic auth patterns)
• schematic/docs/io/openapi-extensions.md (extension schema and examples)
• schematic/gen/README.md (generated method/contracts)
• schematic/schema/README.md (runtime client usage examples)
• schematic/definitions/README.md (built-in API catalog)

For legacy detailed notes that may still be useful, see:

• .claude/skills/schematic/define.md