Money and data contracts

Use Niqat data contracts for exact money, explicit currency scales, offline UUIDv7 identifiers, and company memberships. Preserve meaning across integrations.

Retail data must remain understandable after a restart, an export, or a device recovery. Niqat’s data conventions make identity, units, and precision explicit.

Money is exact

The conceptual money type carries an integer amount and a currency code:

Money {
  minor_units: signed 64-bit integer
  currency_code: ISO 4217 string
}

IQD defaults to scale zero and USD defaults to scale two. The tenant currency registry owns the explicit scale; the visitor’s language must not decide it. This is Niqat’s accounting/display contract, not a claim about every external currency standard.

For illustration, 3,250 IQD plus 2,000 IQD equals 5,250 IQD. The website demo uses small integer sample amounts only. It is not the implementation of the native money type.

Avoid binary floating point

Money, tax, cost, payment, total, and journal calculations must not use binary floating point for business values. Mixed currencies require an explicit conversion. Persisted quantities and rates also follow the project’s fixed-precision conventions.

{
  "minor_units": 5250,
  "currency_code": "IQD"
}

This JSON illustrates the conceptual fields. It is not a public endpoint request body.

Identity works offline

Business identifiers are UUIDv7 strings generated offline. A phone number, email address, username, or document number must not become a primary synchronization identifier.

Keep global identity separate from tenant membership. Membership owns role, status, permissions, and optional branch and warehouse assignments.

Preserve the original meaning

Retain original transaction quantity and unit, define where rounding happens, and keep historical currency scale interpretation stable. A later display or configuration change must not silently reinterpret an earlier document.

Source references

See docs/data-conventions.md and packages/platform_contracts/README.md. Contract changes require the project’s decision and migration review process.