# How standard types are named, and what is left out

A standard type's name says exactly what it is, and a type you might look for
may be part of another or left for your app to define.
[Standard types](https://jadpo.dev/docs/types) lists every one, from A to Z and
by group, and each has a page saying what it is and how to make one. Each part
or kind a standard type names is a standard type too: [`IdentityDocument`](/docs/types/type-identity-document.md)'s
[`IdentityDocumentKind`](/docs/types/type-identity-document-kind.md), or [`RichText`](/docs/types/type-rich-text.md)'s [`RichTextBlock`](/docs/types/type-rich-text-block.md). GeoJSON's [`Feature`](/docs/types/type-feature.md) and
[`FeatureCollection`](/docs/types/type-feature-collection.md) are explained on the [Geospatial](/docs/geospatial.md) page. Why
Jadpo defines these types itself is in the
[design notes](https://github.com/jadpo-dev/jadpo/blob/main/docs/language/notes/19-standard-library.md#shared-vocabulary-types).

Three rules shape the list:

- **Country-specific identifiers are global types,** like the rest.
  [`UkSortCode`](/docs/types/type-uk-sort-code.md), [`UsSsn`](/docs/types/type-us-ssn.md) and [`NhsNumber`](/docs/types/type-nhs-number.md) are named by their country, so
  they don't clash.
- **Gender and sex at birth are left out.** They are contested, and they
  are personal data, so your app models them deliberately, and
  [Personal data](/docs/personal-data.md) treats them as sensitive.
- **A quantity is stored in its SI base unit.** You choose a unit when
  you make the value and when you show it: `units.of(5, LengthUnit.mile)`
  holds metres, and `text.format(distance, locale:, unit: LengthUnit.mile)`
  shows miles. So `==` and ordering just work, and storage is one
  `numeric` column.

## How standard types are named

A standard type's name says exactly what it is, so it doesn't take a word
your app needs for something else. The name is, in order of preference:

1. the defining standard's own term, qualified until it is unambiguous:
   [`PostalAddress`](/docs/types/type-postal-address.md), [`RecurrenceRule`](/docs/types/type-recurrence-rule.md), [`ProblemDetails`](/docs/types/type-problem-details.md);
2. otherwise the noun, qualified by what it holds: [`DateRange`](/docs/types/type-date-range.md),
   [`DataSize`](/docs/types/type-data-size.md), [`ImageDimensions`](/docs/types/type-image-dimensions.md);
3. never a bare word an app plausibly uses for its own, different thing,
   except a generic container that takes a type, such as [`Range<T>`](/docs/types/type-range.md), as
   `List<T>` is.

So it is [`CountrySubdivision`](/docs/types/type-country-subdivision.md), not `Subdivision`, which could be a housing
subdivision, and [`UnitQuantity`](/docs/types/type-unit-quantity.md), not `Quantity`, which could be an order
line's count. The same rule gives [`SecretText`](/docs/types/type-secret-text.md), [`NetworkPort`](/docs/types/type-network-port.md),
[`WritingScript`](/docs/types/type-writing-script.md) and [`WebOrigin`](/docs/types/type-web-origin.md), and a time interval is the built-in
[`InstantRange`](/docs/types/type-instant-range.md). A bare word passes when an app using it means the
standard thing: [`Price`](/docs/types/type-price.md), [`Area`](/docs/types/type-area.md), [`Mass`](/docs/types/type-mass.md), [`Currency`](/docs/types/type-currency.md).

[`Point`](/docs/types/type-point.md) and [`Length`](/docs/types/type-length.md) are the two exceptions, so that geography and
quantities read naturally (`var shelf: Length = 2metre`). Built-in names
older than the rule (`File`, `Page`, `Access`) keep their names.

## Types that aren't on the list

Some types you might look for are folded into another, so nothing is
lost: units into their quantity type, roles into the general type, and
duplicates into the one type they duplicate. Formats and application
entities are left out:

| What | Became |
|---|---|
| Units (`Metre`, `Mile`, `Kilogram`, `Pound`, `Celsius`, `Litre`, `KilowattHour`, every `...Unit` enum and 17 more) | The quantity type, with a unit at construction and display |
| Roles: `Height`, `GeoDistance` · `FloorArea` · `WindSpeed` · `BodyTemperature` · `BarometricPressure` · `MediaDuration` · `DateOfBirth`, `ExpiryDate` · `CountryOfOrigin` · `UsState`, `Region` · `Salary` | [`Length`](/docs/types/type-length.md) · [`Area`](/docs/types/type-area.md) · [`Speed`](/docs/types/type-speed.md) · [`Temperature`](/docs/types/type-temperature.md) · [`Pressure`](/docs/types/type-pressure.md) · [`Duration`](/docs/types/type-duration.md) · [`CalendarDate`](/docs/types/type-calendar-date.md) · [`Country`](/docs/types/type-country.md) · [`CountrySubdivision`](/docs/types/type-country-subdivision.md) · [`Money`](/docs/types/type-money.md): a field of the general type |
| Duplicates: `Timestamp`, `Uri`, `Ipv4Address`, `Ipv6Address`, `HexColour`, `HslColour`, `Sha256`, `UuidV7`, `Point3D`, `CountryAlpha3`, `LanguageAlpha3`, `UkPostcode`, `UsZipCode`, `UkNumberPlate`, `EuVatNumber`, `UkVatNumber`, `TimeRange`, `MinorUnits`, `MediaType`, `ImageFormat` | The one standard type each duplicates |
| Also folded in review: `AddressLine`, `BarcodeSymbology`, `DoseFrequency`, `FlightDesignator`, `GitSha`, `Gtin`, `HttpHeaders`, `Humidity`, `PackageDimensions`, `PackageName`, `PhysicalQuantity`, `UnitOfMeasure`, `Ucum`, `Proportion`, `QueryString`, `SubtitleTrack`, `UkBankAccount`, `WebhookSignature`, `WindDirection`, `CarbonDioxideEquivalent` | [`PostalAddress`](/docs/types/type-postal-address.md), [`Barcode`](/docs/types/type-barcode.md), [`DosageInstruction`](/docs/types/type-dosage-instruction.md), [`FlightNumber`](/docs/types/type-flight-number.md), [`GitRef`](/docs/types/type-git-ref.md), [`Ean13`](/docs/types/type-ean13.md), [`HttpHeaderName`](/docs/types/type-http-header-name.md), [`Percentage`](/docs/types/type-percentage.md), [`Dimensions`](/docs/types/type-dimensions.md), [`PackageUrl`](/docs/types/type-package-url.md), [`UnitQuantity`](/docs/types/type-unit-quantity.md) (three), [`Ratio`](/docs/types/type-ratio.md), [`Url`](/docs/types/type-url.md), [`SubtitleCue`](/docs/types/type-subtitle-cue.md), [`BankAccount`](/docs/types/type-bank-account.md), [`Hmac`](/docs/types/type-hmac.md), [`Bearing`](/docs/types/type-bearing.md), [`Mass`](/docs/types/type-mass.md) |
| Formats: `Hex`, `Base64`, `Wkt`, `Json`, `CsvDialect`, `MessageFormat`, `VCard`, `OtpAuthUri`, `CssLength` | Out: `encoding.` and `json.` operations |
| Application entities: `Recipe`, `HotelStay`, `OrderStatus`, `PaymentStatus`, `Consent`, `SensorReading`, `StoredFile`, `UserId`, `Allergy` and 31 more | Out: an application's own records |
| `Gender`, `SexAtBirth`, `Cvv` | Out: sensitive (a CVV is never stored) |
| `HashAlgorithm`, `KeyAlgorithm`; `SessionId`; `AcceptLanguage` | Out: no algorithm choices; the runtime's ([Sign-in and identity](/docs/identity.md)); a call, `locale.from_accept_language` |
| Niche, silly, or a maybe with no published standard | Out: 729 entries, a package's to define |

## What's left out on purpose

Some things you might reach for aren't in the standard library, each for a
reason and with something to use instead:

| Left out | Why | Instead |
|---|---|---|
| Generic functions in your own code | They bring type-parameter errors for agents to fight | The standard library stays generic |
| `reduce`, `fold` | A second way to accumulate | `for` with `var mut`; `list.sum` |
| Comparators | A key expresses every order, and an inconsistent comparator differs by target | `sort_by`, `reverse` |
| `items[i]` | Out of range needs an arm or a defect | `list.at` gives `T?` |
| Regular expressions as calls | A pattern is a type's rule, in linear time | `pattern:` and construction ([Values and types](/docs/values-and-types.md)) |
| Graphemes | They'd disagree with `max_length` and PostgreSQL, and change with each Unicode version | Code points |
| Dynamic keys on records | A field is its own type and carries its own policy and marks | `Map` |
| A dynamic JSON value | Nothing Jadpo is meant for needs one | `json.read(..., as:)`; `Text` to pass on |
| CSV in memory | One way to read rows | `csv.read` through a store |
| MD5, SHA-1 | Broken | A package |
| Bitwise operations | Flags read better as a set; device formats belong in their package | `Set<Enum>` |
| Fetching exchange rates | Outside data with a time and a source | A provider package; `money.convert` applies a rate the app holds |
| Gender, sex at birth | Contested, and personal data | The app's own type, marked sensitive ([Personal data](/docs/personal-data.md)) |
| CMYK and print colour | Needs a colour profile | A package on the standard [`Colour`](/docs/types/type-colour.md) |
| Training models | Needs GPUs, datasets and long jobs | A package or an outside service |
| Aliases (`size` for `count`) | One obvious name each | The name this page gives |