Glossary
A reference for the domain concepts and project-specific terms used throughout
govdata-cli. This tool wraps the GovData CKAN Action API (ckan.govdata.de),
so the vocabulary is split between the GovData open-data programme, the
CKAN software that powers the catalogue (and its quirks, e.g. “package” ==
“dataset”), and the project’s own client/CLI terms.
The GovData programme
GovData. The central open-data portal for Germany (govdata.de), federating
open datasets from the federal government (Bund), the federal states (Länder) and
municipalities (Kommunen). It is the German node that feeds the European
data.europa.eu portal.
Open data. Data published under an open licence for anyone to use, reuse and redistribute. Everything this tool reaches is open and requires no API key.
CKAN. The open-source data-management/cataloguing software (originally by the Open Knowledge Foundation) that GovData runs on. Its HTTP interface is the Action API, which this client wraps.
DCAT-AP.de. The German application profile of the W3C DCAT (Data Catalog Vocabulary) metadata standard. GovData’s dataset metadata follows it; it is why a dataset’s raw fields are catalogue-specific and exposed here as untyped JSON.
CKAN core objects
Dataset (Package). The primary catalogue unit: a described collection of
data on one topic (title, description, publisher, tags, licence, and one or more
resources). CKAN historically calls a dataset a “package”, so the API action
names use package_* even though the user-facing concept is “dataset”. Exposed
as a raw JsonObject (Package). CLI: package, packages, search.
Resource (distribution / Resource). A single distributable file or service
endpoint within a dataset — e.g. one CSV, JSON, XLSX or WMS URL. A dataset
usually has several. In DCAT terms a resource is a distribution. Identified by
its own id. CLI: resource <id>.
Organization (Organization). A data publisher — the body that owns and
maintains datasets (e.g. a federal statistics office). Organizations have
membership/ownership semantics in CKAN. CLI: organizations, organization.
Group (Group). A thematic grouping / category of datasets (e.g. an
open-data theme). Unlike an organization, a group does not own datasets; it
classifies them. CLI: groups, group.
Tag. A free keyword attached to a dataset for discovery. Tags can be listed
and filtered by substring. CLI: tags [--query <substring>].
Facet. A field CKAN aggregates over a search result to give value counts
(e.g. how many hits per organization or res_format). The counts are
datasets, not resources: a dataset with five CSV files counts once. Requested
via facet.field (the library’s facet_field option) and returned under
facets / search_facets in a PackageSearchResult. Only the top
facet.limit values come back (50 unless you set it; -1 returns all).
CKAN Action API mechanics
Action API. CKAN’s RPC-style HTTP API, rooted at /api/3/action/. Each
endpoint is an action addressed by name, e.g. package_search,
package_show, organization_list. This client targets the open, read-only
(GET) actions only.
Action name. The [a-z0-9_]+ identifier of an action. The client validates
every name against ^[a-z0-9_]+$ (and URL-encodes it) so the generic escape
hatch cannot inject extra path segments, a query string or a fragment into the
request URL.
CKAN envelope (CkanEnvelope). Every Action API response is wrapped in
{ help, success, result } (or { help, success, error } when success is
false). help is a docstring URL/text, success is the status flag, result
is the payload. The client unwraps result for callers and raises an error
on success: false.
package_search. The full-text / faceted dataset search action. Returns a
PackageSearchResult (count, results, facets, search_facets, sort).
CLI: search. Parameters: q, fq / fq_list, rows, start, sort,
facet.field.
package_show / package_list. Fetch one dataset by id/name; list dataset
names with limit/offset. CLI: package, packages.
organization_show / organization_list, group_show / group_list.
Show one / list organizations or groups. The _list actions return bare names
by default, or full objects with all_fields. CLI: organization(s),
group(s) (--all-fields).
tag_list, resource_show. List tags (optional query substring filter);
show one resource by id. CLI: tags, resource.
Generic action (escape hatch). client.action(name, params) / the CLI
action <name> [--param key=value …] command call any read action — even
those without a typed convenience method — and return the unwrapped result.
A blank parameter name or value (q=, =x) is refused before any request — a
usage error in the CLI, a GovDataValidationError in the library — because CKAN
would read an empty value as “no filter”.
Log record. Every diagnostic line the CLI writes to stderr: a timestamp, a level
(ERROR, WARN, INFO) and a topic govdata.<area>, as text (log4j style) or with
--log-format jsonl as one JSON object per line. The areas: cli (usage errors,
commander’s messages, unexpected errors), api (the API’s answers: an error status,
CKAN’s success: false envelope even on HTTP 200, and a malformed answer — bad JSON, not JSON, not a CKAN envelope, the wrong result
shape), http (the connection, the cleartext warning, and one WARN per retry before it waits) and output (stdout failures). A
record is always one line; control characters in it are escaped.
Search parameters (Solr)
CKAN search is backed by Apache Solr, so its parameters use Solr syntax.
q (query). The Solr query string, e.g. title:Haushalt or a bare term.
CLI positional: search [query]. Solr tokenises the query, so a bare term may
match on a sub-token rather than the whole string (e.g. abc12345 can hit a title
containing 12345). Scope the field (title:…) or add an --fq filter when you
need a precise match instead of a loose keyword.
fq (filter query). A Solr filter constraining results without affecting
relevance scoring, e.g. organization:statistisches-bundesamt, groups:tran.
CLI: --fq (repeatable; every filter must match). CKAN rejects a repeated fq
key, and it puts +capacity:public in front of a single fq, which disables a
top-level OR in it. So the client sends every filter as fq_list (a single one
twice, because CKAN splits a lone fq_list value into characters), and
organization:open-nrw OR groups:tran works as written.
rows / start. Page size and zero-based offset for paging through search
hits. CLI: --rows, --start. GovData’s Solr caps rows at 1000 per
request, so a larger value yields at most 1000 results (with count still
reporting the true total); page past the first 1000 with start. (The *_list
actions instead use limit / offset.)
sort. A Solr sort expression, e.g. metadata_modified desc. CLI: --sort.
facet.field. The fields to compute facet counts over, as a JSON list such
as ["res_format"] (see Facet). The library option is facet_field; CKAN
itself rejects a facet_field parameter.
res_format. A common facet/filter value: the format of a resource (CSV,
JSON, WMS, …). Used inside an fq, not a dedicated flag. The same format
appears as a bare string and as an EU file-type URI
(http://publications.europa.eu/resource/authority/file-type/CSV), so filter on
both: res_format:("CSV" OR "http://publications.europa.eu/resource/authority/file-type/CSV").
metadata_modified / metadata_created. Timestamp fields on a dataset; the
former is the usual sort key for “newest first”.
Identifiers & pagination
id / name (slug). Datasets, organizations and groups can be addressed by
either their CKAN id (UUID) or their human-readable name (URL slug). The
*_show actions accept either. Resources are addressed by id only.
limit / offset (ListParams). Pagination for the *_list actions: page
size and number of records to skip. (Distinct from search’s rows / start.)
--limit is 1 or more: CKAN reads limit=0 as “no limit”, so the CLI and the
client refuse 0; leave --limit out for the whole list.
all_fields. On organization_list / group_list, return full objects
instead of just names. CLI: --all-fields.
Library & internals. Terms for the TypeScript client and its internals —
GovDataClient, the request engine, transport, retry/backoff, error types, query builder — now live in DEVELOPING.md.