Skip to content

JSON schemas for apic.yaml, http-client.env.json and .apic/session.json #64

Closed

Description

@dataGriff

Why

apic.yaml has grown keys (env, dir, timeout, maxBodyBytes, auth.default, auth.allowExec, test.paths, and more coming: cookies, tls, proxy, retry, history). Nothing validates it or offers completion. Published JSON schemas give every editor completion and validation for free through the YAML and JSON language servers, and the VS Code extension registers them directly. Docs can render the config reference from the same source.

What

  • Generate docs/schemas/apic.schema.json, http-client.env.schema.json and session.schema.json from the Go structs (internal/project/project.go config types, internal/env) with task schemas, using struct tags for descriptions so the docs and the schema share one source. The MCP SDK already pulls in google/jsonschema-go; use it or invopop/jsonschema in a scripts/schemas program (not part of the binary).
  • Publish them on the docs site at stable URLs (https://datagriff.github.io/api-caller/schemas/apic.schema.json) and add them to SchemaStore (schemastore/schemastore PR) so editors pick them up by filename.
  • apic init writes # yaml-language-server: $schema=… as the first line of apic.yaml.
  • CI fails if the committed schemas are stale (task schemas && git diff --exit-code).
  • docs/cli.md "Configuration file" section is generated from the schema descriptions.

Where

scripts/schemas/main.go, Taskfile.yml, .github/workflows/ci.yml, docs/schemas/, mkdocs.yml (ensure the JSON files are copied), internal/cli/init.go, docs/cli.md.

Tests

The generator's output validates the example projects' files and the demo project; a negative test with a misspelled key fails validation.

Activity

  1. dataGriff commented on Sep 19, 2026

    @dataGriff
    OwnerAuthor

    Implemented on branch claude/apic-parity-learning-content-dwta3d in ffbfb5a: scripts/schemas (reflected from project.Config, descriptions required), docs/schemas/*.json, task schemas, a staleness test, and the yaml-language-server modeline from apic init and in the demo project. Not done here: the SchemaStore submission and generating the docs/cli.md config section from the schema, both small follow-ups.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions