# 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](https://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`.

---

## 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, so the client sends one filter as `fq` and several as `fq_list`. CKAN puts
`+capacity:public` in front of an `fq`, so a top-level `OR` in one filter is not
applied: write `(organization:open-nrw OR groups:tran)`, not the bare `OR`.

**`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`.)

**`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](DEVELOPING.md)**.