`?uid=` query parameter is silently ignored — server returns all resources unfiltered

[Sam-Bolling]

Finding

QueryParams.BuildFromRequest() parses the id query parameter but never reads uid, so all collection list endpoints silently ignore ?uid= and return unfiltered results.

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

---

Problem Statement

The OGC 23-001 specification (§7.3) defines uid as a standard query parameter for filtering resources by their globally unique identifier. The Go server's base QueryParams struct parses id and maps it to both id and unique_identifier columns in the database, but it never reads the uid query parameter at all.

Affected code — internal/model/query_params/query_params.go:

// QueryParams.BuildFromRequest() — only reads "id", never "uid"
func (QueryParams) BuildFromRequest(r *http.Request) *QueryParams {
    params := &QueryParams{
        Limit:  10,
        Offset: 0,
    }
    // ...
    if ids := r.URL.Query().Get("id"); ids != "" {
        params.IDs = strings.Split(ids, ",")
    }
    // ← No handling of r.URL.Query().Get("uid")
    return params
}

Affected code — internal/repository/deployment_repository.go (representative of all repos):

func (r *DeploymentRepository) applyFilters(query *gorm.DB, params *queryparams.DeploymentsQueryParams, parentId *string) *gorm.DB {
    if len(params.IDs) > 0 {
        query = query.Where("id IN ? OR unique_identifier IN ?", params.IDs, params.IDs)
    }
    // The IDs field is the only one used for identity filtering.
    // Since "uid" is never parsed into IDs (or any other field),
    // ?uid=urn:example:sensor:001 is silently discarded.
}

Scenario:

# Server has 37 systems registered
# Filter by UID — should return only one
GET /systems?uid=urn:os4csapi:system:nws:KDEN:v1

# Expected: 1 system returned
# Actual: all 37 systems returned (first 10 due to default limit)

Impact: Any client using ?uid= to look up resources by their globally unique identifier gets the entire (paginated) collection back instead of the matching resource. This is a spec-compliance failure that affects all resource types: systems, datastreams, deployments, procedures, sampling features, properties, control streams, observations, and commands.

The OSHConnect-Python publisher bootstrap helpers rely on ?uid= for idempotent resource creation (check-before-create). The workaround was to fetch all resources with ?limit=1000 and filter client-side:

# Workaround in bootstrap_helpers.py
def find_by_uid(session, url, target_uid):
    resp = session.get(f"{url}?limit=1000")  # Can't rely on ?uid= filter
    for item in resp.json().get("items", resp.json().get("features", [])):
        uid = item.get("properties", {}).get("uid") or item.get("uid", "")
        if uid == target_uid:
            return item
    return None

---

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	~10	Add UIDs []string field and parse uid query parameter in BuildFromRequest()
internal/repository/system_repository.go	Modify	~5	Add unique_identifier IN ? clause for UIDs in applyFilters()
internal/repository/deployment_repository.go	Modify	~5	Same — add UID filtering
internal/repository/datastream_repository.go	Modify	~5	Same — add UID filtering
All other *_repository.go files with applyFilters	Modify	~5 each	Same pattern across all resource types
e2e/	Modify	~30	Add E2E test for ?uid= filtering

Proposed Solutions

Option A: Add UIDs field to QueryParams (Recommended)

// internal/model/query_params/query_params.go
type QueryParams struct {
    IDs    []string
    UIDs   []string // NEW: parsed from ?uid= parameter
    Q      []string
    Limit  int
    Offset int
}

func (QueryParams) BuildFromRequest(r *http.Request) *QueryParams {
    params := &QueryParams{
        Limit:  10,
        Offset: 0,
    }
    // ... existing code ...
    if ids := r.URL.Query().Get("id"); ids != "" {
        params.IDs = strings.Split(ids, ",")
    }
    // NEW: parse uid parameter
    if uids := r.URL.Query().Get("uid"); uids != "" {
        params.UIDs = strings.Split(uids, ",")
    }
    return params
}

// In each repository's applyFilters():
if len(params.UIDs) > 0 {
    query = query.Where("unique_identifier IN ?", params.UIDs)
}

Pros: Minimal diff; follows existing pattern for id; spec-compliant; backward compatible
Cons: Requires touching every repository's applyFilters()
Effort: Small | Risk: Low

Option B: Map uid into existing IDs field

Since applyFilters() already does WHERE id IN ? OR unique_identifier IN ? for the IDs field, simply also parse uid into IDs:

