Default pagination limit of 10 is unusually low — causes silent result truncation for typical workloads

[Sam-Bolling]

Finding

QueryParams.BuildFromRequest() hardcodes Limit: 10 as the default page size, causing silent result truncation for any workload with more than 10 resources of a given type.

Review Source: Live integration testing against the Go CSAPI server during OSHConnect-Python publisher fleet migration to the Go server.
Severity: P3-Minor
Category: API Design
Ownership: Upstream (SomethingCreativeStudios/connected-systems-go)

---

Problem Statement

The default pagination limit of 10 is significantly lower than other OGC API implementations. When a client requests a collection endpoint without an explicit ?limit=N parameter, only the first 10 resources are returned. The response includes rel=next pagination links, so it's technically conformant — but the low default means that most simple client integrations (which don't implement pagination following) silently miss data.

Affected code — internal/model/query_params/query_params.go — BuildFromRequest():

func (QueryParams) BuildFromRequest(r *http.Request) *QueryParams {
    params := &QueryParams{
        Limit:  10,   // ← Hardcoded default — unusually low
        Offset: 0,
    }

    if limit := r.URL.Query().Get("limit"); limit != "" {
        if val, err := strconv.Atoi(limit); err == nil {
            params.Limit = val
        }
    }
    // ...
}

Scenario:

# Server has 37 systems registered
GET /systems
# Expected: reasonable page of results (50-100 is typical for OGC APIs)
# Actual: only 10 systems returned, with pagination links to subsequent pages

# Same issue affects all resource types:
GET /datastreams     # 58 datastreams, only 10 returned
GET /deployments     # 58 deployments, only 10 returned
GET /observations    # hundreds of observations, only 10 returned

