api.json contract

Platform spec feature

api.json contract

Back to CLI ◎ Open in platform map

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-api-json-primary-contract api.json primary Accepted

   api.json primary

   Context

   UI contract.

   Decision

   api.json is primary structured docs contract.

   Consequences

   Templates exempt.

   Verification anchors

   doc emission; pckg UI.

   Open full ADR page

2. 0002-hub-authority Hub authority Accepted

   Hub authority

   Context

   Informal notes.

   Decision

   Hub and ADRs supersede crate notes.

   Consequences

   Spec leads code.

   Verification anchors

   content verify.

   Open full ADR page

Articles

• Design model Schema v4 for api.json — full resolved API surface, signatures, and navigable type references. article Standard
• Registry API reference UI Normative layout and navigation for pckg package API documentation driven by api.json. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 4 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  CLI

  Parent area

• Feature
  Command surface

  Sibling CLI contract

• Feature
  Documentation comments

  Optional prose layered on compiler-derived API rows

What this feature specifies

api.json is the primary structured contract for registry API documentation. The Beskid CLI emits it under .beskid/docs/ during beskid doc and beskid pckg pack for packageKind: library artifacts. Consumers (pckg, IDE tooling, custom renderers) must treat the JSON graph as authoritative for navigation, member hierarchy, and type linking—not parallel ad-hoc grouping outside the schema.

packageKind: template packages must not require or display api.json on the registry. See Template packages and Package kinds.

Implementation anchors

• Schema emission: compiler/crates/beskid_analysis/src/doc/ (api.json snapshot and signatures)
• CLI: compiler/crates/beskid_cli/src/commands/doc.rs
• Registry ingestion: compiler/crates/beskid_pckg/src/api_doc.rs and pckg StructuredApiDocDtos
• UI: pckg PackageDocs components driven by deserialized api.json

Articles

Decisions

No open decisions. D-TOOL-CLI-0001 (api.json primary contract), 0002 (hub authority)—see adr/ and the ADRs tab.

Normative articles

• api.json primaryapi.json primary
• Design modelSchema v4 for api.json — full resolved API surface, signatures, and navigable type references.
• Registry API reference UINormative layout and navigation for pckg package API documentation driven by api.json.