if uids := r.URL.Query().Get("uid"); uids != "" {
    params.IDs = append(params.IDs, strings.Split(uids, ",")...)
}

Pros: Zero changes to repositories; single-line addition in BuildFromRequest()
Cons: Conflates two semantically different parameters; could return unexpected results if a uid value happens to match a local id
Effort: Small | 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 public API signatures unless the finding specifically requires it
• ❌ Do NOT add uid filtering to single-resource GET endpoints (they use path-based ID lookup)
• ❌ Do NOT implement uid as a path parameter — the spec defines it as a query parameter on list endpoints

Acceptance Criteria

• GET /systems?uid=urn:test:system:001 returns only the system with that UID
• GET /datastreams?uid=urn:test:ds:001 returns only the matching datastream
• GET /deployments?uid=urn:test:dep:001 returns only the matching deployment
• Comma-separated UIDs work: ?uid=urn:a,urn:b returns both matching resources
• When no resource matches the UID, an empty collection is returned (not an error)
• Existing ?id= filtering still works unchanged
• Existing tests still pass (make test)
• E2E test added for ?uid= filtering

Dependencies

Blocked by: Nothing
Blocks: Nothing
Related: #9 — Default pagination limit of 10 (compounds this problem — even ?id= returns only first 10 matches); ogc-client-CSAPI_2#167 — Client library default limit (client-side companion 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 — uid param never parsed
2	internal/repository/deployment_repository.go — applyFilters()	Representative filter logic showing IDs used but no UIDs
3	OGC 23-001 §7.3 — Query parameters	Spec defines uid as a standard list filter parameter
4	OSHConnect-Python publishers/bootstrap_helpers.py — find_by_uid()	Real-world workaround demonstrating impact

[Sam-Bolling]

Evaluation result — research-resolved, NOT a P1 spec-compliance bug

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

Headline: the spec does not define a uid query parameter

Direct inspection of the canonical OGC source — opengeospatial/ogcapi-connected-systems/master/api/part1/openapi/parameters/idList.yaml:

name: id
description: |-
  List of resource local IDs or unique IDs (URI).
  Only resources that have one of the provided identifiers are selected.
in: query
examples:
  id:  { summary: Local IDs,  value: 'RES_ID1,RES_ID2,RES_ID63' }
  uri: { summary: Unique IDs, value: 'urn:example:resource:001,urn:example:resource:033' }

Same shape is referenced from every list endpoint via $ref: ../parameters/idList.yaml, and inlined identically in the Part 2 OAS bundle (/datastreams parameters, lines 52-77). Grepping the Part 2 bundle for name: uid as a query parameter returns zero hits — the only uid: matches are uid properties on Link/Feature objects, not query parameters.

The spec defines exactly one parameter — id — whose value list may contain either local IDs OR URIs (= "UIDs"). The issue's citation of "OGC 23-001 §7.3 defines uid as a standard query parameter" does not match the canonical OAS source.

cs-go already implements the spec parameter correctly

Every list-endpoint repository's applyFilters does the spec-correct dual-match:

// system_repository.go:393  (and equivalents in datastream/control_stream/
// deployment/procedure/property/sampling_feature/feature repositories)
if len(params.IDs) > 0 {
    query = query.Where("id IN ? OR unique_identifier IN ?",
                        params.IDs, params.IDs)
}

So ?id=<URI> is already the spec-compliant URI filter. It works on HEAD today.

Live verification on HEAD

