Glossary

A reference for the domain concepts and project-specific terms used throughout fim-portal-cli. The FIM domain is German; this glossary gives the English term used in the CLI/API (where one exists) alongside the original German.

Translation table (from the API description). The CLI follows these:

German	English / API term
Datenschema	schema
Datenfeldgruppe	data group / group
Datenfeld	data field / field
Dokumentsteckbrief	document profile
Leistung	service
Leistungsbeschreibung	xzufi-service
Prozess	process
Codelisten	code lists

The FIM programme

FIM — Föderales Informationsmanagement (“Federal Information Management”). A German government programme that standardises the information behind public administrative services so they can be described once and reused everywhere (forms, processes, online services). FIM is organised into three Bausteine (building blocks), each backed by an XÖV data exchange standard.

FIM Portal. The central catalogue (fimportal.de) that collects all FIM building blocks and exposes them through the REST API this tool wraps. Formerly hosted at schema.fim.fitko.net, which still resolves to the same API.

FITKO — Föderale IT-Kooperation. The public-sector body that operates the FIM Portal. The source lives on OpenCoDE.

XÖV. The family of XML-based standards for data exchange in German public administration. XDatenfelder, XZuFi and XProzess are all XÖV standards.

The three standards (Bausteine)

XDatenfelder. The standard for data definitions — schemas, data groups, data fields and document profiles. Two relevant versions exist: XDF2 (2.0) and XDF3 (3.0.0); see xdf_version. CLI command groups: schemas, groups, fields, document-profiles.

XZuFi — XML für Zuständigkeitsfinder. The standard for services (Leistungen): what a service is, who is responsible, master texts, online services and the organisations that provide them. CLI command groups: service-profiles, service-texts, organizational-units, specializations, online-services.

XProzess. The standard for processes — how an administrative procedure runs, at varying levels of detail. CLI command groups: processes, process-classes.

XDatenfelder building blocks

Datenschema (schema). The top-level container describing the data needed for a service. References data groups and data fields. Has a steckbrief_id linking it to a document profile. CLI: schemas.

Datenfeldgruppe (data group / group). A reusable, named grouping of data fields (and nested groups) — e.g. “Name of a natural person” bundling the first name, surname, etc. fields. CLI: groups.

Datenfeld (data field / field). The atomic unit of data capture — a single input, e.g. “Familienname”. Carries a Feldart and a Datentyp (below) and may reference a code list. CLI: fields.

Dokumentsteckbrief (document profile). A profile describing a document in a process — what role it plays (trigger, result, incoming/outgoing data) and which schema realises it. Carries a Dokumentart. Can be abstract (ist_abstrakt); the CSV export filters on that with abstraktionsstufe Abstrakt or Konkret (library only). CLI: document-profiles.

Feldart. The kind of a data field: input, select, label, hidden, locked. (Filter: fields search --feldart.)

Datentyp. The data type of a field: text, text_latin, date, time, datetime, bool, num, num_int, num_currency, file, obj. (Filter: fields search --datentyp.)

Dokumentart. The classification of a document profile (a numeric code list 001…014, 999). See the code list.

Code list (Codeliste). An enumerated set of allowed values referenced by a data field (e.g. country codes). The portal serves these behind immutable URLs. CLI: code-lists.

XZuFi building blocks

Leistung (service). An administrative service offered to citizens or businesses (e.g. “apply for a passport”).

Leistungsteckbrief (service profile). The descriptive profile of a service — the searchable, structured summary. Identified by a Leistungsschlüssel. CLI: service-profiles.

Leistungsstammtext (service master text / xzufi-service). The reusable textual content of a service (short text, full text, legal bases), maintained by an editorial office. Identified by redaktion_id + leistung_id + source. CLI: service-texts.

Leistungsschlüssel. The key identifying a service (often a LeiKa key such as 99050048262000).

LeiKa — Leistungskatalog. The national catalogue of administrative services; the origin of many service keys and classifications.

source (XzufiSource). Where a service text originates: leika, landesredaktion (a federal-state editorial office) or pvog (the Portalverbund Online-Gateway).

