CBG-5715: document whole-number fields as integer rather than number

[torcolvin]

CBG-5715

Split out of #8589 — stack 4/9, based on #8651.

Sequence numbers, counters, byte/millisecond/second sizes, timeouts and thresholds are all whole numbers in Go, but were declared type: number, which documents them as accepting fractional values. Retype the 45 affected schemas to integer, leaving the genuinely fractional ones (compact_interval_days, the CPU utilization percentages, which carry format: float) as number.

Two related type fixes:

• Status.runtime.cgroup_memory_limit_bytes used format: uint64, which is not an OpenAPI format. Use the standard int64 plus minimum: 0, matching its sibling go_memlimit_bytes. (Raised by @factory-droid on CBG-5715 docs(api): fix OpenAPI errors #8589.)
• The _sync diagnostic endpoint's user xattr value accepts any JSON number, not just integers, so widen that oneOf branch to number.

Every one of the 45 was traced to its Go declaration: uint32 (bucket_op_timeout_ms, old_rev_expiry_seconds, slow_query_warning_threshold, all five warning_thresholds, rev_max_age_seconds, rev_cache_size, NumIndexPartitions), uint16 (import_partitions), uint/uint64 (max_connections, max_file_descriptors, update_seq, purge_seq, disk_format_version, _revisions.start, Status.seq), int (total_rows, dcp_read_buffer, kv_buffer, expires_in), []uint (enabled_events).

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 integer-vs-number doc updates are mostly correct, but _changes sequence IDs can be either a JSON integer or a string, and the shared limit parameter docs currently misstate limit=0 behavior. Aligning these two spots would prevent client-side deserialization bugs and unexpected unbounded queries.

[github-actions]

Redocly previews

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

[Copilot]

Pull request overview

This docs-only PR aligns OpenAPI numeric schemas with their Go types.

Changes:

• Retypes whole-number fields as integer.
• Corrects cgroup memory format and diagnostic XATTR numeric handling.
• Clarifies related response and parameter schemas.

The revs_limit schema still uses minimum: 0, though the API requires a minimum of 1.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Summary
docs/api/paths/public/keyspace-docid-attach.yaml	Updates attachment length types.
docs/api/paths/public/db-.yaml	Updates database numeric fields.
docs/api/paths/diagnostic/keyspace-sync.yaml	Adjusts XATTR and expiry types.
docs/api/paths/admin/keyspace-docid-attach.yaml	Updates attachment length types.
docs/api/paths/admin/db-.yaml	Updates database numeric fields.
docs/api/components/schemas.yaml	Retypes shared schemas and runtime fields.
docs/api/components/responses.yaml	Retypes _all_docs response fields.
docs/api/components/parameters.yaml	Updates the limit parameter schema.

Suppressed comments (1)

docs/api/components/schemas.yaml:463

• The related OIDC-token schema below still declares expires_in as string (line 475), but the documented mock token endpoint serializes OidcTokenResponse.ExpiresIn as an int (rest/oidc_test_provider.go:245-250). This leaves one response schema inconsistent with the whole-number fix; change that branch to type: integer as well.

    expires_in:
      description: The time until the id_token expires (TTL).
      type: integer

---

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