# Type Mapping and Representation Risks

The valid type syntax is defined by `schema.json`. This reference adds mapping semantics and warnings; it never overrides explicit user mappings.

## Standard semantics

| Schema type | Meaning |
| --- | --- |
| `int8..int64`, `uint8..uint64` | fixed-width signed or unsigned integer |
| `float32`, `float64` | IEEE 754 binary floating point |
| `decimal(p,s)`, `decimal128(p,s)` | exact decimal with declared precision and scale |
| `string(n)`, `char(n)` | variable- or fixed-length text |
| `boolean` | boolean |
| `datetime`, `date`, `time` | date and time semantics defined by the contract |
| `uuid` | UUID |
| `json` | arbitrary JSON value |
| `array<T>`, `map<K,V>` | compound value |
| `enums.<name>`, `types.<name>` | local reference |
| `<alias>.enums.<name>`, `<alias>.types.<name>` | imported reference |

## Explicit mapping objects

A non-empty mapping object assigns a target key such as `node`, `golang`, `python`, `java`, `mongodb`, or `postgres` to the exact target type. Keys and values are user-controlled strings. Code generation must use an explicit target mapping verbatim.

## Nullability

`required: false` must map to a representation that can carry null:

- Go: pointer or another project-approved nullable type;
- Rust: `Option<T>`;
- TypeScript: `T | null` or the project's equivalent optional contract;
- Python: `Optional[T]`;
- Java: a nullable reference or project-approved optional wrapper.

Do not invent getters, setters, wrappers, or optional conventions unless the target project already requires them.

## Warn without rewriting

- Binary floats can lose precision for money and exact measurements; suggest decimal or integer minor units, but retain the declared float.
- BSON driver values such as Decimal128, ObjectId, Timestamp, Binary, and UUID need official driver codecs. Hand-written lookalikes can serialize to the wrong wire type.
- JavaScript database drivers may return `NUMERIC`, `DECIMAL`, or `BIGINT` as strings to preserve precision. Parsing through `Number` or `parseFloat` may lose it.
- MongoDB Decimal128 often needs explicit conversion for arithmetic in Go, Python, and Java.
- Enum storage changes can reinterpret historical rows, especially reordered integer enums.
- Date/time mappings must define timezone and offset behavior. PostgreSQL `timestamp without time zone` and BSON UTC dates are not equivalent representations.
- Nested and collection types may require explicit driver metadata; reflection often cannot recover element types.

Verify current driver behavior against the dependency version in the consuming project before making a mapping claim.