{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/foretak-dev/json-schema/foretak-dev-company-report-schema.json", "title": "CompanyReport", "description": "Everything `registry-mcp` knows about one registered entity.\n\nThis is the single most important shape in the project. It is returned\nverbatim by ``GET /v1/{country}/company/{id}`` and by the MCP tool\n``lookup_company``.\n\nA registry module fills what its national register publishes and leaves the\nrest ``None``. Nothing here is Norway-specific; ``registries/no/`` maps\nEnhetsregisteret's fields onto it (see ``NORBIZ_SPEC.md`` §3).", "x-generated": "2026-11-08", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/foretak-dev-openapi.yml#/components/schemas/CompanyReport", "properties": { "country": { "type": "string", "title": "Country", "description": "ISO-3166-1 alpha-2, upper-case, e.g. 'NO'." }, "registry": { "type": "string", "title": "Registry", "description": "Registry slug, e.g. 'brreg'." }, "id": { "type": "string", "title": "Id", "description": "Canonical national identifier, digits/letters only, no spaces or dots." }, "id_formatted": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id Formatted", "description": "The identifier as a local would write it, e.g. '923 609 016'." }, "id_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id Scheme", "description": "Name of the identifier scheme, e.g. 'organisasjonsnummer'." }, "euid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Euid", "description": "European Unique Identifier (EUID, Commission Implementing Regulation (EU) 2021/1042 Article 9), where the register publishes one, e.g. Finland's 'FIFPRO.0112038-9'. None for a register that does not (today: all of ours). Three traps: (1) this is not the LEI — the EUID is register-issued, mandatory in the EU and free, the LEI is voluntary, global, LOU-issued and fee-bearing; an entity may carry both, one or neither. (2) 'EUid' also names the EU Digital Identity wallet, a personal credential unrelated to company registers. (3) it is not stable across a register reorganisation, since it encodes the register of origin (e.g. France's RNE replacing the RCS in 2023). Carried verbatim from the register; never constructed from parts." }, "name": { "type": "string", "title": "Name", "description": "Current registered name." }, "previous_names": { "items": { "type": "string" }, "type": "array", "title": "Previous Names", "description": "Former registered names, newest first." }, "legal_form_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Form Code", "description": "National legal-form code, e.g. 'AS', 'ASA', 'ENK'." }, "legal_form": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Form", "description": "English label, e.g. 'Private limited company'." }, "legal_form_local": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Form Local", "description": "Local label, e.g. 'Aksjeselskap'." }, "limited_liability": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Limited Liability", "description": "True when owners are not personally liable for debts." }, "has_board_duty": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Board Duty", "description": "True when this legal form must have a registered board." }, "has_annual_accounts_duty": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Annual Accounts Duty", "description": "True when this legal form must file annual accounts with the state." }, "status": { "$ref": "#/$defs/CompanyStatus", "description": "Normalised lifecycle status.", "default": "unknown" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Detail", "description": "One sentence in English explaining the status and the flag it came from." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Convenience mirror of `status == active`, so agents need no enum table.", "default": false }, "registered_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Registered At", "description": "Date first entered in the central register." }, "founded_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Founded At", "description": "Incorporation / foundation date." }, "business_register_registered_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Business Register Registered At", "description": "Date entered in the commercial/business register, where that is separate." }, "bankruptcy_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Bankruptcy Date", "description": "Date bankruptcy was opened." }, "deregistered_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Deregistered At", "description": "Date the entity was deleted from the register." }, "vat_registered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Vat Registered", "description": "Registered for VAT (Norway: Merverdiavgiftsregisteret)." }, "vat_registered_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Vat Registered At", "description": "Date of VAT registration." }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Number", "description": "VAT identifier if it differs from `id` (Norway: id + 'MVA')." }, "in_business_register": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "In Business Register", "description": "Listed in the commercial register (Norway: Foretaksregisteret)." }, "registers": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Registers", "description": "Other national sub-registers this entity is or is not in, keyed by a lower-case slug, e.g. {'stiftelsesregisteret': false}." }, "employees": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Employees", "description": "Registered number of employees. None = not reported." }, "employees_reported": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Employees Reported", "description": "Whether the registry holds an employee figure at all (distinguishes 0 from unknown)." }, "industry_codes": { "items": { "$ref": "#/$defs/IndustryCode" }, "type": "array", "title": "Industry Codes", "description": "Industry classifications, primary first." }, "sector_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sector Code", "description": "Institutional sector code." }, "sector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sector", "description": "Institutional sector description." }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose", "description": "Statutory purpose / objects clause, joined into one string." }, "activity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Activity", "description": "Free-text description of actual activity." }, "share_capital": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Share Capital", "description": "Registered share capital." }, "share_capital_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Share Capital Currency", "description": "ISO-4217 code for `share_capital`." }, "business_address": { "anyOf": [ { "$ref": "#/$defs/Address" }, { "type": "null" } ], "description": "Visiting/registered office." }, "postal_address": { "anyOf": [ { "$ref": "#/$defs/Address" }, { "type": "null" } ], "description": "Postal address." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Website as registered." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Contact email as registered." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "Contact phone as registered." }, "advertising_protected": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Advertising Protected", "description": "Whether the register marks this entity as protected against direct-marketing use (Danish CVR-loven § 19 'reklamebeskyttelse', Swedish 'reklamspärr'). True: the register marks it. False: the register publishes such a flag for this entity and it is not set. None: this register publishes no such flag at all — the default, and it must never default to False, since False asserts a claim about a register that made none. When True, a country module must also append a `notes` entry containing the phrase 'direct marketing' (case-insensitive) stating the protection — that phrase is the contract this model enforces (see the validator below) — because the marking is a legal condition of passing this record's contact details on, and it must travel with them." }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Identifier of the parent/owning entity, if any." }, "is_subunit": { "type": "boolean", "title": "Is Subunit", "description": "True when this record is a branch/sub-unit, not a legal entity.", "default": false }, "in_group": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "In Group", "description": "Part of a corporate group." }, "last_annual_accounts_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Annual Accounts Year", "description": "Most recent financial year for which accounts were filed." }, "published_deadlines": { "items": { "$ref": "#/$defs/PublishedDeadline" }, "type": "array", "title": "Published Deadlines", "description": "Filing dates the upstream register publishes for this entity itself, carried verbatim. Empty for a register that publishes none — most of them. This is the input `Registry.deadlines(report, today)` needs to prefer the register's own figure over any calculation (DECISIONS.md D-018), and it is what keeps that method the pure function of (report, today) its contract promises." }, "lei": { "anyOf": [ { "$ref": "#/$defs/LeiRecord" }, { "type": "null" } ], "description": "This entity's Legal Entity Identifier record, from GLEIF — not a national register (D-026(c), D-045(e)). `None` unless `lei` was passed in `include=[...]` — and, even then, `None` if that fetch failed (see `notes` for why). A country that declares this attachment (`CountryInfo.supported_includes`) returns a *present* block even for an entity GLEIF holds no LEI for: `LeiRecord.lei` is `None` inside it, which is a real answer, never the same as this field being absent (D-011). Declared by default by every country whose identifiers cannot be a natural person's (`Registry.universal_includes`) — Sweden does not declare it, because GLEIF is a third-party host queried by identifier in a URL query string." }, "parents": { "anyOf": [ { "$ref": "#/$defs/ParentBlock" }, { "type": "null" } ], "description": "Corporate parents from GLEIF Level 2 — accounting consolidation, not shareholding (see `ParentBlock`'s own docstring). `None` unless `parents` was passed in `include=[...]` — and, even then, `None` if that fetch failed (see `notes` for why). A country that declares this attachment returns a *present* block even for an entity GLEIF holds no LEI for at all, with `direct` and `ultimate` both `None`: GLEIF cannot hold Level 2 for an entity it has no Level 1 for, and that is the answer, not an absence (D-011). Declared by default by every country whose identifiers cannot be a natural person's (`Registry.universal_includes`, alongside `lei`) — Sweden does not declare it, for the same reason it does not declare `lei`." }, "charges": { "anyOf": [ { "$ref": "#/$defs/ChargeBlock" }, { "type": "null" } ], "description": "Registered charges (mortgages / security interests) against this entity. `None` unless `charges` was passed in `include=[...]` — and, even then, `None` if that fetch failed (see `notes` for which attachment and why). A country that declares this attachment (`CountryInfo.supported_includes`) returns a *present* block with an empty `charges` list for an entity that genuinely has none — the two states never collapse into each other (D-011, D-042(d))." }, "filings": { "anyOf": [ { "$ref": "#/$defs/FilingHistory" }, { "type": "null" } ], "description": "What this entity has filed with its register, and when. `None` unless `filings` was passed in `include=[...]` — and, even then, `None` if that fetch failed (see `notes` for which attachment and why). Scope differs by country because each register publishes a different subset, and the block's own `notes` says which: Companies House the whole filing history, Bolagsverket the filed annual reports, Regnskapsregisteret the filed annual accounts. A *present* block with `documents: []` means the register lists none — never the same as absent (D-011, D-042(d))." }, "insolvency": { "anyOf": [ { "$ref": "#/$defs/InsolvencyBlock" }, { "type": "null" } ], "description": "Insolvency proceedings the register publishes against this entity. `None` unless `insolvency` was passed in `include=[...]`, or that fetch failed. A *present* block with `cases: []` means the register publishes no case, which for Companies House is the normal answer for a solvent company — and is not evidence the entity exists, since that register answers the same way for a number never issued. Read `InsolvencyCase.is_liquidation` with its own caveat: a members' voluntary liquidation is a solvent wind-up." }, "financials": { "anyOf": [ { "$ref": "#/$defs/FinancialSummary" }, { "type": "null" } ], "description": "Key figures from this entity's filed annual accounts. `None` unless `financials` was passed in `include=[...]` — and, even then, `None` if that fetch failed (see `notes` for which attachment and why). Norway returns a *present* block with `periods: []` for an entity Regnskapsregisteret holds no filed accounts for. Sweden instead returns *no block at all*, plus a report-level `notes` sentence naming the reason, because Bolagsverket's digital annual-report channel holds nothing for that entity — a fact about the company, not about the country (D-042(d)(3), `tasks/T55.md`). Norway and Sweden today: Norway's arrive in the register's own open key-figures feed, Sweden's are read out of the entity's own filed annual report. Britain does not declare this attachment because the accounts of the companies that matter are filed on paper or as PDF ahead of the 1 April 2028 machine-readable mandate — a fact about the register's own population, not a parser this project has declined to write (D-043(i), D-047(f))." }, "peppol": { "anyOf": [ { "$ref": "#/$defs/PeppolParticipant" }, { "type": "null" } ], "description": "Whether this entity can be reached over the Peppol e-invoicing network. `None` unless `peppol` was passed in `include=[...]` — and, even then, `None` only if the attachment could not be built at all (see `notes` for why). A country that declares this attachment returns a **present** block even when the network could not be reached: `PeppolParticipant.registered` carries the three-state answer (`true`/`false`/`null`) and `PeppolParticipant.participant_id` is always populated, because that is the key a caller needs to ask elsewhere regardless (D-011, D-029(c)). Norway only, today (D-046(h)): the participant identifier needs a country's own ISO 6523 ICD and the answer's provenance is a different SMP per participant, neither of which generalises to `Registry.universal_includes` yet." }, "confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "description": "How sure we are this record is the entity the caller meant (D-005).", "default": 1.0 }, "confidence_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence Basis", "description": "Why that confidence, e.g. 'exact identifier lookup'." }, "cached": { "type": "boolean", "title": "Cached", "description": "True when served from our cache rather than a live fetch.", "default": false }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Fetched At", "description": "UTC timestamp of the live fetch this record came from." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Human-readable source name, e.g. 'Enhetsregisteret (brreg.no)'." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url", "description": "Direct URL of the upstream record, for citation." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "Licence of the upstream data, e.g. 'NLOD 2.0'." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Caveats an agent should surface to the user, plain English, one per item." } }, "additionalProperties": false, "type": "object", "required": [ "country", "registry", "id", "name" ], "$defs": { "Address": { "properties": { "lines": { "items": { "type": "string" }, "type": "array", "title": "Lines", "description": "Street or PO-box lines exactly as the registry supplies them." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code", "description": "Postal / ZIP code." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "Post town." }, "municipality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Municipality", "description": "Municipality name." }, "municipality_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Municipality Code", "description": "National municipality code, if the registry has one." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code", "description": "ISO-3166-1 alpha-2 country code of the address itself." }, "country_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Name", "description": "Country name as registered." } }, "additionalProperties": false, "type": "object", "title": "Address", "description": "A postal or visiting address, flattened to something an LLM can read.\n\n``lines`` keeps the registry's own street/box lines in order; the rest are\nparsed components where the registry provides them." }, "BalanceSheet": { "properties": { "fixed_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Fixed Assets", "description": "Fixed assets at period end (`sumAnleggsmidler`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "current_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Current Assets", "description": "Current assets at period end (`sumOmloepsmidler`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "total_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Assets", "description": "Total assets at period end (`sumEiendeler`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). One of only three fields present on every one of 573 observed filings. Compare with `total_equity_and_liabilities` (DECISIONS.md D-043(e)): the two disagree on 27 of 358 filings, and this block's own `notes` names the gap when they do; neither figure is edited, reconciled or dropped." }, "paid_in_equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Paid In Equity", "description": "Paid-in equity at period end (`sumInnskuttEgenkaptial` — the register's own spelling, not a typo in this field's description). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "retained_equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Retained Equity", "description": "Retained equity at period end (`sumOpptjentEgenkapital`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Equity", "description": "Total equity at period end (`sumEgenkapital`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "non_current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Non Current Liabilities", "description": "Non-current liabilities at period end (`sumLangsiktigGjeld`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Current Liabilities", "description": "Current liabilities at period end (`sumKortsiktigGjeld`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Liabilities", "description": "Total liabilities at period end (`sumGjeld`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). Carried exactly as the register states it, including negative: DECISIONS.md D-043(e) records real filings with a negative `sumGjeld` (e.g. -108,837), which is a filing the register relayed without validating, not a company fact this field corrects." }, "total_equity_and_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Equity And Liabilities", "description": "Total equity and liabilities at period end (`sumEgenkapitalGjeld`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). One of only three fields present on every one of 573 observed filings. See `total_assets` for the reconciliation note the two together can trigger." } }, "additionalProperties": false, "type": "object", "title": "BalanceSheet", "description": "Stocks at the period's last instant — Regnskapsregisteret's\n``eiendeler`` and ``egenkapitalGjeld``, the other of the two sub-objects on\na :class:`FinancialPeriod` (D-043(c)). See :class:`IncomeStatement` for why\nthe two are separate models rather than one flat one.\n\nEvery field is `None` or a whole-unit figure in :attr:`FinancialPeriod.currency`\n— never both `None` and zero at once, and never inferred from the other\n(D-043(f)). **No field here is a ratio or a verdict** — an equity ratio, a\ncurrent ratio and every similar derived figure are declined by D-043(e): the\nregister's own `total_assets` and `total_equity_and_liabilities` disagree\non 27 of 358 filings (7.5%), so a ratio built from this block would be a\nratio of two numbers the register itself does not vouch for jointly. The\none comparison this project makes is a `notes` sentence, never a number —\nsee :class:`FinancialSummary`." }, "Charge": { "properties": { "charge_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Charge Id", "description": "The register's own opaque handle for this charge; not fetchable through this API. `None` on an older filing that predates the register assigning one — 19 of 110 items observed, all pre-2013 — honestly absent, not guessed." }, "charge_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Charge Number", "description": "The register's own sequence number for this charge, scoped to this company only: not unique across companies, and not a lookup key." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "The register's own word, verbatim, e.g. \"outstanding\", \"fully-satisfied\" — national vocabulary lives here, in the value, never in a field name (D-042(g)). See `is_outstanding` for the country-neutral derived flag." }, "is_outstanding": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Outstanding", "description": "Derived from `status` by membership of a country module's own committed table of status words it has actually observed on the wire. `None` when `status` is absent or is a word not yet in that table — never guessed, never `False` by default (D-025(d), D-011)." }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Classification", "description": "What kind of instrument this is, in the register's own prose — not a code, and not the same field as `FiledDocument.type_code`." }, "created_on": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Created On", "description": "The date the *charge instrument* was created — not a record timestamp. See `delivered_on` for the date it reached the register; the gap between the two is the Companies Act 2006 s.859A window a charge must be delivered within to be registered at all." }, "delivered_on": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Delivered On", "description": "The register's own receipt date: when the charge was delivered to the register for registration, which is not the same date as `created_on`. The interval between them is the Companies Act 2006 s.859A window a charge must be delivered within to be registered at all." }, "satisfied_on": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Satisfied On", "description": "The date the register recorded this charge as satisfied, exactly as published. `None` while outstanding — see `status` for the register's own word and `is_outstanding` for the derived flag." }, "assets_charged": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assets Charged", "description": "The register's own free-text description of what is charged, relayed verbatim and uncapped. It may contain particulars of property, account details or a natural person's name (e.g. a guarantor): never a lookup key, never indexed, never searchable and never reaches a log line (D-028(1), D-040) — the same binding `parties_entitled` carries. See `assets_charged_type` for the register's own category token this text is filed under." }, "assets_charged_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assets Charged Type", "description": "The register's own category token for `assets_charged`, verbatim: `short-particulars` or `brief-description` are the two seen on Companies House's `particulars.type` — two different kinds of text under one field name, which this token disambiguates. National vocabulary lives here, in the value, never in the field name (D-042(g))." }, "obligations_secured": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Obligations Secured", "description": "The register's own free-text description of what the charge secures, relayed verbatim and uncapped, under the same binding as `assets_charged` (D-028(1), D-040): never a lookup key, never indexed, never searchable, never reaches a log line. See `obligations_secured_type` for the register's own category token — on every observed item that carried one (19 of 19) it was `amount-secured`, never `obligations-secured`, so this field's name is a category the token disambiguates, not a description every value matches." }, "obligations_secured_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Obligations Secured Type", "description": "The register's own category token for `obligations_secured`, verbatim from Companies House's `secured_details.type`. Observed as `amount-secured` on 19 of 19 items that carried a token at all — `obligations_secured` itself has never once carried an `obligations-secured` value, which is exactly why this token, not the field's name, is the category. National vocabulary lives here, in the value, never in the field name (D-042(g))." }, "contains_fixed_charge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Contains Fixed Charge", "description": "Whether Companies House marks this instrument as including a fixed charge. The register emits this key **only when `True`**: absence means the register did not mark this instrument, never that it lacks one, and must never be read or stored as `False` (D-011). Norway's Løsøreregisteret and Sweden's företagsinteckningar use different taxonomies for security interests, so a future filler for either may leave this `None` on every item it fills, forever — the same shape as `FiledDocument.days_from_fee_point`." }, "contains_floating_charge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Contains Floating Charge", "description": "Whether Companies House marks this instrument as including a floating charge. The register emits this key **only when `True`**: absence means the register did not mark this instrument, never that it lacks one, and must never be read or stored as `False` (D-011). Norway's Løsøreregisteret and Sweden's företagsinteckningar use different taxonomies for security interests, so a future filler for either may leave this `None` on every item it fills, forever — the same shape as `FiledDocument.days_from_fee_point`." }, "contains_negative_pledge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Contains Negative Pledge", "description": "Whether Companies House marks this instrument as including a negative pledge — a covenant restricting further charges over the same assets, and, on its own, a fact a lender changes behaviour on. The register emits this key **only when `True`**: absence means the register did not mark this instrument, never that it lacks one, and must never be read or stored as `False` (D-011). Norway's Løsøreregisteret and Sweden's företagsinteckningar use different taxonomies for security interests, so a future filler for either may leave this `None` on every item it fills, forever — the same shape as `FiledDocument.days_from_fee_point`." }, "parties_entitled": { "items": { "type": "string" }, "type": "array", "title": "Parties Entitled", "description": "Names exactly as the register publishes them for the party or parties the charge is entitled to (typically a bank, an insurer or a trustee company; occasionally a natural person, e.g. a director lending to their own company). This is a term of the company's own instrument, not a person record: it is never a lookup key, never indexed, never searchable and never reaches a log line (D-028(1), D-040) — the same binding `assets_charged` and `obligations_secured` carry, because free prose describing charged property can also name a guarantor or a charged dwelling. It is deliberately not named the register's own `persons_entitled` — that name asserts a natural person; this one does not." } }, "additionalProperties": false, "type": "object", "title": "Charge", "description": "One registered charge (a mortgage or other security interest) against\nan entity — one row of a `ChargeBlock`.\n\nField names are country-neutral (D-042(g)): GB is the first filler\n(Companies House `/company/{n}/charges`, `registries/gb/__init__.py`),\nand any future filler (e.g. Norway's Løsøreregisteret, once it opens a\npublic API) maps onto this same shape rather than getting one of its own.\n\n**The field list is ruled by D-045(a)**, not by D-042(h) — which rules\n`FiledDocument` and no charge shape at all. D-045(a) accepts the names\nthis class started with, corrects the `created_on` / `delivered_on` /\n`satisfied_on` descriptions, and adds `contains_fixed_charge` and\n`contains_negative_pledge` beside `contains_floating_charge`, all three of\nwhich Companies House emits **only when true** — so an absent flag means\nthe register did not mark this instrument, never that it lacks one, and\nnever `False` (D-011). It also adds `assets_charged_type` and\n`obligations_secured_type`, the register's own category token for each\nfree-text field (S-series finding 7, D-042(e)(3)'s `persons_entitled`\ntreatment reused twice over)." }, "ChargeBlock": { "properties": { "charges": { "items": { "$ref": "#/$defs/Charge" }, "type": "array", "title": "Charges", "description": "Sorted newest first (a country module's own tie-break rule)." }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "The register's own count of charges for this company, which may exceed `len(charges)` — see `notes` for a truncation disclosure when it does." }, "satisfied_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Satisfied Count", "description": "The register's own whole-company count of satisfied charges, verbatim." }, "part_satisfied_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Part Satisfied Count", "description": "The register's own whole-company count of charges it marks partially satisfied, identical in kind to `total_count` and `satisfied_count`. `None` when the register does not publish it. Observed as `0` in every fixture this project has seen — this project has never observed a non-zero value — and the count is the register's own; it is not derived from anything else on this block." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block was fetched." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block: truncation when `total_count` exceeds `len(charges)`, and — whenever any charge on this page carries free text in `assets_charged` or `obligations_secured` — a disclosure that the text is the register's own prose, relayed verbatim and not parsed, and may name a natural person or carry an account identifier." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "ChargeBlock", "description": "Registered charges for one entity — an `include=[\"charges\"]` attachment\n(D-042(g), D-045(a)), never a plain field on `CompanyReport` (D-041(c)):\nit is a second round trip with its own moment, its own cache state and its\nown failure mode, so it carries its own `SourceRef` rather than reusing\nthe report's.\n\n**The count fields are ruled by D-045(a)**, not by D-042(h). It strikes\n`outstanding_count` — `total_count - satisfied_count` was our arithmetic\nwearing a register figure's name, and on a shared model it would have\nmeant \"outstanding\" for a register with no partially-satisfied state and\n\"not fully satisfied\" for one that has it (D-011) — and adds the\nregister's own `part_satisfied_count` in its place: a whole-company\nfigure Companies House publishes directly, `0` in every fixture observed\nso far, and not derived from anything else on this block.\n\nTwo-level nullability is the point of this shape (D-026(c), D-041(c),\nD-042(d)(3)): `CompanyReport.charges` is `None` when `charges` was not in\n`include`, or when the fetch failed (`Registry.lookup_with` appends a\n`notes` sentence on the report saying which). Once *present*, this block\ncarries `charges: []` for an entity the register confirms has none —\nthat case must never collapse into the absent case, and must never be\n`not_found` (D-011)." }, "CompanyStatus": { "type": "string", "enum": [ "active", "under_liquidation", "under_compulsory_liquidation", "bankrupt", "dissolved", "deleted", "unknown" ], "title": "CompanyStatus", "description": "Normalised lifecycle status of a registered entity.\n\nThe mapping from national flags to these values is the registry module's\njob; the values themselves are country-neutral so an agent can branch on\nthem without knowing which country it is looking at.\n\nPrecedence when several national flags are true is defined per registry\n(for Norway: ``deleted`` > ``bankrupt`` > ``under_compulsory_liquidation``\n> ``under_liquidation`` > ``active``)." }, "FiledDocument": { "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "The `Deadline.kind` slug this filing discharges, or `None` when it discharges none. This is the one field that is *derived* rather than relayed, and it is derived only by a committed per-country table of category words actually observed on the wire. A filing whose category is outside that table gets `None` rather than an invented slug (D-009): a filing that discharges no deadline this product publishes says so honestly." }, "period_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period End", "description": "The reporting period's last day, exactly as the register published it. Beware what the period belongs to: on an annual-accounts filing it is the date the accounts were made up to, but a register may publish a made-up date on other filing kinds too — a British confirmation statement carries one, and it is not a financial year end. Read it together with `kind`. `None` on the great majority of filings, which have no reporting period at all." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "The reporting period's first day, as published. `None` wherever the register publishes no counterpart to `period_end` — deriving one would assert a period length the register never stated, and a first, shortened or extended accounting period is lawful and common (D-009). Norway's Regnskapsregisteret publishes `regnskapsperiode: {fraDato, tilDato}` and fills both ends; Companies House publishes only the end; so does Sweden's Bolagsverket, whose bokföringslagen 3 kap. 3 § permits an 18-month first or final period — exactly the period length a subtracted twelve months would falsely assert." }, "filed_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Filed At", "description": "When the register recorded this filing, verbatim. This is the field that makes the block answer *does this company file on time*, and it is the sort key for `FilingHistory.documents`: newest first." }, "days_from_fee_point": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days From Fee Point", "description": "Signed days from a named late-fee datum to `filed_at`, **only where the register itself publishes such a datum for that period**. Negative is early. `None` is the common answer and means the datum does not exist in the data, not that the arithmetic was skipped. Sweden's Bolagsverket fills it: årsredovisningslagen 8 kap. 6 § starts a förseningsavgift of 7 500 kr (15 000 kr for a public company) at that datum. It is **not** the company's own filing deadline — ÅRL 8 kap. 3 § instead requires filing within one month of the general meeting that adopts the accounts — and a nine-month variant of 8 kap. 6 § cannot be excluded, because the dataset does not identify which companies it applies to. Companies House publishes only the *next* period's due date — `accounts.next_accounts.due_on` and `confirmation_statement.next_due` on the company profile — and no per-period historical due date at all, so there is nothing to measure a past filing against without guessing a 9-month or 6-month period and presenting the guess as the register's own — the invented figure D-009 forbids." }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id", "description": "The register's own opaque handle for this filing, relayed verbatim and never interpreted. **Not fetchable through this API**: the filed document itself lives behind a separate host, which is a second upstream with its own provenance and out of scope for this block (D-041(c)). It is the key a support case with the register can name. Norway's payload also carries an integer `id`, an internal row identifier, which is not relayed." }, "file_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Format", "description": "What the register holds the document as, where it says. `None` where the filing-history endpoint publishes no format: Companies House's filing-history endpoint publishes only a page count and a `paper_filed` marker, no media type — the media type itself lives on a separate document host, a second fetch this block does not make." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "The register's own category for this filing, verbatim and never translated. It is the field `kind` is derived from. Twenty-two words observed live in Britain, and the list is not closed: \"accounts\", \"capital\", \"officers\", \"mortgage\", \"confirmation-statement\", \"annual-return\", \"resolution\", \"gazette\", \"incorporation\", \"address\", \"insolvency\", \"dissolution\", \"change-of-name\", \"persons-with-significant-control\", \"auditors\", \"miscellaneous\", \"historical\", \"restoration\", \"document-replacement\", \"change-of-constitution\", \"return\" and \"other\"." }, "type_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type Code", "description": "The register's own form code for this filing, verbatim: \"AA\", \"CS01\", \"AP01\", \"MR01\" and older forms such as \"288a\" and \"363s\" in Britain — 100 distinct codes across 1876 items observed live." }, "description_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description Code", "description": "The register's own description-template key, verbatim and **never resolved into prose**. This is the key and not the sentence on purpose, and the reason is the whole design of this block: Companies House resolves these templates from a `description_values` object, 97 templates interpolate an officer's name and 26 a person with significant control's, so the resolved sentence is personal data while the key is not. **The key says what happened; only the values say who** (D-042(e)(1), D-028)." } }, "additionalProperties": false, "type": "object", "title": "FiledDocument", "description": "One filing a national register publishes for one entity — one row of a\n:class:`FilingHistory`.\n\nThe shape ``DECISIONS.md`` D-041(d) ruled and D-042(h) widened, and it is\ncountry-neutral by construction rather than by intent: Britain, Sweden and\nNorway each built this model independently behind their own seam, and all\nthree arrived field-for-field at this one. National vocabulary lives in the\n*values* (`category`, `type_code`, `description_code`), never in a field\nname (D-042(g)).\n\nEvery field is nullable and every `None` means the same thing: **the\nregister does not publish it** (D-011). It never means zero, never means\n\"no\", and is never filled by derivation — a register that does not publish\na period start gets `None`, not a start inferred by subtracting twelve\nmonths from the end (D-009)." }, "FilingHistory": { "properties": { "documents": { "items": { "$ref": "#/$defs/FiledDocument" }, "type": "array", "title": "Documents", "description": "One page of the register's own filing history, newest first by the register's own period or filing date: Britain sorts by `filed_at`; Sweden by `period_end` then `filed_at`; Norway by `period_end` then `period_start`. Never paginated further; when the register holds more, `total_count` says how many and `notes` says so in words. Empty means the register lists none — not that we could not look." }, "financial_year_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Financial Year End", "description": "The latest reporting period among this entity's filed **annual accounts** (`kind == \"annual_accounts\"`), carried verbatim — never a synthesised month-day, and never taken from a filing of another kind that happens to carry a made-up date of its own. It is the latest *period*, not the period of the latest *filing*, because a register may accept a later filing that amends an earlier year and that would otherwise roll this date backwards. It is **evidence of** the entity's accounting reference date, not a statement of it. `None` when this page holds no annual-accounts filing with a reporting period, including when older accounts exist further back than the page reaches." }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "The register's own count of filings for this entity, which may greatly exceed `len(documents)` — 8371 against a 25-row page, for one company observed live. **`None` means the register published no count**, not zero, and for Companies House it additionally distinguishes a real zero from a number whose filing history the register cannot serve at all: that endpoint returns `0` for both, and relaying the second as a zero would assert something the register never said (D-011). `notes` names which case it was." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block was fetched." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block: which subset of filings this register publishes, truncation when `total_count` exceeds `len(documents)`, and which empty state an empty `documents` is." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "FilingHistory", "description": "What one entity has filed with its national register — an\n``include=[\"filings\"]`` attachment (D-041(d), D-042), never a plain field\non :class:`CompanyReport` (D-041(c)): it is a second round trip with its\nown moment, its own cache state and its own failure mode, so it carries its\nown :class:`SourceRef` rather than reusing the report's.\n\nAll three live countries declare it, and each answers a differently-scoped\nquestion its register actually supports — Companies House returns the whole\nfiling history, Bolagsverket the filed annual reports, Regnskapsregisteret\nthe filed annual accounts. `notes` says which, in words, on every block.\n\nTwo-level nullability is the contract (D-011, D-026(c), D-041(c)):\n**absent** means \"you did not ask, or the fetch failed\" — `lookup_with`\nappends one `notes` sentence to the report saying which — while **present\nwith `documents: []`** means \"the register lists no filings for this\nentity\", a real and useful answer about a counterparty that must never be\nrendered as an absence." }, "FinancialPeriod": { "properties": { "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "The reporting period's first day, as published (`regnskapsperiode.fraDato`). Real, published data — never derived by subtracting twelve months from `period_end`, because a first or final period may be shorter or longer (DECISIONS.md D-009)." }, "period_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period End", "description": "The reporting period's last day, as published (`regnskapsperiode.tilDato`). Equal to the sibling `FiledDocument.period_end` for this filing on the same report (DECISIONS.md D-043(h))." }, "currency": { "type": "string", "title": "Currency", "description": "ISO-4217-shaped currency code, verbatim from `valuta`. **Required — this field has no default, and a period the register published with no currency is not constructed at all** (DECISIONS.md D-043(d)): a figure without its currency is not partially wrong, it is meaningless, and this model makes that state unrepresentable rather than merely discouraged. 12 of 358 observed Norwegian filings are not in kroner (USD, EUR, SEK, DKK), so two *Norwegian* companies can be incomparable without either crossing a border. Values are whole units of this currency; scale (thousands, millions) is not recorded because the register does not publish one, and the figures are exact integers that are not significant to that precision." }, "accounting_framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accounting Framework", "description": "The accounting framework this period was prepared under, verbatim from `regnkapsprinsipper.regnskapsregler` — observed values include 'regnskapslovenAlminneligRegler', 'IFRS' and 'forenkletAnvendelseIFRS'. Two Norwegian companies' figures are not necessarily on the same basis; no field here converts between them (DECISIONS.md D-043(d))." }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope", "description": "What this filing covers, the register's own word, verbatim from `regnskapstype` — 'SELSKAP' (company accounts) is the only value observed in 573 payloads; 'KONSERN' (consolidated) is implied by the vocabulary but was never seen. See `consolidated` for the country-neutral derived flag." }, "consolidated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Consolidated", "description": "Whether this filing is a consolidated (group) statement, derived from `scope` by a committed table of words this module has actually observed on the wire — today only `{'SELSKAP': False}`. A word outside that table, including an implied-but-unobserved 'KONSERN', gets `None`, never `False` (DECISIONS.md D-011, D-025(d)): this field never guesses." }, "small_entity": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Small Entity", "description": "Whether this filing was prepared under the reduced-disclosure regime for a *lite foretak* (regnskapsloven § 1-6), from `regnkapsprinsipper.smaaForetak`. **Not a distress signal** — True on 315 of 358 observed filings, the majority case — it is a disclosure caveat: fewer figures exist, and those that do were prepared under rules that permit simplification." }, "audit_exempt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Audit Exempt", "description": "Whether the company has resolved to opt out of audit under aksjeloven § 7-6, from `revisjon.fravalgRevisjon` — lawful below that section's thresholds and True on 65 of 358 observed filings (18%). The consequence a credit decision must weigh: no independent auditor checked these figures." }, "unaudited": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Unaudited", "description": "Relayed uninverted from `revisjon.ikkeRevidertAarsregnskap`, which its own name claims means these accounts were not audited. **`True` was never observed** in 573 sampled payloads, including every filing by a company that had opted out of audit under `audit_exempt` — so this flag's semantics are unverified: do not read a `False` here as an assertion that the accounts were audited, and do not read this field as more reliable than `audit_exempt` (DECISIONS.md D-043(g))." }, "liquidation_basis": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Liquidation Basis", "description": "Whether this filing is an *avviklingsregnskap* under aksjeloven § 16-10 — a winding-up account prepared on a realisation rather than a going-concern basis, over a final stub period — from `avviklingsregnskap`. Rare (3 of 215 entities the register marks `underAvvikling`) and, when true, real: read `FinancialSummary.notes` for the caveat this triggers. It does not restate the winding-up itself, which `CompanyReport.status` already carries." }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id", "description": "The register's own opaque handle for this filing, verbatim from `journalnr` — the same handle the sibling `FiledDocument.document_id` on `filings` carries for the same filing, and the join key between the two blocks (DECISIONS.md D-043(h)). Not fetchable through this API." }, "income_statement": { "anyOf": [ { "$ref": "#/$defs/IncomeStatement" }, { "type": "null" } ], "description": "Flows for this period. `None` when the register published no line in this statement at all for this filing; otherwise present with whichever lines it published, each individually nullable (DECISIONS.md D-043(f))." }, "balance_sheet": { "anyOf": [ { "$ref": "#/$defs/BalanceSheet" }, { "type": "null" } ], "description": "Stocks at this period's last instant. `None` when the register published no line in this statement at all for this filing; otherwise present with whichever lines it published, each individually nullable (DECISIONS.md D-043(f))." } }, "additionalProperties": false, "type": "object", "required": [ "currency" ], "title": "FinancialPeriod", "description": "One filed accounting period's key figures, mapped a second time\nalongside :class:`~registry_mcp.core.models.FiledDocument` for the same\nfiling (D-043(h), D-047(f)). For Norway the two come from the same\nfetch; for Sweden `financials` shares `filings`' document-list discovery\nstep but then reads the filed document itself, a further fetch `filings`\nnever makes. Either way, `document_id` and `period_end` are the join\nkeys a caller uses to line this period up with its sibling\n`FiledDocument`.\n\n`currency` is the one field in this whole block with no default\n(DECISIONS.md D-043(d)): a figure separated from its currency is not\npartially wrong, it is meaningless, and this model makes constructing one\na `pydantic.ValidationError` rather than a silently-`None` currency. A\nperiod the register published with no `valuta` is not carried at all —\nthe mapper skips it and says why in `FinancialSummary.notes` — which is\nsafe because `valuta` was present on 573 of 573 payloads this project has\nread." }, "FinancialSummary": { "properties": { "periods": { "items": { "$ref": "#/$defs/FinancialPeriod" }, "type": "array", "title": "Periods", "description": "Filed accounting periods, sorted newest first by `period_end`. Both registers carry exactly one today, for different reasons: Regnskapsregisteret publishes only one — the endpoint takes no year argument and holds no history — while Bolagsverket lists every filed annual report but only the most recent is parsed into this block, a bounded-cost choice rather than a register limit (DECISIONS.md D-047(f)). Either way this is a latest-figures block, not a trend; `notes` says so on every non-empty block, and the rest of a Swedish entity's filed reports are in `include=[\"filings\"]`. The list exists for a register that publishes more than one." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block was fetched. For Norway, **identical in all five fields to the sibling `filings` block's `provenance` when both are requested together**: they are the same upstream fetch, not two (DECISIONS.md D-043(h)). For Sweden the two blocks' `provenance` are **not** identical: `financials` shares `filings`' document-list discovery fetch to decide what to fetch, but then makes its own further request for the document itself, and this field describes that further request, not the shared list (DECISIONS.md D-047(f))." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block. Unconditional on any non-empty block: that figures are denominated in the stated currency and framework and are not comparable across companies or borders without regard to both, and that this is the latest filed period rather than a history. Conditional: a reconciliation note when `total_assets` and `total_equity_and_liabilities` disagree, a non-NOK currency note, and one note each for `small_entity`, `audit_exempt`, `liquidation_basis` and an observed `unaudited` (DECISIONS.md D-043(e),(g))." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "FinancialSummary", "description": "Key figures from an entity's filed annual accounts — an\n``include=[\"financials\"]`` attachment (DECISIONS.md D-043), never a plain\nfield on :class:`CompanyReport` (D-041(c)): it is a second round trip with\nits own moment, its own cache state and its own failure mode, so it\ncarries its own :class:`SourceRef` rather than reusing the report's.\n\n**A second block, not a wider `FiledDocument`** (D-043(b)): \"did they file\non time\" and \"what do the numbers say\" are two different questions, and\nfolding nineteen numeric fields onto `FiledDocument` would collapse two\nmeanings into one `None` — \"Britain does not publish this\" and \"this\nNorwegian company did not report this line\" — which D-011 forbids.\n\nNorway and Sweden fill this block today, from two different sources:\nNorway's figures arrive in Regnskapsregisteret's own open key-figures\nfeed, the same fetch as `filings`; Sweden's are read out of the entity's\nown filed annual report (the K2 inline-XBRL document Bolagsverket's\ndocument API serves), a second request that shares its document-list\ndiscovery step with `filings` but is not the same fetch (DECISIONS.md\nD-047(f)). Britain does not fill this block, and that is the register's\nown population, not a scope decision this project made: the accounts of\nthe companies that matter are filed on paper or as PDF, the\nmachine-readable (iXBRL) mandate is 1 April 2028 with a\nprofit-and-loss publication opt-out for small and micro companies, and\nno British filing sampled carried the balance-sheet totals this block\nrelays (DECISIONS.md D-043(i), as amended by D-047(f)).\n`include=[\"financials\"]` on a country that does not declare it is\n`bad_request`, never a silently empty block.\n\nTwo-level nullability is the point of the shape (D-011, D-026(c),\nD-041(c), D-042(d)(3)): once *present*, this block carries `periods: []`\nfor an entity Regnskapsregisteret holds no filed accounts for — that\nstate must never collapse into the absent state and must never be\n``not_found``. **No field on this block or on `FinancialPeriod` is a\nderived ratio, indicator or verdict** — DECISIONS.md D-043(e) rules out an\nequity ratio, a current ratio, a net-debt figure, a working-capital\nfigure and every similar field on three independent grounds, the\nstrongest being that the register relays filings whose own totals do not\nreconcile on 27 of 358 observed filings. The one comparison this project\nmakes is a `notes` sentence, never a number: see `notes` below." }, "IncomeStatement": { "properties": { "revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Revenue", "description": "Turnover for the period (`sumDriftsinntekter`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). Absent on 51 of 358 observed filings (14%) — not rare." }, "operating_costs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Operating Costs", "description": "Total operating costs for the period (`sumDriftskostnad`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "operating_result": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Operating Result", "description": "Operating result for the period (`driftsresultat`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "financial_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Financial Income", "description": "Financial income for the period (`sumFinansinntekter`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "financial_costs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Financial Costs", "description": "Financial costs for the period (`sumFinanskostnad`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "net_financial_items": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Net Financial Items", "description": "Net financial items for the period (`nettoFinans`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "profit_before_tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Profit Before Tax", "description": "Ordinary result before tax (`ordinaertResultatFoerSkattekostnad`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f))." }, "profit_for_period": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Profit For Period", "description": "Profit or loss for the period (`aarsresultat`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). One of only three fields present on every one of 573 observed filings." }, "total_comprehensive_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Comprehensive Income", "description": "Total comprehensive income for the period (`totalresultat`). `None` means the register did not publish this line for this filing — never zero. The register is inconsistent about when it states an explicit zero for an absent figure versus omitting the line entirely, so this field's absence is not evidence the true value is zero, and a stated zero is not evidence the register omits the line elsewhere (DECISIONS.md D-043(f)). Absent on 209 of 358 observed filings (58%) — the register's own line, not this project's omission." } }, "additionalProperties": false, "type": "object", "title": "IncomeStatement", "description": "Flows over one reporting period — Regnskapsregisteret's\n``resultatregnskapResultat``, one of two sub-objects on a\n:class:`FinancialPeriod` (D-043(c)). Nested apart from :class:`BalanceSheet`\non purpose: revenue is a flow over a span, not a stock at an instant, and a\ncaller who mixes the two time semantics makes precisely the error this\nsplit exists to prevent.\n\nEvery field is `None` or a whole-unit figure in :attr:`FinancialPeriod.currency`\n— never both `None` and zero at once, and never inferred from the other\n(D-043(f)); see `FinancialPeriod.currency` for what the unit is and why it\nis required." }, "IndustryCode": { "properties": { "code": { "type": "string", "title": "Code", "description": "The code as published, e.g. '06.100'." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Registry's own description." }, "scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheme", "description": "Classification scheme, e.g. 'NACE' or the national variant name." }, "rank": { "type": "integer", "minimum": 1.0, "title": "Rank", "description": "1 = primary activity, 2 = second, and so on.", "default": 1 } }, "additionalProperties": false, "type": "object", "required": [ "code" ], "title": "IndustryCode", "description": "An industry classification code (NACE / SIC / national equivalent)." }, "InsolvencyBlock": { "properties": { "cases": { "items": { "$ref": "#/$defs/InsolvencyCase" }, "type": "array", "title": "Cases", "description": "Every insolvency case the register publishes for this entity — the whole history, not a page, where the register's endpoint is unpaginated. Sorted newest first by the case's most recent event date, then by `case_number` descending; cases the register gives no date for sort last." }, "statuses": { "items": { "type": "string" }, "type": "array", "title": "Statuses", "description": "The register's own entity-level insolvency status words, verbatim — national vocabulary in values (D-042(g)). Eight observed live in Britain: \"in-administration\", \"liquidation\", \"receivership\", \"receiver-manager\", \"administrative-receiver\", \"administration-order\", \"voluntary-arrangement\" and \"live-receiver-manager-on-at-least-one-charge\". An **empty list means the register publishes no such word for this entity**, which is not the same as 'not currently insolvent': about one in ten companies whose Companies House status is itself an insolvency status still has no word here. No yes/no flag is derived from this field for exactly that reason (D-011)." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block was fetched." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block: which of the register's two empty states this is, that practitioner particulars exist upstream and are deliberately not relayed, and any note code withheld by the allow-list." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "InsolvencyBlock", "description": "Insolvency proceedings a register publishes against one entity — an\n``include=[\"insolvency\"]`` attachment (D-042), never a plain field on\n:class:`CompanyReport` (D-041(c)), and carrying its own :class:`SourceRef`.\n\nTwo-level nullability is the point of the shape (D-011, D-026(c),\nD-041(c), D-042(d)(3)): once *present*, this block carries ``cases: []``\nfor an entity the register publishes no insolvency case for — that state\nmust never collapse into the absent state and must never be ``not_found``.\nCompanies House's 404 here is the *normal* answer for a solvent company and\nis byte-identical to its answer for a number that was never issued, so it\nsays nothing about whether the entity exists; ``notes`` therefore\ndistinguishes \"the register holds no insolvency resource here\" from \"the\nresource exists and is empty\" instead of flattening both into silence." }, "InsolvencyCase": { "properties": { "case_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Case Number", "description": "The register's own identifier for this case, verbatim. For Companies House this is a per-company sequence number rendered as a string (\"1\", \"2\", … up to \"31\" in the live sample) and is **not** a court reference — it identifies the case only within this entity. Kept as a string because another register's case identifier need not be numeric." }, "case_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Case Type", "description": "The register's own word for the kind of procedure, verbatim — national vocabulary in the value (D-042(g)). Ten words observed live in Britain, among them \"compulsory-liquidation\", \"creditors-voluntary-liquidation\", \"members-voluntary-liquidation\" and \"in-administration\". See `is_liquidation` for the country-neutral derived flag." }, "is_liquidation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Liquidation", "description": "Whether this procedure is a winding-up — the country-neutral question behind the national word in `case_type`. Derived by membership of a committed table of words the country module has actually observed on the wire. `None` when `case_type` is absent or is a word not yet in that table — never guessed, never `False` by default (D-011, D-025(d)). **`True` does not mean insolvent**: a members' voluntary liquidation is a *solvent* winding-up, begun by a declaration of solvency, and 56 of the 1,485 live British cases behind this table were exactly that. Read it as 'the entity is being wound up', not as 'the entity cannot pay'." }, "events": { "items": { "$ref": "#/$defs/InsolvencyEvent" }, "type": "array", "title": "Events", "description": "The register's own dated steps in this case, newest first. Frequently empty — 172 of the 1,485 live British cases carried no date at all, most of them old receiverships — and an empty list means the register publishes no date for this case, never that nothing happened." }, "note_codes": { "items": { "type": "string" }, "type": "array", "title": "Note Codes", "description": "The register's own note **codes** for this case, verbatim and never resolved into prose — the same treatment D-042(e)(1) gives a filing's `description_code`. Only one code has ever been observed live: \"scottish-insolvency-info\", which means the Accountant in Bankruptcy's Register of Insolvencies holds further detail this API does not. Companies House declares this field an unbounded `array[string]`, so it is the one place in that payload a name could hide; codes are therefore relayed through an allow-list of observed codes, and an unrecognised one is dropped and disclosed in the block's `notes` rather than passed through." } }, "additionalProperties": false, "type": "object", "title": "InsolvencyCase", "description": "One insolvency case a register publishes against one entity.\n\n**No practitioner particular can land here.** A register commonly publishes\neach appointed practitioner's name and postal address alongside the case;\nD-042(e)(2) bars relaying them in the first tranche, so this model has no\nfield for them and no country mapper reads the key. Adding them later is a\ndecision with its own entry in ``DECISIONS.md``, inheriting D-028's four\npreconditions in full." }, "InsolvencyEvent": { "properties": { "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type", "description": "The register's own word for what happened, verbatim — national vocabulary lives here, in the value, never in a field name (D-042(g)). Thirteen words have been observed live in Britain: \"administration-started-on\", \"administration-ended-on\", \"administration-discharged-on\", \"instrumented-on\", \"petitioned-on\", \"wound-up-on\", \"concluded-winding-up-on\", \"voluntary-arrangement-started-on\", \"voluntary-arrangement-ended-on\", \"moratorium-started-on\", \"declaration-solvent-on\", \"due-to-be-dissolved-on\" and \"dissolved-on\" (the last of which Companies House's own published enumeration omits). A word outside the observed set is still relayed verbatim: this field is never filtered, only reported." }, "occurred_on": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Occurred On", "description": "The date the register gives for this event." } }, "additionalProperties": false, "type": "object", "title": "InsolvencyEvent", "description": "One dated step in an insolvency case, as the register itself records it.\n\nThese are the register's own events, not this service's interpretation of\nthem: D-042(e)(2) rules that case type, case number and *these* dated\nevents carry the entire distress signal a pre-contract check needs." }, "LeiRecord": { "properties": { "lei": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lei", "description": "The 20-character Legal Entity Identifier GLEIF publishes for this entity. `None` *inside a present block* means GLEIF holds no LEI for it — a real and useful answer about a counterparty, and not the same as this block being absent (D-026(c), D-011). The LEI is **not** the EUID — see `CompanyReport.euid`'s own description for that distinction rather than restating it here." }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name", "description": "The legal name as GLEIF publishes it, carried verbatim. May differ from `CompanyReport.name`, because the two are two registers' opinions recorded at two different moments — never reconciled against it and never used to correct the company record (D-018: say which source said what)." }, "registration_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Status", "description": "GLEIF's own `registration.status` for this LEI record, verbatim: 'ISSUED', 'LAPSED', … (national-vocabulary-in-values, D-042(g)). A 'LAPSED' LEI means the entity stopped renewing its registration and is **not** evidence of insolvency or inactivity — Carillion plc ('03782379') and Lehman Brothers International (Europe) ('02538254') both read `entity.status: ACTIVE` beside `registration.status: LAPSED`. This field carries the *registration's* status; GLEIF's `entity.status` is not carried at all, because it is a claim about the company made by neither the company's own register nor us." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block was fetched. `source` names GLEIF, `license` is 'CC0 1.0', and `source_url` is this record's own GLEIF URL. Never implies endorsement and never describes registry-mcp as a GLEIF service — GLEIF's anti-impersonation clause sits outside its data licence (D-026(c))." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block. Always names the exact string sent as GLEIF's `entity.registeredAs` filter, so a `lei: null` answer is legible rather than silent, and the register-authority code GLEIF cites for this entity. If GLEIF returned more than one record for this registration number, a sentence discloses how many and each LEI, rather than silently picking one." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "LeiRecord", "description": "The Legal Entity Identifier GLEIF (the Global LEI Foundation) publishes\nfor one entity — the ``include=[\"lei\"]`` attachment, D-026(c)'s shape,\nunamended by D-045(e). Unlike every other attachment, this upstream is\nnot any one country's own register: GLEIF publishes every jurisdiction\nfrom one endpoint, under one CC0 licence, with one TTL, so it is the\nfirst attachment every country declares by default\n(``Registry.universal_includes``, D-045(e)) rather than something a\ncountry module opts into.\n\nThe two-level nullability is D-026(c)'s and D-011's, restated here: an\n**absent** ``CompanyReport.lei`` means the attachment was not requested,\nor the fetch failed (a ``notes`` sentence on the report says which); a\n**present** block with ``lei=None`` means GLEIF holds no LEI for this\nentity, which is a real and useful answer about a counterparty and must\nnever be rendered as though nothing were known." }, "ParentBlock": { "properties": { "direct": { "anyOf": [ { "$ref": "#/$defs/ParentLink" }, { "type": "null" } ], "description": "The entity that directly consolidates this entity's accounts, or the reporting exception recorded for this side. `None` when GLEIF's relationships name neither a disclosed parent nor a reporting exception for this side (0 of 1,800 records sampled) or when a failed fetch degraded just this side (`notes` names the leg); see `ParentBlock`'s own docstring for the two other reasons this can be `None`." }, "ultimate": { "anyOf": [ { "$ref": "#/$defs/ParentLink" }, { "type": "null" } ], "description": "The entity at the top of the chain that ultimately consolidates this entity's accounts, or the reporting exception recorded for this side. Independent of `direct` — never derived from it, never reconciled against it." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "One `SourceRef` for the whole fan-out (D-046(d)), not one per side: `source` names GLEIF, `license` is 'CC0 1.0', `source_url` is 'https://api.gleif.org/api/v1/lei-records/{lei}' — the record every leg hangs off — and `fetched_at` is the moment the fan-out completed. The discovery search that finds this entity's LEI fills no field on this block; it is shared with `include=[\"lei\"]` and never repeated for a lookup that asks for both. Each side's own `source_url` names the exact leg that filled it. Never implies endorsement and never describes registry-mcp as a GLEIF service (D-026(c))." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats, always naming the URL(s) actually fetched — including, when GLEIF holds no LEI at all, a sentence saying so. Whenever either side carries a `reporting_exception`, also carries the 'this word is the filer's own, unverified and inconsistently applied' sentence, because a caveat that lives only in a schema description does not travel into a rendered answer. Also names the one thing lost by not modelling the disclosed relationship's own period history: its start date." } }, "additionalProperties": false, "type": "object", "required": [ "provenance" ], "title": "ParentBlock", "description": "Corporate parents from GLEIF Level 2 — the `include=[\"parents\"]`\nattachment (D-047(a)).\n\n**Three-level nullability**, restated for this block: an **absent**\n`CompanyReport.parents` means `parents` was not requested, or the fetch\nfailed (`notes` on the report says which). A **present** block whose\n`direct` and `ultimate` are both `None` means GLEIF holds **no LEI at\nall** for this entity — there is no Level 2 to hold either, and that is\nitself the answer, not an absence. A **present** block with `direct`\nand/or `ultimate` populated is the ordinary case, whether populated side\ndiscloses a parent or records why it did not.\n\n`direct` and `ultimate` are two independent sides that can disagree in\nkind — one disclosed, the other excepted, or two different parents.\n**Never collapse them and never derive one from the other**: in a\n600-record Swedish sample, 9 records disclosed a direct parent and 10\ndisclosed an ultimate one, so at least one record took different paths\non its two sides.\n\nThe sentence the whole block hangs on: **GLEIF Level 2 reports the\n*accounting consolidating* parent — the entity that consolidates this\nentity's accounts (wire word `IS_DIRECTLY_CONSOLIDATED_BY` /\n`IS_ULTIMATELY_CONSOLIDATED_BY`) — which is not the same as the majority\nshareholder, and neither implies the other.**" }, "ParentLink": { "properties": { "lei": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lei", "description": "The parent's own 20-character LEI, when GLEIF discloses a parent for this side. This is a lookup key **for GLEIF**, not for `lookup_company` — the caller cannot feed it a national identifier this project does not carry. To walk up a group from here, call `lookup_company` on the parent's own national identifier where the caller already has it. Norway additionally publishes `CompanyReport.parent_id` on the *first* round trip from Enhetsregisteret — a different register's answer to a neighbouring question, and it is not reconciled against this one (D-018)." }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name", "description": "The parent's legal name exactly as GLEIF publishes it, verbatim and never reconciled against `CompanyReport.name` or anything else. **Bound by D-028(1)**: never a lookup key, never an index, never searchable, never written to a log (D-040). The binding exists because GLEIF issues LEIs to sole proprietors too — 126,936 records carry an entity-level classification of `SOLE_PROPRIETOR`, whose legal name is routinely a natural person's name — and although no sole-proprietor *parent* was observed in a 30-record sample, nothing in GLEIF's Level 2 format forbids one." }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jurisdiction", "description": "The parent's own registered jurisdiction, ISO-3166-1 alpha-2, as GLEIF publishes it. May differ from this entity's own `CompanyReport.country`." }, "registration_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Status", "description": "The *parent's* own LEI registration status (`ISSUED`, `LAPSED`, …), carrying the same warning as `LeiRecord.registration_status`: a `LAPSED` LEI means the parent stopped renewing its own registration and is **not** evidence of insolvency — see that field's own description rather than restating it here." }, "corroboration_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Corroboration Level", "description": "GLEIF's own corroboration level for the *relationship* record, verbatim: `FULLY_CORROBORATED`, `PARTIALLY_CORROBORATED`, `ENTITY_SUPPLIED_ONLY`. Measured over 31 disclosed relationships: 10 / 11 / 10 — roughly a third of all disclosed parent links are the filer's own assertion that nobody has checked, which is the reason this field costs a second request. `None` on the exception side, where there is no relationship record." }, "reporting_exception": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reporting Exception", "description": "Why the entity did not report a parent on this side, from GLEIF's closed exception-reason vocabulary, relayed verbatim: `NO_LEI`, `NATURAL_PERSONS` ('the entity is controlled by a natural person(s) without any intermediate legal entity'), `NON_CONSOLIDATING` ('controlled by legal entities not subject to consolidation'), `NO_KNOWN_PERSON` ('no known person(s) controlling the entity, e.g. the entity is controlled by diverse shareholders'), `NON_PUBLIC`, and five values deprecated since 2022-03-01 and retained only for compatibility (`BINDING_LEGAL_COMMITMENTS`, `LEGAL_OBSTACLES`, `DISCLOSURE_DETRIMENTAL`, `DETRIMENT_NOT_EXCLUDED`, `CONSENT_NOT_OBTAINED`). Three things to hold onto reading it, all load-bearing: it is a **category word and never a name** — nothing beyond the word is available and nothing beyond it would be relayed if it were (D-028); it is the entity's **own stated reason**, verified by neither GLEIF nor us; and it is **not applied consistently between filers** — of 117 ultimate-parent exceptions sampled, `NATURAL_PERSONS` is 49 of 57 (86%) of Norwegian ones and 28 of 60 (47%) of British ones, and EQUINOR ASA (`OW6OFBNCKXC4US5C7523`), 67% owned by the Norwegian State, reads `NATURAL_PERSONS` while DNB, Telenor and Tesco — in the same position at the top of their own groups — read `NON_CONSOLIDATING`, and BP, Ericsson and Carillion read `NO_KNOWN_PERSON`. Treat `NATURAL_PERSONS` on a company with a known institutional owner as a filing artefact, not a fact about its owners." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url", "description": "The exact GLEIF URL that returned this side's own record — the parent's Level 1 record when disclosed, or the reporting-exception record when excepted. `ParentBlock.provenance` describes the fetch as a whole; this names the one leg that filled this side (D-046(d))." } }, "additionalProperties": false, "type": "object", "title": "ParentLink", "description": "One side (`direct` or `ultimate`) of a `ParentBlock` — either GLEIF\ndiscloses a corporate parent for this side, or the entity's own filer\nexplained why it did not (``include=[\"parents\"]``, D-047(a)).\n\n**Exactly one of `lei` and `reporting_exception` is populated — never\nboth, never neither** (enforced below, D-011: a link that discloses a\nparent's LEI and a link that records why no parent was disclosed are two\ndifferent facts and must not collapse into one).\n\nGLEIF Level 2 reports the *accounting consolidating* parent — the wire\nword is `IS_DIRECTLY_CONSOLIDATED_BY` / `IS_ULTIMATELY_CONSOLIDATED_BY` —\nwhich is **not** the same as the majority shareholder, and neither\nimplies the other." }, "PeppolParticipant": { "properties": { "participant_id": { "type": "string", "title": "Participant Id", "description": "The ISO 6523 participant identifier, `'0192:' + normalised orgnr` — `0192` is Norway's ICD (International Code Designator) inside the Peppol network. Derived offline from the identifier alone and **always populated, even when every lookup failed** (D-029(c)): it is the key a caller needs to ask elsewhere, regardless of what this block's own `registered` field says." }, "registered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Registered", "description": "Three states, and an agent branches on this field under a statute, so all three matter. `true`: the Peppol network answered for this participant — either the SMP the Peppol SML named for it served a ServiceGroup, or the Peppol Directory listed a match. `false`: **the authoritative SML/SMP route answered that it is not registered** — an NXDOMAIN resolving the Peppol SML, or a 404 from the SMP the SML named. Nothing else ever earns `false` (D-046(a)). `null`: we could not get an authoritative answer — a DNS resolver exception, a timeout, a NOERROR answer with no `Meta:SMP` record, an SMP error, **or the Peppol Directory simply not listing this participant**, which both Peppol operators state in writing means nothing: publication to the Directory is voluntary, and its own introduction page says a miss there 'doesn't mean the entity is not in the Peppol Network' (D-046(a))." }, "can_receive_invoice": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Can Receive Invoice", "description": "Whether this participant advertises the Peppol BIS Billing 3.0 Invoice document type or its PINT successor — DFØ's own equation: 'Peppol BIS billing v3.0 er det samme som EHF-faktura', which is exactly the 1 January 2027 question. Derived by **exact membership of a committed table of document type identifiers**, never by matching text, a substring or a version range. `true` when a table id is in `document_types` via the authoritative SMP route; also `true` via the Peppol Directory fallback, but a Directory list is a subset of the SMP's, so a Directory miss here is `null`, never `false` — see `document_types`. `false` only when `registered` itself is `false`. `null` when `registered` is `null`. **The SMP publishes a per-document-type ServiceActivationDate/ServiceExpirationDate that this block does not read** (one extra HTTP call per document type), so an advertised document type may be future-dated or already expired — `notes` says so whenever this is `true`." }, "document_types": { "items": { "type": "string" }, "type": "array", "title": "Document Types", "description": "The **document type** identifiers the answering SMP (or, on the Directory fallback, the Peppol Directory) advertises for this participant, full qualified `'::'` strings, e.g. `'busdox-docid-qns::urn:oasis:...:billing:3.0::2.1'`. **Not process identifiers** — those live one HTTP call deeper, per document type, and are not carried (D-046(e)). No cap and no truncation: the modal Norwegian participant lists two, some list many more. Only *receiving* capabilities are registered anywhere in the Peppol network, which is the right semantics for 'can this counterparty receive an e-invoice'." }, "smp_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Smp Url", "description": "The SMP base URL the Peppol SML named for **this participant**, verbatim. This varies per participant and is **never assumed**: the default national SMP a country's participants mostly resolve to is not the only one — a measured 1-in-43 Norwegian participants resolve to a different one entirely (D-046(b)). `null` when the SML never named a host for this participant (NXDOMAIN, or no usable `Meta:SMP` record)." }, "provenance": { "$ref": "#/$defs/SourceRef", "description": "Where, when and under what licence this block's answer was produced. `source` names the SMP host and route that answered (e.g. ' (Peppol SMP, via the Peppol SML)'), or the Peppol Directory named as an index that may lag — **derived at request time from what actually answered, never a constant** (D-046(b)). `license` carries D-046(g)'s stated absence: nobody publishes a licence for the Peppol SML, for any SMP or for the Peppol Directory. One `SourceRef` for the whole block even though up to two round trips were made (a DNS read and an HTTPS read): the DNS step only located the host and fills no field of this block except `smp_url`, so it is disclosed as that field rather than as a second provenance (D-046(d))." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "Plain-English caveats about this block. Always names which route answered (the SMP, or the Peppol Directory) or which step failed when `registered` is `null`; that only *receiving* capabilities are registered in the Peppol network; on the Directory route, that it is a voluntary, lagging index of the SMP; and, on a Directory miss, the operators' own statement that this does not mean the entity is not in the Peppol Network." } }, "additionalProperties": false, "type": "object", "required": [ "participant_id", "provenance" ], "title": "PeppolParticipant", "description": "Whether one entity can be reached over the Peppol network — the\n``include=[\"peppol\"]`` attachment (DECISIONS.md D-029(b), amended in full\nby D-046 after ``tasks/T48-recon.md`` read the wire). Norway-only today:\ndeclared by ``BrregRegistry.supported_includes``, not by\n:attr:`Registry.universal_includes` (D-046(h)) — the participant\nidentifier needs a country's own ISO 6523 ICD, the answer's provenance is\na *different SMP per participant* rather than one endpoint, and the\nlicence sentence below was earned by reading a Norwegian catalogue page.\n\nThe Peppol network is not Enhetsregisteret: the answering SMP is operated\nby a second organisation entirely (for Norway, Digitaliseringsdirektoratet\n— named in ``registries/no/peppol.py``, where national vocabulary belongs\nper D-004, never here), so this is a second round trip with its own\n:class:`SourceRef` rather than a field on :class:`CompanyReport` itself\n(D-026(c))." }, "PublishedDeadline": { "properties": { "kind": { "type": "string", "title": "Kind", "description": "The same machine slug the country module uses for the matching `Deadline.kind`, e.g. 'annual_accounts'. Unique within a report." }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Due Date", "description": "The date the register itself publishes for this filing. `None` when the register names a period but no date — the country module may still be able to compute one from `period_end`." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period this filing covers, if published." }, "period_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period End", "description": "Last day of the period this filing covers, if published. This, not an accounting reference date, is what a statutory period runs from." }, "overdue": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Overdue", "description": "The register's own overdue flag, if it publishes one. Corroboration only: it is computed against the register's today, not the caller's, so `Deadline.days_until < 0` is the authoritative answer." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Where the date came from upstream, e.g. 'accounts.next_accounts.due_on'. Opaque to core; the country module turns it into `applies_because` prose." } }, "additionalProperties": false, "type": "object", "required": [ "kind" ], "title": "PublishedDeadline", "description": "A filing obligation exactly as the *register itself* publishes it.\n\nThe counterpart to :class:`Deadline`, and deliberately much smaller.\n:class:`Deadline` is *ours*: computed, English-labelled, dated against a\ncaller-supplied ``today``. This is *theirs*: whatever the upstream register\nstates about the obligation, carried verbatim, with no interpretation and\nno arithmetic.\n\nIt exists because some registers do the filing arithmetic themselves and\npublish the answer — Companies House publishes\n``accounts.next_accounts.due_on`` and ``confirmation_statement.next_due``,\nwhich already account for accounting-reference-date changes, shortened and\nextended periods, and administrative extensions that no outside calculation\ncan see (``DECISIONS.md`` D-016(a), D-018). A registry whose upstream\npublishes such a date fills this list at lookup time, and its\n:meth:`Registry.deadlines` then merges: the published date wins, a\ncomputation fills the gaps. A registry whose upstream publishes nothing —\nBrønnøysundregistrene, and every register that only states the statute —\nleaves the list empty and loses nothing.\n\nNothing in ``core/`` interprets any field here. ``kind`` and ``source``\nare opaque strings owned by the country module; ``core`` only carries them\nacross the lookup → deadlines boundary so that\n``Registry.deadlines(report, today)`` can stay the pure function of\n``(report, today)`` that its contract promises." }, "SourceRef": { "properties": { "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Human-readable source name, e.g. 'GLEIF Level 1 (gleif.org)'." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url", "description": "Direct URL of the upstream record, for citation." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "Licence of the upstream data for this attachment's own fetch, e.g. 'CC0 1.0'. A block's licence is the register's own for that endpoint and may equal the base report's without being derived from it: Norway's Regnskapsregisteret accounts endpoint states no licence of its own, so the blocks it serves carry NLOD 2.0 — the same value the company record on the same host already carries." }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Fetched At", "description": "UTC timestamp of the live fetch this attachment came from." }, "cached": { "type": "boolean", "title": "Cached", "description": "True when this attachment was served from cache rather than a live fetch.", "default": false } }, "additionalProperties": false, "type": "object", "title": "SourceRef", "description": "Provenance for one attachment fetch — never for `CompanyReport` itself.\n\n`CompanyReport` has one `source`, one `source_url`, one `license` and one\n`fetched_at`: every field on it is an assertion by *that* register under\n*that* licence *at that moment* (D-026(c)). An attachment (`include=[…]`\non `lookup_company`, assembled by `Registry.lookup_with`) is a **second**\nround trip, so it needs its own moment, its own cache state and its own\nfailure mode — even when it happens to be the same upstream as the first\nfetch (D-041(c)'s correction: the discipline is **one fetch, one\n`SourceRef`**, not one organisation). No new vocabulary: this reuses the\nfive provenance names `CompanyReport` already carries.\n\nEvery attachment model — the LEI (D-026(c)), officers (D-028(5)), Peppol\n(D-029(b)), filing history (D-041(d)) and whatever else lands behind a\nfuture `include` value — carries exactly one of these, however many\nfields the rest of the block has. None of those models are added by this\ntask (D-042(g)): this is the shape they will all reuse." } } }