CBG-5715: fix fields documented as string that are not strings

[torcolvin]

CBG-5715

Split out of #8589 — stack 6/9, based on #8653.

Each of these is documented as string but is unmarshalled into a bool or an integer, so the documented request bodies would be rejected and the documented response types don't match what is emitted:

• include_doc and offline query params are read with getBoolQuery (rest/admin_api.go:1632, rest/oidc_api.go:118)
• _changes POST body (per readChangesOptionsFromJSON, rest/changes_api.go:599): limit is int, heartbeat/timeout are *uint64, active_only/include_docs are bool, and doc_ids is a real []string here — unlike the query parameter, which is a serialized string
• event_handlers.max_processes is a uint (rest/config.go:218)
• OIDC-token.expires_in is an int TTL (rest/oidc_api.go:67)
• Compact-status.docs_purged, marked_attachments and purged_attachments are int64 counters

revocations is also dropped from the _changes POST body. Neither readChangesOptionsFromJSON nor updateChangesOptionsFromQuery reads it, so a POST cannot set it at all — not via the body and not via the query string. It is only honoured on GET (rest/changes_api.go:190). @bbrks spotted this on #8589 and suspected an oversight in the handler; removing the property documents current behaviour, and the handler gap is worth its own ticket if revocations should work on POST.

wait_for_process is left as a string: it really is parsed as a duration string, not a number (rest/config.go:219).

Covers the three @factory-droid comments on #8589 about the POST /_changes request bodies and OIDC-token.expires_in.

Pre-review checklist

• Logging sensitive data? N/A — docs only
• Updated relevant information in the API specifications in docs/api

🤖 Generated with Claude Code

[factory-droid]

Droid finished @torcolvin's task —— View job

---

The schema-type fixes look consistent with the Go implementation. The remaining gap is that POST /_changes request-body schemas still omit supported options (since in both admin and public, and version_type in public), which can mislead users and break generated clients.

[github-actions]

Redocly previews

• Admin API
• Public API
• Metric API
• Diagnostic API

[Copilot]

Pull request overview

This PR updates the OpenAPI specifications under docs/api/ to align documented request/response types with how Sync Gateway actually parses and emits values (primarily correcting fields previously documented as string that are in practice booleans or integers).

Changes:

• Fix _changes POST body schema types (e.g., limit, since, active_only, doc_ids, heartbeat, timeout) and adjust documented fields to match handler behavior.
• Correct component schema field types for OIDC token responses, event handler configuration, and compaction status counters.
• Update shared query-parameter component schemas (include_doc, offline) from string to boolean.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
docs/api/paths/public/keyspace-_changes.yaml	Updates the public _changes endpoint schema (notably POST body field types and added fields).
docs/api/paths/admin/keyspace-_changes.yaml	Updates the admin _changes endpoint POST body schema field types to match server parsing.
docs/api/components/schemas.yaml	Fixes component schema field types (OIDC token TTL, event handler concurrency, compaction status counters).
docs/api/components/parameters.yaml	Corrects shared query parameter schemas to boolean where handlers parse booleans.

Suppressed comments (4)

docs/api/components/schemas.yaml:2180

• marked_attachments is emitted as an int64 counter (see db/background_mgr_attachment_compaction.go), so the schema should use format: int64 (and it’s a count, so it should be non-negative).

      type: integer

docs/api/components/schemas.yaml:2186

• purged_attachments is emitted as an int64 counter (see db/background_mgr_attachment_compaction.go), so the schema should use format: int64 (and it’s a count, so it should be non-negative).

      type: integer

docs/api/paths/public/keyspace-_changes.yaml:182

• timeout in the POST body is clamped/validated server-side (default 300000ms, max 900000ms). Adding these constraints to the schema helps prevent documented request bodies that the server will reject.

              type: integer

docs/api/paths/admin/keyspace-_changes.yaml:195

• timeout in the POST body is clamped/validated server-side (default 300000ms, max 900000ms). Adding these constraints to the schema helps prevent documented request bodies that the server will reject.

              type: integer

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.