Redaktion / redaktion_id. The editorial office that maintains a record, and its identifier.

Organisationseinheit (organizational unit). An administrative organisation (authority/office) in XZuFi. CLI: organizational-units.

Spezialisierung (specialization). An XZuFi specialization record. CLI: specializations.

Onlinedienst (online service). A digital service offering in XZuFi. CLI: online-services.

Einheitlicher Ansprechpartner (EA). “Single point of contact” — an EU-driven concept; some services are flagged as EA-relevant (--einheitlicher-ansprechpartner).

SDG — Single Digital Gateway. EU regulation; services can be flagged SDG-relevant and tagged with an SDG information area (--sdg, --sdg-relevant). The JSON search takes sdg_relevant as true/false; the CSV export (tools.searchCsvDownload) takes Ja/Nein instead and ignores true, so the library accepts only Ja or Nein there.

OZG — Onlinezugangsgesetz. The German Online Access Act. Services carry an ozg_id and an OZG-Themenfeld (thematic field, e.g. familie_kind).

Lagen / Portalverbund. Life/business “situations” used to organise services in the federal portal network (--lagen-portalverbund).

Vollzugsbehörde. The executing authority for a service (BAMF, BLE, DRV).

XProzess building blocks

Prozess (process). A modelled administrative procedure. Identified by process_id + process_version + Detaillierungsstufe + verwaltungspolitische Kodierung. CLI: processes.

Prozessklasse (process class). A higher-level, reusable process template, identified by id + version. CLI: process-classes.

Detaillierungsstufe. The level of detail of a process model: 101–105 (coarse → fine). Required to address a specific process. Any other value is rejected before a request, by the CLI and the library alike.

Verwaltungspolitische Kodierung. The fourth part of a process address, next to id, version and Detaillierungsstufe (e.g. 17). Every processes search result item carries it as verwaltungspolitische_kodierung; pass that value as the <kodierung> argument of processes get and the process downloads.

Anwendungsgebiet. The application domain of a process (01–17).

Musterprozess. A reference/template process (--is-musterprozess).

Operatives Ziel, Verfahrensart, Handlungsform. XProzess classification dimensions used to filter process classes.

Visualization / Report. Generated artefacts for a process: a visual model (BPMN-like) and a quality/structure report. CLI: processes visualization, processes visualization-display, processes report.

Identifiers, versioning & metadata

FIM ID (fim_id). The stable identifier of a building block, prefixed by type: S… schema, D… document profile, F… field, G… group. Example: S07000009.

FIM version (fim_version). The version of a specific FIM ID, e.g. 1.0, 3.0.0. The special value latest resolves to the newest version — the default in every CLI get/xdf command when you omit the version.

namespace. For fields and groups, a URN namespace that, together with the FIM ID, identifies the element (e.g. urn:xoev-de:fim:standard:xdatenfelder). Required as a path argument for fields/groups get/versions/xdf.

Nummernkreis. The numeric “number range” a building block belongs to, roughly an owning organisation/domain. Filtering is a prefix match: 01 matches all of 01000. Repeatable (--nummernkreis).

Freigabestatus (freigabe_status). The release/approval status, an integer 1–8: 1 in Planung (planned), 2 in Bearbeitung (in progress), 3 Entwurf (draft), 4 methodisch freigegeben (methodically approved), 5 fachlich freigegeben (silber), 6 fachlich freigegeben (gold), 7 inaktiv (inactive), 8 vorgesehen zum Löschen (marked for deletion). 5 and 6 are the released states. See the status code list. Repeatable filter (--freigabe-status). freigabe_status_label is the human-readable form, present on schemas, groups, fields and document profiles; service profiles, service texts and processes carry only the number.

status_gesetzt_durch / _am / _seit / _bis. Who set the current status and when; the seit/bis variants are date-range filters.

gültig ab / bis (gueltig_ab / gueltig_bis). Validity period of a record; --gueltig-am <date> returns records valid on that date.

Bezug. A free-text “reference/relation” field (e.g. a legal basis); bezug_unterelemente searches the references of a schema’s sub-elements.

