> ## Documentation Index > Fetch the complete documentation index at: https://slovakapi.dev/llms.txt > Use this file to discover all available pages before exploring further. # Data models > Types, fields, and the conventions that apply across the entire API. *** ## Key concepts RPO responses are built around two concepts that explain almost everything: 1. **Validity**: most fields are *timed*, which means they carry a validity window. 2. **Codes**: most categorical values link to a codelist entry — see [Codelists](/rpo/concepts/codelists). Internalize these two concepts before reading the individual type docs — they appear on nearly every field in the API. *** ## Type hierarchy RPO's type system is shallow by design. A handful of primitives compose into the types you'll work with directly. ```mermaid theme={null} flowchart TD CV["CodeValue"] TVE["TimedValueEntry"] TCVE["TimedCodeValueEntry"] ADDR["Address"] ACT["Activity"] PN["PersonName"] SH["Stakeholder"] SB["StatutoryBody"] PO["PO (entity)"] TCVE -. "value is a CodeValue" .-> CV ADDR --> SH PN --> SH ADDR --> SB PN --> SB TCVE -.-> PO ADDR -.-> PO ACT -.-> PO SH -.-> PO SB -.-> PO ``` *** ## Embedded types A categorical value pairing a human-readable label with its codelist reference. Used wherever a field belongs to a controlled vocabulary. `code` can be an empty string — not `null`, not absent — when no matching codelist entry exists. Always guard against `""` before using it as a lookup key. Human-readable label (in Slovak). Always use this for display. Codelist entry key. Empty string if no matching entry exists. Identifies the codelist, e.g. `CL000056`. See [Codelists](/rpo/concepts/codelists). A string value with a validity window. The building block for any scalar field that can change over time — names, identifiers, and similar. The scalar value for this time period. Validity start (`YYYY-MM-DD`). Absent if the start date is unknown. Validity end (`YYYY-MM-DD`). **Absent means this is the current value** — not a data gap. The timed variant of a codelist-backed value. Wraps a `CodeValue` in a validity window so you can track when a classification like legal form or legal status changed. Note the double `.value` — the outer one is the timed entry property, the inner one is the human-readable label on the `CodeValue`. The categorical value for this period. Has its own `.value`, `.code`, and `.codelistCode`. Validity start (`YYYY-MM-DD`). Validity end. Absent if current. A structured postal address with a validity window. Use `formatedAddress` for display; parse the sub-fields only when filtering or grouping by location. Pre-formatted full address string. Use for display. Validity start (`YYYY-MM-DD`). Validity end. Absent if current address. Street name. Registry number (súpisné číslo). Orientation number (orientačné číslo). Array of postal codes. Usually one entry. Municipality from codelist `CL000025` or `UCE`. City quarter from codelist `CL010141` or `UCE`. Country from codelist `CL000086` or `STA`. Building identifier from the Address Register. *** ## Entity types A registered economic activity. Activities can be individually suspended without being terminated — giving three distinct states to check. Active = no `validTo` and not suspended. Suspended = `suspendedFrom` set, `suspendedTo` absent. Deregistered = `validTo` set. Free-text description of the activity. Date from which the activity is registered. Date the activity was deregistered. Absent if still registered. Suspension start date. Suspension end date. Absent if currently suspended. A structured name for a natural person. All components are arrays — a person may have multiple given names or titles. Pre-formatted full name. Use for display. First name(s). Current family name(s). Birth family name(s). Titles before the name (e.g. `Ing.`, `JUDr.`) from codelist `CL000062`. Titles after the name (e.g. `PhD.`) from codelist `CL000063`. A person or organisation with a formal relationship to the entity — shareholders, partners, members, and similar roles. May be a natural person (FO) or a legal entity (PO/OZ). Role from codelist `CL010109` (e.g. shareholder, partner). Relationship start date. Relationship end date. Absent if current. Address of the stakeholder. Name of the natural person. Present for FO only. IČO of the legal entity or organisational unit. Present for PO/OZ only. Full name of the legal entity. Present for PO/OZ only. Date of incorporation. Present for PO/OZ only. Date of dissolution. Present for PO/OZ only. A person or organisation authorised to act on behalf of the entity. Structurally identical to `Stakeholder` with one addition: `statutoryBodyMember` captures the specific role within a collective board. Type of statutory body from codelist `CL010113`. Role within a collective body from codelist `CL010470` (e.g. chairman, member). Appointment start date. Appointment end date. Absent if current. Address of the statutory body. Name of the natural person. Present for FO only. IČO of the legal entity. Present for PO/OZ only. Full name of the legal entity. Present for PO/OZ only. Date of incorporation. Present for PO/OZ only. Date of dissolution. Present for PO/OZ only. *** ## Timed values Instead of a single current value, most fields return an array of time-scoped entries. The **current value is always the entry where `validTo` is absent**. Entries with both `validFrom` and `validTo` set are historical. ```json Default theme={null} { "fullNames": [ { "value": "Acme s.r.o.", "validFrom": "2021-03-15" } ] } ``` ```json With history theme={null} { "fullNames": [ { "value": "Acme s.r.o.", "validFrom": "2021-03-15" }, { "value": "Beta s.r.o.", "validFrom": "2010-01-01", "validTo": "2021-03-14" } ] } ``` Historical data is opt-in. Pass `showHistoricalData=true` on the detail endpoint — without it, all entries with a `validTo` are omitted. *** ## Examples The current entry is the one with no `validTo`. Safe to use on any timed array — `fullNames`, `identifiers`, `legalForms`, etc. ```js theme={null} const current = entity.fullNames.find(e => !e.validTo); console.log(current.value); // "Acme s.r.o." ``` Useful for reconstructing entity state at a point in time — auditing, historical reports, or change detection. ```js theme={null} function valueAt(entries, date) { return entries.find(e => e.validFrom <= date && (!e.validTo || e.validTo >= date) ); } const nameIn2015 = valueAt(entity.fullNames, "2015-06-01"); console.log(nameIn2015?.value); // "Beta s.r.o." ``` Sort by `validFrom` descending to get a chronological changelog of any timed field. ```js theme={null} const history = [...entity.fullNames] .sort((a, b) => b.validFrom.localeCompare(a.validFrom)); history.forEach(e => { const to = e.validTo ?? "present"; console.log(`${e.validFrom} → ${to}: ${e.value}`); }); // 2021-03-15 → present: Acme s.r.o. // 2010-01-01 → 2021-03-14: Beta s.r.o. ```