## Problem The first two modular features to ship chose opposite models. Artifact Registry hand-authors OpenAPI 3.1 and verifies it with redocly plus `kin-openapi`. Orbit's surface is Grape in the monolith and, if it gets a spec at all, it gets a generated one. Both were reasonable local decisions because no house model exists. This is not a stylistic preference. The two models need opposite tooling, and the choice determines the value of three other epics: - Generated means a generator per language per framework. The spec cannot drift, but it silently omits whatever the generator does not understand — exactly the `hidden true` failure that hid Orbit's entire API surface. - Hand-authored means a linter plus contract tests. The spec is authoritative and drift is caught rather than prevented. - If specs are generated, contract testing is close to tautological: a spec cannot disagree with the code it was derived from. Contract testing earns its cost only under the hand-authored model. - The scaffolding convention cannot be written before this is settled, and the completeness check in the breaking-change epic only makes sense under one of the two. ### Multi-language is what makes this urgent rather than academic LabBench's schema names four handler variants — `rs`, `go`, `rb`, `py` — but `validate_runtime` rejects Ruby and Python, and LB-D5 confirms only Rust and Go are supported today. So the estate is three buckets: two supported bench runtimes, two more named in the schema for later, and Ruby-in-the-monolith as a separate case that is not a bench service at all. That asymmetry falls almost entirely on one branch: - **Generated from code** needs a generator per language per HTTP framework. GitLab has exactly one, `gitlab-grape-openapi`, and it serves the monolith. Zero exist for any bench runtime. The one service that could use the existing generator is Orbit — whose API is Grape *in the monolith* — so the precedent for "generated" comes from the case least representative of a modular feature. - **Hand-authored** is language-agnostic where it is linted (redocly reads YAML regardless of runtime) but not where it is verified: contract-testing libraries are per-language. - **Derived from protobuf** is the only branch that is language-neutral by construction. This does not pick a winner — that is the ADR's job, with LabBench in the room. It settles the weighting: generated-from-code is the weakest branch on cost grounds alone, independent of anyone's preference. ## Goal ### First iteration 1. An ADR, agreed with the LabBench team, stating GitLab's API definition model for modular features and the reason. Precedent exists: LabKit already mandates a protobuf schema for all module configuration, so this is a missing piece of an established pattern rather than a new category of work. 2. An explicit answer on whether LabBench's `inbound.proto` grows request and response schemas, since that is what decides whether the language-neutral branch is available. 3. A stated position for each of the two shipped services: conform, or migrate by a date. 4. Supporting both paths is a permitted outcome, but only if the cost of maintaining both is written down and accepted rather than arrived at by default. ### Long-term outcome - One model, so tooling investment compounds instead of forking per language. - LabBench's transport-layer abstraction derives HTTP surface and OpenAPI spec from the same definitions, rather than the API having two sources of truth. - The breaking-change and contract-testing epics can be scoped against a known model. ## Technical considerations - The discriminating question is whether `inbound.proto` grows schemas. **If it does, proto-derived is available and language-neutral. If it does not, hand-authored is the only language-neutral option left.** - `config/buf.yaml` in the bench repo is `version: v1` with lint-only rules. That is a configuration gap, not a capability gap — buf does codegen once a plugin is configured. - Generated model, for reference: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi_v3.yaml - Hand-authored model, for reference: https://gitlab.com/gitlab-org/ops/artifact-registry/-/tree/main/api/openapi ## Links **Contacts**: Elliot Forbes (Theseus and LabBench alignment). LabBench framework owner to confirm — this epic cannot start without them. LabKit module configuration convention: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/labkit_configuration/ LabBench assembly runtime decision (`LB-D5`): https://gitlab.com/gitlab-org/lab-bench/bench/-/blob/main/docs/decisions/LB-D5-assembly-runtime.md Downstream: https://gitlab.com/groups/gitlab-org/quality/-/work_items/432 and https://gitlab.com/groups/gitlab-org/quality/-/work_items/434 ## After ADR 008 [ADR 008](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/theseus_platform_vision/decisions/008_openapi_specification_for_modular_http_apis/) is merged (status Proposed). It settles the model question: a quality bar every spec must pass, with the method left to each team. The Problem and Goal sections above are kept as the original framing. | First-iteration goal | Issue | Status | | --- | --- | --- | | 1. ADR agreed with the Lab Bench team | [624041](https://gitlab.com/gitlab-org/gitlab/-/work_items/624041) | ADR merged, issue closed. Lab Bench's agreement is not yet recorded: see the new issue "Record Lab Bench's agreement to ADR 008" (https://gitlab.com/gitlab-org/gitlab/-/work_items/633600). | | 2. Answer on whether `inbound.proto` grows request and response schemas | [624042](https://gitlab.com/gitlab-org/gitlab/-/work_items/624042) | Open, unassigned. | | 3. A position for each shipped service | [624045](https://gitlab.com/gitlab-org/gitlab/-/work_items/624045) | Open. Artifact Registry's position is recorded in ADR 008 point 7. Orbit's is open. | | 4. Cost of supporting both paths | Superseded | ADR 008 point 4 makes the method the team's choice, so there are no two paths to cost. [624044](https://gitlab.com/gitlab-org/gitlab/-/work_items/624044) was repurposed from this goal. | | 5. The quality bar runs (new, below) | [624044](https://gitlab.com/gitlab-org/gitlab/-/work_items/624044) | Open. See below. | **Goal 5.** The quality bar runs: a versioned ruleset and a CI component that lints every modular feature's spec, with Artifact Registry as the first adopter. [624044](https://gitlab.com/gitlab-org/gitlab/-/work_items/624044) has four child tasks: - Build the OpenAPI lint CI component in common-ci-tasks (https://gitlab.com/gitlab-org/gitlab/-/work_items/633601) - Gate release-platform publishing on the OpenAPI lint (https://gitlab.com/gitlab-org/gitlab/-/work_items/633602) - Add a Renovate rule that bumps the OpenAPI ruleset pin (https://gitlab.com/gitlab-org/gitlab/-/work_items/633603) - Move Artifact Registry to the OpenAPI lint component (https://gitlab.com/gitlab-org/gitlab/-/work_items/633604) Goals 1 and 6 of 624044 are met: the ruleset is released as v5.37.0, and the template config ([MR 1069](https://gitlab.com/gitlab-com/gl-infra/common-template-copier/-/merge_requests/1069)) is released in common-template-copier v1.85.0. [624046](https://gitlab.com/gitlab-org/gitlab/-/work_items/624046) re-scopes epics [432](https://gitlab.com/groups/gitlab-org/quality/-/work_items/432) and [434](https://gitlab.com/groups/gitlab-org/quality/-/work_items/434) against ADR 008. Due date: 2026-10-23, unchanged. <!-- STATUS NOTE START --> ## Status 2026-10-08 :tada: **achievements**: - Initial ADR was merged: https://gitlab.com/gitlab-org/gitlab/-/work_items/624041 - Follow-up with quality bar for OpenAPI specs was also merged: https://gitlab.com/gitlab-org/gitlab/-/work_items/624043 :issue-blocked: **blockers**: :arrow_forward: **next**: - Publish the ruleset as a versioned file, plus the CI component that runs it. (https://gitlab.com/gitlab-org/gitlab/-/work_items/624044) - Pick up the remaining issues. Currently on track, next week will be pivotal to ensure completion before end of October. _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/465#note_3974266361_ <!-- STATUS NOTE END -->