Unknown and optional fields

Overview

Many optional fields and lookup roles in Formation can be marked Unknown rather than left blank. The distinction matters: blank means “we haven’t filled this in yet”; Unknown means “we’ve looked, and the data isn’t available”. Reporting that’s filtering on completeness counts these differently.

The Unknown affordance appears in two main places:

As a checkbox on a lookup role — e.g. Unknown Investor, Unknown Vendor, Unknown Occupier. Ticking it adds an explicit placeholder to the role’s list rather than leaving the role empty.
As a free-form field — fields like Description can be cleared without ambiguity, so they don’t typically need an Unknown marker.

When to use Unknown vs leaving a field blank

If…	Use…
You’ve looked and the data really isn’t available	Unknown
You haven’t checked yet	Blank
The fact is “this role isn’t applicable to this record”	Blank
There is a party in this role but you don’t know who	Unknown (with a percentage share if relevant)

The Unknown checkbox

When a role supports Unknown, the form renders a checkbox alongside the entity picker. Ticking the box adds a placeholder entry for that role. The placeholder still occupies a “slot” in the role — it counts towards rules like “at least one company” and (where supported) carries its own percentage share.

For roles where a Share % is being tracked (e.g. Investor on an investment event), the Unknown placeholder gets an optional percentage field next to the checkbox. Two things to know about how it behaves:

The field accepts whole numbers from 0 to 100. Decimals are rounded to the nearest integer on save (e.g. 33.6% becomes 34%).
The percentage is displayed in the read-only detail view in the same place where a named company’s share would appear — so a row with “Unknown Investor: 25%” reads the same as “Acme Capital: 25%”.

If the role doesn’t carry a share (e.g. Unknown Vendor), the percentage field doesn’t appear at all.

One unknown placeholder per role

A given role on a record can hold at most one Unknown placeholder. The server rejects requests that include two: “Only one unknown company is allowed per role.” This applies on schemes and investment events alike — the rule sits in the command handlers.

Where the Unknown affordance appears today

Entity	Role	Has Unknown?	Has share field?
Investment Event	Investor	Yes	Yes
Investment Event	Vendor	Yes	No
Investment Event	Investor Agent	No	No
Investment Event	Vendor Agent	No	No
Scheme	(various roles)	Yes (the rule “at most one unknown per role” applies)	Yes for roles with share tracking
Portfolio	(various roles)	Yes	Yes when ownership = Share only
Occupier Event	Occupier	Yes (via Is Occupier Unknown flag, not a placeholder row)	N/A

The Occupier event has a slightly different shape: instead of a placeholder row, it uses a dedicated Is Occupier Unknown field on the event itself. See Occupier Events → Occupier-or-unknown — pick one.

Where unknowns show up in read-only views

In detail views, an Unknown placeholder renders as the role’s name followed by “(Unknown)” — e.g. Investor (Unknown) — rather than a company name. If the placeholder carries a percentage, the percentage shows alongside in the usual share column.

In lists (the table view of investment events, occupier events, etc.), columns that summarise the cast of a record (e.g. “Investor”) show “Unknown” when the named-company list is empty and the unknown placeholder is set, and the company name when there’s a named company.

Field-level Unknown checkboxes (older UI)

Some legacy fields use an inline Unknown checkbox alongside a regular input rather than on a role-list. The semantics are the same: ticking the box records “we’ve looked; not available” and the input is cleared.

Investment Events — Unknown Investor with a percentage share.
Schemes — Unknown placeholders on company roles; the per-role share cap.
Portfolios — Unknown investors/vendors; shares only under Share ownership.
Occupier Events — the dedicated Is Occupier Unknown flag.

Where this lives

Component: src/services/web/src/lib/components/forms/UnknownCheckbox.svelte
Per-entity wiring: see each entity’s edit panel (e.g. InvestmentEventEdit.svelte, PortfolioPartiesEdit.svelte)
Server-side per-role check: src/services/api/app/app.api/Handlers/Commands/InvestmentEvents/CreateInvestmentEventCommandHandler.cs and the equivalent in Schemes/