Impact: Combined with ?uid= being ignored (#7), this was particularly impactful during the publisher fleet migration. The find_by_uid() helper fetches a collection and iterates client-side to find a matching UID. With a default limit of 10, any resource beyond the first 10 was unfindable. Every publisher bootstrap script had to be updated with ?limit=1000:

# Workaround in bootstrap_helpers.py — explicit large limit
resp = session.get(f"{url}?limit=1000")

Comparison with other OGC API implementations:

Server	Default limit
SensorHub	100
pygeoapi	10
ldproxy	10
Go CSAPI	10

While 10 is not uncommon, the combination of limit=10 + missing ?uid= filter makes this server significantly harder to work with than others. Once #7 is fixed, this becomes a lower-priority cosmetic issue.

---

Ownership Verification

This code is pre-existing in the upstream SomethingCreativeStudios/connected-systems-go repository. The OS4CSAPI fork is currently synced with upstream (main branch is up to date).

Conclusion: This code is upstream.

Files to Modify

File	Action	Est. Lines	Purpose
internal/model/query_params/query_params.go	Modify	~3	Change Limit: 10 to Limit: 100 (or make configurable)

Proposed Solutions

Option A: Increase default to 100 (Recommended)

func (QueryParams) BuildFromRequest(r *http.Request) *QueryParams {
    params := &QueryParams{
        Limit:  100,  // Changed from 10 to 100
        Offset: 0,
    }
    // ...
}

Pros: Single-line change; matches SensorHub default; backward compatible (clients passing explicit ?limit=N are unaffected); greatly improves usability for typical workloads
Cons: Higher memory usage per request for servers with many resources; opinionated
Effort: Small | Risk: Low

Option B: Make default configurable via config.yaml

// internal/config/config.go
type APIConfig struct {
    BaseURL      string `yaml:"base_url"`
    DefaultLimit int    `yaml:"default_limit"` // NEW
}

// internal/model/query_params/query_params.go
// Pass config to BuildFromRequest, or use a package-level default
var DefaultLimit = 100

func (QueryParams) BuildFromRequest(r *http.Request) *QueryParams {
    params := &QueryParams{
        Limit:  DefaultLimit,
        Offset: 0,
    }
    // ...
}

Pros: Deployers can tune to their workload; allows different defaults for different deployment contexts
Cons: Larger diff; requires threading config through to query param construction; adds deployment complexity
Effort: Medium | Risk: Low

Scope — What NOT to Touch

• ❌ Do NOT modify files outside the "Files to Modify" table above
• ❌ Do NOT refactor adjacent code that isn't part of this finding
• ❌ Do NOT change the limit parsing logic (it correctly reads explicit ?limit=N)
• ❌ Do NOT add maximum limit enforcement — that's a separate concern
• ❌ Do NOT modify pagination link generation in BuildPagintationLinks()

Acceptance Criteria

• GET /systems (no ?limit=) returns up to 100 results (or configured default)
• GET /systems?limit=10 still returns exactly 10 results (explicit override works)
• Pagination links are correct for the new default
• Existing tests still pass (make test)

Dependencies

Blocked by: Nothing
Blocks: Nothing
Related: #7 — ?uid= filter ignored (fixing #7 reduces the impact of this issue significantly); #8 — Subdeployments hidden (more resources in listing increases importance of reasonable defaults); ogc-client-CSAPI_2#167 — Client library also lacks a default limit (companion client-side fix)

---

Operational Constraints

⚠️ MANDATORY: Before starting work on this issue, review docs/governance/AI_OPERATIONAL_CONSTRAINTS.md if available.

Key constraints:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Fix the finding, nothing more
• Minimal diffs: Prefer the smallest change that satisfies the acceptance criteria
• Ask when unclear: If intent is ambiguous, stop and ask for clarification
• Respect ownership: This code is upstream — coordinate with the maintainer if contributing back

Ownership-Specific Constraints

If Upstream:

• Track the issue for potential future contribution or discussion with the maintainer
• If the fix is trivial and clearly beneficial, note in the issue that it could be offered as a separate upstream PR

References

#	Document	What It Provides
1	internal/model/query_params/query_params.go — BuildFromRequest()	Root cause — hardcoded Limit: 10
2	OGC 23-001 §7.6 — Limit parameter	Spec says limit is optional with server-defined default
3	OSHConnect-Python publishers/bootstrap_helpers.py — find_by_uid()	Real-world workaround: hardcoded &limit=1000
4	ogc-client-CSAPI_2#167	Companion client-side issue

[Sam-Bolling]

Evaluation result — NOT a defect. cs-go matches the canonical CSAPI spec default exactly. Recommend close as wontfix or defer to upstream maintainer UX call.

Full write-up: docs/research/issue-evaluations/issue-009.md. Spec extracts and live transcripts under docs/research/evidence/issue-009/.

Spec authority — cs-go matches the spec literally

Direct fetch of opengeospatial/ogcapi-connected-systems/master/api/part1/openapi/parameters/limit.yaml:

schema:
  type: integer
  minimum: 1
  maximum: 10000
  default: 10

The canonical CSAPI spec explicitly sets default: 10. Unlike the parent OGC API Features spec, the CSAPI limit.yaml does not include the "values are examples and can be changed" escape clause — the value is stated literally. cs-go's Limit: 10 matches the spec exactly.

(For reference, the parent OGC API Features spec uses default: 100 with the escape clause. CSAPI authors removed both the value and the escape clause when forking it, which is plausibly deliberate.)

Two readings, both vindicate cs-go:

• Strict: CSAPI says 10 → cs-go matches → conformant.
• Permissive (via parent escape clause): any default permitted → cs-go's 10 is permitted; SensorHub's 100 is permitted → no defect either way.

The issue's own comparative table refutes its own framing

From the issue body:

Server	Default limit
SensorHub	100
pygeoapi	10
ldproxy	10
Go CSAPI	10

cs-go matches two of three comparison servers and the canonical CSAPI spec. "Unusually low" concentrates entirely on SensorHub. This is the same SensorHub-as-baseline framing pattern as #5, #6, and #7 — but here, the issue's own data contradicts its framing.

The compounding concern with #7 has evaporated

Issue body: "Once #7 is fixed, this becomes a lower-priority cosmetic issue."

#7 was research-resolved (no code change needed; spec parameter is id and accepts URIs — the publisher's ?limit=1000 workaround is unnecessary; one-character fix ?uid= → ?id=). The compounding concern is gone, and #9 sits at its self-described cosmetic level.

The publisher's actual root cause was no pagination handling in find_by_uid, which is a client-side defect. The server is conformant.

Live verification

Test	Request	Result
baseline	?limit=1000	numberMatched=13, features=13
T1	default GET /systems	numberMatched=13, features=10
T2	?limit=5	features=5

Default 10 confirmed; explicit override works.

What about raising to 100?

That's a deployer/maintainer UX preference, not a spec compliance call. Reasonable arguments either way:

• For raising: aligns with parent OGC API Features default; reduces footgun for naive clients; matches SensorHub for interop optics.
• Against: deviates from literal CSAPI spec; pygeoapi and ldproxy also use 10 (cs-go is not an outlier); the CSAPI authors removed both the value and the escape note from the parent spec, signaling deliberateness; modestly increases per-request memory.

I have no strong opinion. This belongs to the upstream SomethingCreativeStudios/connected-systems-go maintainer.

Recommendation

• Close Default pagination limit of 10 is unusually low — causes silent result truncation for typical workloads #9 as wontfix or defer to upstream maintainer UX discussion. No spec defect; cs-go matches the canonical CSAPI default.
• Do not change the cs-go default unilaterally. If raised, it should be a deliberate UX choice tracked separately, not as a "fix" against this issue.
• No follow-up issues filed against cs-go. There is nothing to fix.
• Publisher-side concern (pagination handling in find_by_uid) is a client defect — belongs in OSHConnect-Python, not here.

Severity adjustment

Filed P3-Minor with enhancement label. Recommend P4 / not-a-defect. The issue's own self-downgrade ("cosmetic once #7 is fixed") plus #7's research-resolution puts this below the threshold for a meaningful action item against cs-go.

Methodology notes

Patterns recurring through this evaluation queue, all confirmed again here:

1. SensorHub-as-baseline framing — Research: Strict schema validation — requiring ALL declared fields in observation results #5/Research: Cross-resource references — @link objects only vs. flat @id strings for interoperability #6/?uid= query parameter is silently ignored — server returns all resources unfiltered #7/Default pagination limit of 10 is unusually low — causes silent result truncation for typical workloads #9 all instances. Even when an issue's own comparative data shows cs-go matching the OGC ecosystem majority, the framing concentrates on the SensorHub deviation.
2. Self-downgrade clauses are often correct — "becomes cosmetic once ?uid= query parameter is silently ignored — server returns all resources unfiltered #7 is fixed" landed exactly right after ?uid= query parameter is silently ignored — server returns all resources unfiltered #7 was research-resolved. Worth checking dependency resolutions early in any deep evaluation.
3. Internal-evidence inconsistency — when an issue's own table contradicts its own framing, the framing is usually the load-bearing claim and the evidence is collateral. Cross-check before accepting.

[Sam-Bolling]

Closing as completed, verified against upstream 635547f.

Maintainer's call

This issue was not directly addressed in the maintainer's triage pass, but commit 635547f — "making the default limit for pagination configurable" — adopts Option B from this issue's body verbatim. So while the maintainer didn't comment here, the fix shipped.

What landed

The maintainer chose configurability over default-bumping — which is the spec-correct call. The CSAPI canonical spec limit.yaml explicitly defines default: 10, and unlike the parent OGC API Features spec, it does not include the "values are examples and can be changed" escape clause. Raising the default to 100 (Option A) would have been a deviation; making it configurable while keeping the spec-default in place is the right shape.

The change touches 27 files — every per-resource handler and *_query_params.go builder now threads a defaultLimit int parameter through:

// internal/model/query_params/query_params.go (after)
func (QueryParams) BuildFromRequest(r *http.Request, defaultLimit int) *QueryParams {
    params := &QueryParams{
        Limit:  defaultLimit,   // was: 10 (hardcoded)
        Offset: 0,
    }
    // ...
}

Backed by a new config field with a spec-conformant default:

// internal/config/config.go (after)
type APIConfig struct {
    BaseURL      string `mapstructure:"base_url"`
    Title        string `mapstructure:"title"`
    Description  string `mapstructure:"description"`
    Version      string `mapstructure:"version"`
    DefaultLimit int    `mapstructure:"default_limit"`   // new
}

// in Load():
viper.SetDefault("api.default_limit", 10)   // spec-conformant default preserved

Deployers who want SensorHub-parity (100) or a workload-tuned value just set api.default_limit in config.yaml (or API_DEFAULT_LIMIT env var via the existing viper env-key replacer).

How this maps to the body's options

Body option	Status
Option A: bump default to 100	Not adopted. Spec-correct call — CSAPI literal is 10.
Option B: make configurable via config.yaml	Adopted in 635547f exactly as proposed.

Acceptance criteria from the body:

• GET /systems (no ?limit=) returns up to configured-default results (default still 10, deployer-overridable).
• GET /systems?limit=N still honors explicit override (BuildFromRequest parses ?limit= after seeding from defaultLimit).
• Pagination links unchanged.
• Existing tests still pass (per upstream CI on 635547f).

Eval-related context

Our evaluation flagged that the literal-spec default of 10 is in fact correct (cs-go matches pygeoapi and ldproxy; only SensorHub is the outlier at 100), and recommended against filing this as a defect. The maintainer's choice to ship Option B — keeping the default at 10 while providing the configurability knob — is precisely the resolution we'd have advocated for had we filed this upstream.

The publisher-side root cause (find_by_uid not iterating pagination) referenced in the body is a client-side defect tracked separately on ogc-client-CSAPI_2#167 and the Python publisher repo. Both can now bootstrap with ?limit=<deployer-configured> if higher pagination is desired without per-request override, or just iterate rel=next properly.

Cross-references

• Original evaluation: docs/research/issue-evaluations/issue-009.md.
• Upstream commit: SomethingCreativeStudios/connected-systems-go@635547f.
• Related: ?uid= query parameter is silently ignored — server returns all resources unfiltered #7 (research-resolved — ?id= accepts URIs), companion client-side ogc-client-CSAPI_2#167.

Closing as completed.