Supported queries and validation¶
The generator compiles a JSON results URL from an lxml OpenSearchDescription root element.
Jinja2 emits a pygeofilter evaluator with embedded validation definitions;
invoke expands the original OpenSearch URL template and sends that URL through requests. The generated module runs without the
osdd2pygeofilter package, Jinja2, or lxml. Regenerate it to pick up changes
to validation rules.
Only advertised placeholders are exposed as properties. Query names may differ
from those properties: q={searchTerms} maps searchTerms to q.
CQL2 translation¶
| Expression | Translation |
|---|---|
| Scalar equality, including reversed operands | Parameter assignment |
AND |
Combine assignments; reject conflicts |
EO numeric/date <, <=, >, >= |
EO one-sided interval notation |
EO numeric/date BETWEEN / IN |
Inclusive interval / set notation |
| Conjunction of EO intervals | Intersect bounds; reject an empty intersection |
S_INTERSECTS on a geo:geometry property |
Exact WKT and geo:relation=intersects when advertised |
Dates and timestamps use ISO serialization; booleans use true or false.
Identical assignments are deduplicated. Spatial predicates never approximate a
geometry by its bounding box. A bounding box can be assigned directly to the
advertised geo:box property.
OpenSearch descriptions do not define a universal translation for arbitrary
CQL2. OR, NOT, null predicates, arithmetic, functions, general temporal
predicates, and comparisons on parameters without an EO range contract fail
explicitly. Time filters can assign RFC 3339 values to time:start and
time:end; these are overlap search bounds, not a general implementation of
CQL2 temporal relations. Distinct scalar/set assignments to the same parameter
are rejected, including mixed scalar/interval conjunctions.
Validation¶
Invocation validates the complete parameter set, including defaults and fixed values, before sending a request. Evaluation logs warnings for unlisted option values.
| Contract | Checks |
|---|---|
| OpenSearch 1.1 | Required placeholders, integer pagination, URL offsets, declared languages and encodings |
| Parameter extension | Required occurrence, scalar occurrence limits, patterns, inclusive/exclusive numeric or date bounds, numeric steps |
| Geo | WGS84 coordinate limits, ordered latitude bounds, antimeridian boxes, finite coordinates/radius, supported relation values, nonempty 2D WKT syntax and bounds |
| Time | RFC 3339 timestamps with timezone, calendar validity, chronological start/end order |
| EO | Numeric/date scalar, set and interval syntax, integer fields, cloud/snow percentages, specified enumerations, advertised range/set restrictions and member patterns |
| SRU | Integer counts/offsets, record packing, rendering, sort-key flags and facet-sort structure |
| EUMETSAT/custom namespaces | QName mapping and constraints advertised by the service's Parameter elements |
WKT checking is syntactic and dimensional; it does not perform GEOS topology validation. String parameters without standard enums or advertised constraints remain unrestricted. Unknown extension namespaces do not inherit another extension's semantics merely because their prefix or local name matches.
The adapter supports declared input and output text encodings, defaulting to UTF-8. Explicit encoding parameters override declaration defaults; an HTTP response charset overrides the output-decoding fallback. Required placeholders need nonempty values. Missing optional placeholders are replaced with empty strings; surrounding URL text remains intact. No service defaults are invented.
URL templates may contain path, authority, fragment, query-name, and composite
query-value placeholders. The original template is preserved, including repeated
query keys and fixed literals. Replacement values are percent-encoded once;
existing literal escapes are not decoded and re-encoded. Missing required values,
malformed placeholders, ambiguous parameter aliases, unsupported occurrence
counts, and invalid parameter bindings are rejected. Expansion must produce an
absolute HTTP(S) URL before a request is sent. Multiple JSON
results URLs can be selected using url_index. Unknown foreign annotations are
retained as metadata but do not trigger network requests or dynamic code.
Advertised options¶
Parameter Option elements suggest values; they do not establish an exhaustive
enumeration. The generator preserves their submitted values as tuples
in PARAMETER_OPTIONS, keyed by HTTP parameter name, and omits labels, without changing the underlying parameter type.
Handlers log a WARNING immediately for each assigned value missing from its
advertised options tuple, without rejecting or changing it. Repeated assignments
and computed values are checked independently, before evaluation completes. Listed values and absent
parameters are silent. A pattern alongside options is enforced at invocation,
even for an advertised value. Unlisted values remain valid when they satisfy
the parameter's other constraints.
This follows the OGC EO guidance on supplying patterns when options describe only a subset of possible values. Closed enumerations require an explicit exhaustive contract; existing standard-defined enumerations, such as orbit direction, remain enforced. The generator does not infer a service-specific Enum, Literal, or schema enum from options alone.
Specification sources¶
- OpenSearch 1.1 Draft 5
- OGC EO extension 13-026r9
- OGC Geo and Time extensions 10-032r8
- OpenSearch SRU extension
- EUMETSAT live description
The historical EUMETSAT namespace page could not be recovered from the archive:
the exact-URL availability query returned no snapshot, and broader archive
queries returned a temporary outage. Accordingly, EUMETSAT-specific rules are
read from advertised constraints rather than claimed as a complete historical
profile implementation. The live description advertises eum:elementSetName
values full and brief, which are covered by regression tests.