#	Request	numberMatched	Verdict
T1	?id=666ed3fe-... (UUID)	1	✅ local-ID branch
T2	?id=urn:test:issue1:sys:1 (URI — the publisher's actual need)	1	✅ URI branch works
T3	?uid=urn:test:issue1:sys:1	12	unknown-param ignored (= same as T7)
T4	?id=urn:does:not:exist	0	✅ empty collection on no match
T5	?id=666ed3fe-...,urn:does:not:exist	1	✅ comma-separated mixed
T7	?foo=bar&limit=2	12	unknown-param foo ignored — same mechanism as T3

T3 is not "uid parameter is broken" — it is "Go's url.Values.Get returns empty for any unknown key, including the misspellings tested in T7". uid is unknown from the spec's perspective; the spec parameter is id.

Verdicts on the issue's claims

Claim	Verdict
QueryParams.BuildFromRequest() parses id but never reads uid	Factually true — but a non-defect, because uid is not in the spec
"OGC 23-001 §7.3 defines uid as a standard query parameter"	Incorrect — spec parameter is id and it accepts both forms
"All list endpoints silently ignore ?uid= and return unfiltered results"	True — but consistent with how the API treats every unknown parameter
Severity P1-Critical	Disagree — no spec-compliance failure; URI lookup is fully supported via ?id=
AC: "Comma-separated UIDs work"	Already met via ?id=urn:a,urn:b (T5)
AC: "Empty collection when no resource matches"	Already met via ?id=urn:does:not:exist (T4)
Option A (add UIDs field + per-repo branch)	Not recommended — duplicates a path the spec parameter already covers; touches every repository for no spec benefit
Option B (alias uid → IDs)	Possible only as a P4 SensorHub-compat alias — explicitly not a spec compliance fix

Actual root cause of the publisher pain

OSH SensorHub accepts ?uid= (SensorHub-era / SOS 2.0 idiom). The OSHConnect-Python publisher inherited this idiom and sent ?uid=urn:... to cs-go, where it falls through silently. The correct publisher fix is one character:

# bootstrap_helpers.py — corrected
def find_by_uid(session, url, target_uid):
    resp = session.get(f"{url}?id={target_uid}")   # spec parameter
    items = resp.json().get("items", resp.json().get("features", []))
    return items[0] if items else None

This drops the client-side filter loop, removes the ?limit=1000 correctness hazard, and works on cs-go today. Interop fix is client-side, not server-side.

Recommendation

Close #7 as research-resolved. The factual claims about cs-go's code are accurate; the spec interpretation is not. No UIDs field, no separate uid query parameter, no per-repo changes are warranted as spec-conformance work.

I'll file one small follow-up only:

• F2 [P4 docs] — README/OpenAPI note that the spec filter parameter is id and accepts both local IDs and URIs, with examples. Eliminates the discoverability footgun for future publishers without committing to non-spec extensions.

(I am explicitly not filing the uid→id alias as a follow-up. If cross-stack interop with un-modifiable SensorHub clients later becomes a project priority, the existing analysis here is enough to add the alias in one line.)

Methodology note

This is the third issue in a row (#5 → #6 → #7) where the comparative-server framing inverted the conformance polarity: SensorHub's behavior was treated as the baseline, and cs-go's deviation from SensorHub was read as a defect. In all three cases, direct spec inspection showed cs-go matches the spec and SensorHub deviates. The decisive evidence here was a single fetch of parameters/idList.yaml from the canonical opengeospatial repo. When an issue says "server X is missing feature Y that server Z has", open the canonical spec source for the feature by name before stopping at the comparative table.

[Sam-Bolling]

Closing as not planned, in agreement with the maintainer.

Resolution

@SomethingCreativeStudios on the upstream triage pass: "UID... still not doing" — i.e. the maintainer is rejecting the proposed ?uid= query parameter on the same spec-compliance grounds the evaluation reached. Posting the rationale chain so the closure is auditable.

Why no code change

The issue cited "OGC 23-001 §7.3 defines uid as a standard query parameter for filtering resources by their globally unique identifier" — but direct inspection of the canonical OGC source at opengeospatial/ogcapi-connected-systems/master/api/part1/openapi/parameters/idList.yaml shows otherwise:

name: id
description: |-
  List of resource local IDs or unique IDs (URI).
  Only resources that have one of the provided identifiers are selected.
in: query
required: false
schema: { $ref: idListSchema.yaml }
explode: false
examples:
  id:  { summary: "Local IDs",  value: 'RES_ID1,RES_ID2,RES_ID63' }
  uri: { summary: "Unique IDs", value: 'urn:example:resource:001,urn:example:resource:033' }

The same shape is referenced from every list-endpoint YAML in Part 1 via $ref: ../parameters/idList.yaml, and is inlined identically in the Part 2 OAS bundle (docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml lines 52–77 for /datastreams). Grepping the bundle for name: uid as a query parameter returns zero hits — the only uid: occurrences are property fields on Link / Feature object schemas, not query parameters.

The spec defines exactly one filter parameter — id — whose value list may contain either local IDs OR URIs (the things the issue calls "UIDs"). There is no ?uid= parameter to implement. Adding one would be a non-spec server-specific extension carrying two sources of truth for the same lookup.

What cs-go already implements correctly

Every list-endpoint repository's applyFilters does the spec-correct dual-match:

// internal/repository/system_repository.go:393   (and equivalents in
// datastream / control_stream / deployment / procedure / property /
// sampling_feature / feature repositories — 8 sites total)
if len(params.IDs) > 0 {
    query = query.Where("id IN ? OR unique_identifier IN ?", params.IDs, params.IDs)
}

Live confirmation on HEAD 4b994212 (transcript):

#	Request	numberMatched	Verdict
T1	?id=666ed3fe-... (local UUID)	1	✅ local-ID branch works
T2	?id=urn:test:issue1:sys:1 (URI)	1	✅ URI branch works — this is the publisher's actual need
T3	?uid=urn:test:issue1:sys:1	12	unknown param — silently ignored (Go's url.Values.Get returns empty for any unknown key)
T4	?id=urn:does:not:exist	0	✅ empty collection on no match
T5	?id=666ed3fe-...,urn:does:not:exist	1	✅ mixed comma-separated
T7	?foo=bar&limit=2	12	unknown param foo silently ignored — identical mechanism to T3

So the symptom — ?uid= returns unfiltered results — is real, but it's the same generic "unknown query params are silently ignored" behaviour that applies to any misspelling (?lmiit=10, ?systemId=x, etc.), not a missing spec feature. Both stated acceptance criteria — "comma-separated UIDs work" (T5) and "empty collection when no resource matches" (T4) — are already met via ?id=.

Where the interop fix belongs

The publisher symptom that triggered this issue is OSH SensorHub accepting a ?uid= idiom (SOS-2.0-era) that doesn't exist in OGC 23-001 / 23-002. OSHConnect-Python inherited the idiom and sent ?uid=urn:... to cs-go, where it falls through silently.

The publisher's correct fix is a one-character change:

# corrected
resp = session.get(f"{url}?id={target_uid}")   # spec parameter

That is shorter than the existing workaround, drops the client-side filter loop, removes the ?limit=1000 correctness hazard, and works on cs-go today.

If wider OSH ↔ cs-go interop is desired, the appropriate venue is an issue against OSH SensorHub (which deviates from the spec by exposing a non-standard ?uid=), not cs-go.

Mapping rationale → original claims

Claim from issue body	Outcome
"QueryParams.BuildFromRequest() parses id but never reads uid"	Factually true — but a non-defect, because uid isn't in the spec.
"OGC 23-001 §7.3 defines uid as a standard query parameter"	Incorrect. Spec parameter is id and it accepts both local IDs and URIs (per the idList.yaml quoted above).
"All collection list endpoints silently ignore ?uid= and return unfiltered results"	Factually true — but consistent with how Go's url.Values.Get treats every unknown parameter.
Severity P1-Critical	Disagree. No spec-compliance failure; publisher's actual need (URI lookup) is fully supported via ?id=.
AC: comma-separated UIDs work	Already met (T5: ?id=urn:a,urn:b).
AC: empty collection on no match	Already met (T4: ?id=urn:does:not:exist).
Option A: add UIDs field + per-repo unique_identifier IN ? branch	Not recommended — duplicates a code path the spec parameter already covers, drift risk, touches every repository for no spec benefit.
Option B: alias uid → IDs	Maintainer declined this too. Per the maintainer's note on the related #26 ("UID is not a valid param"), even the alias was rejected on consistency grounds.

Methodology note

This is the third issue in a row (#5 → #6 → #7) where the comparative-server framing inverted the conformance polarity — SensorHub's behaviour was being treated as the baseline, and cs-go's deviation from SensorHub was being read as a defect. In all three cases, direct spec inspection showed cs-go matches the spec and SensorHub is the deviating party. The maintainer's "still not doing" tracks this pattern.

Cross-references

• Original evaluation: docs/research/issue-evaluations/issue-007.md (T1–T7 transcripts, source attestation across all 8 UID-bearing repositories, canonical-spec extract from idList.yaml).
• Related closures on the same theme: Research: Strict schema validation — requiring ALL declared fields in observation results #5 (research-resolved, optional mechanism already works), Research: Cross-resource references — @link objects only vs. flat @id strings for interoperability #6 (@link is the spec shape), [P4 docs] Document that ?id= accepts both local IDs and URIs (the spec UID filter is ?id=, not ?uid=) #26 (per maintainer: "UID is not a valid param").

Closing as not planned (won't fix), in agreement with the maintainer's triage.