Skip to content

fix(cli): normalize JSON schema for diagnostics and payload fields #96

@danielewood

Description

@danielewood

Summary

JSON outputs diverge in naming and encoding for similar concepts, forcing clients to special‑case each command.

Underlying problems

  1. Diagnostics key name differs: verify uses diagnoses, connect uses diagnostics.
  2. Diagnostics status enum differs: verify uses pass/fail/warn, connect uses warn/error.
  3. OCSP verbose JSON uses cert_subject/cert_issuer instead of the standard subject/issuer used elsewhere.
  4. PEM payload fields differ: bundle uses chain_pem for text output, while convert uses data.
  5. data encoding semantics differ: bundle base64‑encodes binary output in data, while convert uses raw PEM in data for text output.

Why this matters

Downstream tooling has to branch on command‑specific JSON shapes and encodings, which breaks the CLI‑wide JSON contract and makes automation brittle.

Evidence

  • diagnoses vs diagnostics: internal/verify.go:71, cmd/certkit/connect.go:70.
  • Diagnostics status enum: internal/verify.go:294, connect.go:24.
  • OCSP verbose fields: cmd/certkit/ocsp.go:43-47.
  • chain_pem vs data: cmd/certkit/bundle.go:145-165, cmd/certkit/convert.go:184-189.
  • Binary vs text encoding in data: cmd/certkit/bundle.go:141-146, cmd/certkit/convert.go:165-168.

Acceptance criteria

  • A single canonical JSON schema is defined for diagnostics and payload fields.
  • All commands use the same field names and encoding conventions.
  • Documentation reflects the canonical schema.
  • Tests cover JSON shape consistency across commands.

Suggested approach

  • Introduce shared JSON structs or helpers for common fields (diagnostics, certificate context, payload data).
  • If multiple encodings are needed, use explicit fields (e.g., data_pem, data_base64).

Dedupe notes

Checked open issues #88#92 and gh search issues "repo:sensiblebit/certkit" with relevant keywords; no overlapping issue found. Classified as new.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workinggoPull requests that update go code

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions