Sphereon OpenAPI specifications

Single source of truth for every Sphereon-owned REST API specification across the three product layers:

• IDK — Identity Development Kit (open-core SDK). Specs under idk/.
• EDK — Enterprise Development Kit. Specs under edk/.
• VDX — Verifiable Data Exchange platform. Specs under vdx/.

Products are inclusive: EDK consumes IDK, VDX consumes EDK + IDK. A VDX deployment can expose every IDK + EDK + VDX spec; an EDK deployment exposes IDK + EDK; IDK exposes IDK only.

Third-party reference specs (vendor APIs we integrate but do not own) live under external/ and are excluded from aggregation, linting, and release tags.

Layout

shared/   common-components.yml          canonical shared components (errors, pagination, security, tenant headers)
idk/      <domain>-openapi.yml + a synced common-components.yml + leaf component bundles
edk/      <domain>-openapi.yml + a synced common-components.yml
vdx/      <domain>-openapi.yml + a synced common-components.yml + domain component bundles
external/ vendor reference specs (not aggregated)

Every spec is flat within its product directory. All cross-file $refs are same-directory (./common-components.yml#/..., ./<bundle>.yml#/...). The canonical shared/common-components.yml is the only edited copy; the per-product common-components.yml copies are generated by sync-shared and must not be hand-edited.

Why flat + synced copies, not $ref into shared/: the OpenAPI generator used by the consuming Kotlin Multiplatform builds resolves cross-subdirectory parameter $refs unreliably, and common-components.yml is referenced as parameters on nearly every path. Keeping every $ref same-directory sidesteps that entirely.

Consuming this repo

Each product repository includes this repo as a git submodule at openapi/ and pins it by commit. After cloning a product repo:

git submodule update --init --recursive

A product's build resolves the nearest openapi/ checkout and reads specs in place — there is no copy-into-module step. When a product picks up new specs, bump its submodule pin; all three product pins (IDK / EDK / VDX) must be advanced in lockstep to the same commit.

Versioning

This repo defines its own release-tag namespace (v0.25, v0.26, …), independent of any product repository's tags. A tag is a release coordinate; an individual spec's info.version is independent of it. Documentation snapshots and product builds reference these tags.

Files

• shared/common-components.yml — the canonical shared components.
• sync-shared.js — copies shared/common-components.yml into idk/ edk/ vdx/; run after any edit to the canonical file. CI re-runs it and fails on drift.
• manifest-catalog.json — maps each spec's owning REST/API module to its division/domain/path; drives runtime spec selection (a service serves only specs whose owning module is on its classpath) and documentation aggregation.
• .redocly.yaml — lint configuration. npx @redocly/cli lint must pass; the no-unresolved-refs gate proves every same-directory $ref resolves.
• INVENTORY.md — convention-divergence report (pagination, error model, base-path versioning) with a prioritized normalization fix-list. Report only; specs are not edited to match yet.