forgejo-api-contract

The shared API contract for Forgejo clients built at Raster & State. One pinned spec, one operational policy, consumed by both Fjord (Swift / iOS) and fj (Rust CLI).

This repo is the single source of truth for:

• which Forgejo API version the clients target,
• the OpenAPI 3.0 document they generate code from,
• the operational policy (retry budget, body cap, redaction list, version floor) the clients are expected to honor in lockstep.

It contains no compiled code. Each consumer vendors this repo as a git submodule and runs its own language-specific code generation.

What's here

Path	Role
swagger.v1.json	Upstream Forgejo spec, vendored at a pinned version (Forgejo 17.0.0, Gitea 1.22-compatible).
openapi.v1.yaml	Raw OpenAPI 3.0 conversion of the swagger via swagger2openapi. Committed so consumers don't need Node to build.
openapi.yaml	The patched spec: openapi.v1.yaml plus policy.yaml's requiredOverrides: and requestBodyOverrides: applied. This is the document consumers generate from.
policy.yaml	Operational policy shared by every consumer: version floor, retry table, body cap, redaction allowlist, optionality overrides, required-field overrides.
patches/	Reserved for future Redocly-style overlays. Empty today; the simple required: rewrites are driven from policy.yaml.
scripts/apply-required-overrides.sh	Reads policy.yaml's requiredOverrides:, applies them to openapi.v1.yaml. Validates each schema and field exists before writing.
scripts/apply-requestbody-overrides.sh	Reads policy.yaml's requestBodyOverrides:, marks each named operation's request body required: true. Runs after the required-field pass and writes openapi.yaml.
scripts/generate-policy-swift.sh	Consumer-side convenience: renders policy.yaml into a Swift constants file. Invoked by Fjord with its own output path. A generate-policy-rs.sh will join it when fj adopts the contract.
Makefile	Contract-level targets: fetch, convert, patch, check.
OPERATIONS.md	Re-vendor cadence, patch hygiene, ownership, breaking-change protocol.
GAPS.md	Live-verified divergences between the vendored spec and real deployed servers (version skew, undocumented semantics, missing webhook surfaces).

Contract-level commands

make help          # list targets
make fetch         # re-download swagger.v1.json from rasterhub.com
make convert       # rerun swagger2openapi (writes openapi.v1.yaml)
make patch         # apply policy.yaml overrides (writes openapi.yaml)
make regenerate    # convert + patch
make check         # fail if either committed spec drifts (CI gate)

make check is this repo's CI gate. Language-specific code generation (Swift types, Rust constants) is each consumer's responsibility and runs in the consumer's own CI.

How consumers use this

Each consumer adds this repo as a git submodule, points its code generator at openapi.yaml, and runs its own policy.yaml-to-constants step:

• Fjord vendors the submodule at Fjord/Tools/forgejo-contract/, runs swift-openapi-generator against openapi.yaml, and runs scripts/generate-policy-swift.sh to produce ForgejoPolicy constants.
• fj (planned) will vendor the submodule, generate Rust models, and run a generate-policy-rs.sh for the matching policy.rs constants.

Prerequisites

• node 24.x (for swagger2openapi, invoked via npx --yes).
• yq, Mike Farah's Go implementation (not the Python yq wrapper). The patching script refuses to run on the wrong flavor.
• make, bash, curl.

Re-vendoring

See OPERATIONS.md for the cadence, the patch-hygiene rules, and the major-version bump protocol.

versionFloor vs spec version

policy.yaml's versionFloor.semver is the minimum Forgejo major version clients agree to talk to (7.0.0, set by fj's pre-existing version-warning baseline). It is independent of the spec version vendored in swagger.v1.json (Forgejo 17.0.0 today); the spec floats forward, the floor changes only when both clients agree to drop compatibility with older servers.