> ## Documentation Index
> Fetch the complete documentation index at: https://stockcontext.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Units and fields

> Decimal-string magnitudes, the unit vocabulary, the decimals scale, and how signs and dates work.

Exact filed magnitudes are **decimal strings**, not floats. Schema 2 may put them in compact `v` cells or in aligned `data.fields` arrays. Parse exact strings with a decimal type so no precision is lost.

```json theme={null}
{ "revenue": { "v": "37579000000", "d": "≈€37.58B" } }
```

## Magnitudes are strings

Exact cells are strings: `"416161000000"` or `{ "v": "416161000000", "d": "≈$416.2B" }`. Use `Decimal` in Python or a decimal library in JS; never `float`, which would silently drop precision on a large magnitude. Only convert to a display number at the very edge, and label the conversion. Ratios can be plain JSON numbers.

## The unit vocabulary

Money units are the filer's ISO-4217 reporting currency, not a fixed USD vocabulary. Statement blocks carry `reporting.reporting_currency`; overview and price responses can also expose `subject.entity.reporting_currency` and `subject.security.trading_currency`. The unit policies are served by `stock_reference` with `{ "catalog": "units" }`.

| Unit pattern                  | Meaning                                                      | Example                                                    |
| ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
| `USD`, `EUR`, `JPY`, ...      | Whole monetary amount in the filing's ISO-4217 currency.     | `SAP` revenue with `unit: "EUR"` is euros, not dollars.    |
| `USD/share`, `EUR/share`, ... | Per-share monetary amount in the filing's ISO-4217 currency. | `eps_diluted` with `unit: "EUR/share"` is euros per share. |
| `shares`                      | A whole share count.                                         | `weighted_avg_shares_basic` `"14948500000"`.               |
| `ratio`                       | A dimensionless ratio (not a percentage).                    | `effective_tax_rate` `0.1561` is 15.61%.                   |

A `ratio` is a fraction, not percentage points: `0.1561` means 15.61%. Multiply by 100 only at display.

## Currency locations

Always format from these currency fields. If a value is `36800000000` with `reporting_currency: "EUR"`, write EUR 36.8B, not USD 36.8B. Price-derived ratios that would mix reporting and trading currencies refuse with `missing_operand: "currency_conversion"` instead of inventing an FX rate.

## The decimals scale

`decimals` mirrors XBRL's reporting scale — the power of ten the filer rounded to. `-6` means the value was reported in millions, `-3` in thousands, and a positive value (like `2` on EPS) means places after the decimal point. It tells you the precision the filer actually reported; the `value` string is already the full magnitude, so you rarely need `decimals` for math — it is there for faithful display.

## Status and provenance

Higher detail can carry:

* **direct/derived markers** — whether the value came from one tagged concept or proven operands.
* **`concept`** — the XBRL concept the value came from, e.g. `us-gaap:NetIncomeLoss`.
* **`provenance`** — on price-derived cells: `licensed_market_data` or `computed_from_prices`.

The `concepts` catalog in `stock_reference` maps each served field to its XBRL concept.

## Signs are meaningful

A negative number is information — preserve the sign end to end.

```json theme={null}
{ "retained_earnings": ["-14264000000"], "financing_cash_flow": ["-120686000000"] }
```

A negative `retained_earnings` is a real accumulated deficit; a negative `financing_cash_flow` is normal (cash paid out). Stripping the minus to make a value "look clean" changes its meaning.

## Dates

Date-only fields use `YYYY-MM-DD` (`"period_end": "2025-09-27"`); timestamps in `meta` are UTC ISO-8601 with a `Z` (`"published_at": "2026-06-26T18:42:30.172304Z"`). Business dates (`period_end`, `filed`, `transaction_date`) are not data-currency signals — the clocks in [Clocks and provenance](/docs/reference/freshness) are.

## Absent values

A value you expected may instead be a refusal: `{ "unavailable": "not_reported" }`. Check `unavailable` before doing math on any field. The [Response model](/docs/reference/response-model) owns the value-cell and refusal shapes.