api.json symbolKey pack validation
Platform spec ADR
api.json symbolKey pack validation
Spec standingStandard
- Contracts and edge cases Registry client guarantees and failure modes.
- Design model Conceptual model for the Beskid pckg registry client (`beskid_pckg`).
- Examples Example `beskid pckg` invocations and configuration.
- FAQ and troubleshooting Common pckg client and registry issues.
- Flow and algorithm Pack, upload, and query flows for the pckg registry client.
- Verification and traceability Tests and traceability for the pckg client contract.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
| 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).
Context
Section titled “Context”Registry ingestion already validates graph navigation (parentId, refItemId, package-relative paths). With registry-backed symbolKey on v4 rows, pack-time validation must catch malformed or duplicated keys before artifacts reach the docs UI.
Decision
Section titled “Decision”validate_packed_api_doc must run validate_symbol_keys for schemaVersion >= 4 graph artifacts. When symbolKey is present on an item:
| Check | Rule |
|---|---|
| Non-empty | Reject blank strings |
| Package prefix | Must contain :: (package-prefixed canonical form) |
| Uniqueness | Reject duplicate symbolKey values across items |
| Leaf consistency | Lenient check: obvious mismatch between symbolKey leaf segment and qualifiedName leaf may reject when unambiguous |
Absence of symbolKey on any row remains valid (backward compatibility with pre-registry emitters).
Consequences
Section titled “Consequences”- Implementation:
compiler/crates/beskid_pckg/src/api_doc.rs - Operators re-pack with a current
beskid doc/ CLI to populate keys on new publishes; old.bpkfiles without keys still ingest.
Verification anchors
Section titled “Verification anchors”compiler/crates/beskid_pckg/src/api_doc.rsunit tests (accept distinct keys, reject duplicate / malformed, accept omitted field)