Versionshinweis. A note describing what changed in a version.

Stichwort. Keyword/tag (XDF3 only), e.g. Anwendungsgebiet::Bundesrepublik.

is_latest. Whether a record is the newest version of its kind (--is-latest).

fts_match. When a full-text search matches, the snippet/field that matched.

Search & API concepts

Full-Text-Search (fts_query). Free-text search across a resource; suche_nur_in (--suche-nur-in) restricts it to one module (e.g. Rechtsgrundlagen). Allowed modules differ per resource (schemas additionally allow Stichwort).

Blank filter values. The API treats an empty parameter (name=) as no filter and answers with the unfiltered result. So a blank value ("" or whitespace only) is rejected before any request: by the CLI as a usage error, and by the library (FimPortalClient) with a FimValidationError. The same goes for a blank id or version in a path: it would turn a request for one object into the search or the versions list.

order_by. Result ordering. The allowed values differ by resource — Datenfelder resources share one set (relevance, id_asc, name_asc, …); services have their own sets (including relevance, titel_asc). relevance ranks the hits of an --fts-query search. Processes and process classes have no sort order, so search-csv refuses --order-by for them.

Offset pagination. The v1/XDatenfelder and most v0 search endpoints page with offset + limit (limit 1–200, default 200) and return a PaginatedResult envelope (items, offset, limit, count, total_count). A limit outside 1–200 or a negative or fractional offset is rejected before any request, by the CLI and the library alike.

Cursor pagination. The XZuFi entity listings (organizational-units, specializations, online-services) page with cursor + limit and return a CursorPaginationResult envelope (items, limit, count, next_cursor). Pass the returned next_cursor as the next --cursor (a non-negative integer).

Immutable URLs. The portal serves code lists, JSON Schema and XSD files behind constant URLs intended for stable production use; the full URLs are included in API responses.

Rate limiting. The API rate-limits by IP and returns 429 when exceeded; the client retries 429/503 automatically (--max-retries), waiting the response’s Retry-After (up to 30 s; a longer one is not retried) or else backing off linearly.

Authenticated endpoints (out of scope). Uploads, the /tools/* converters and quality-checks, and token introspection require an Access-Token. This tool implements only the open, no-auth (read-only GET) endpoints, plus the public CSV export.

Log record. Every diagnostic line the CLI writes to stderr: a timestamp, a level (ERROR, WARN, INFO) and a topic fim-portal.<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, and a malformed answer — bad JSON, the wrong shape, an HTML page, an unknown charset), http (the connection, the cleartext warning, and one WARN per retry before it waits) and output (the Wrote N bytes notes, a failure to write the -o file or stdout). A record is always one line; control characters in it are escaped.

Download formats

XDF / XML download (xdf). The native XDatenfelder XML for a schema, group, field or document profile.

XZuFi download (xzufi). The native XZuFi XML for a service text or XZuFi entity.

XProzess download (xprozess). The native XProzess XML for a process or a process class. The API’s OpenAPI document says a process class answers with JSON, but the server sends XML, so process-classes xprozess is a download like the others.

PDF export (pdf). A rendered PDF of a service profile/text in a given language code. The code depends on where the text comes from: service profiles and leika service texts use de-DE, pvog service texts use bare de/en. The languageCode attributes in the xzufi download show the codes a text has. A code the text doesn’t have exits 4 (“Could not find language”), and so does the --sprache search filter’s value (Deutsch).

search-csv. A tools endpoint that streams a search result as CSV. Its --resource takes the portal’s singular resource names (schema, field, processclass, …); the server answers any name it does not know with a CSV of Leistungen, so the CLI and the library (tools.searchCsvDownload) reject those, and a missing resource too. The server also ignores a filter value it doesn’t know (feldart=SELECT) and a filter for another resource (feldart on schema) and exports the unfiltered result; the CLI and the library reject those as well, before the request.

Library & internals. Terms for the TypeScript client and its internals — FimPortalClient, resource groups, the request engine, transport, retry/backoff, error types, query builder — now live in DEVELOPING.md.