objectstack-ai · Copilot · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/content/docs/references/data/currency/CurrencyCalculationResult.mdx b/content/docs/references/data/currency/CurrencyCalculationResult.mdx
@@ -0,0 +1,13 @@
+---
+title: CurrencyCalculationResult
+description: CurrencyCalculationResult Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **value** | `object` | ✅ | Calculated currency value |
+| **crossCurrency** | `boolean` | ✅ | Whether cross-currency calculation was performed |
+| **sources** | `object[]` | optional | Source values |
+| **method** | `Enum<'sum' \| 'average' \| 'min' \| 'max' \| 'count'>` | optional | Calculation method |
diff --git a/content/docs/references/data/currency/CurrencyValidation.mdx b/content/docs/references/data/currency/CurrencyValidation.mdx
@@ -0,0 +1,16 @@
+---
+title: CurrencyValidation
+description: CurrencyValidation Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **minAmount** | `number` | optional | Minimum amount |
+| **maxAmount** | `number` | optional | Maximum amount |
+| **minConvertedAmount** | `number` | optional | Minimum amount in corporate currency |
+| **maxConvertedAmount** | `number` | optional | Maximum amount in corporate currency |
+| **allowedCurrencies** | `string[]` | optional | Allowed currency codes |
+| **positiveOnly** | `boolean` | optional | Require positive amounts only |
+| **nonZero** | `boolean` | optional | Require non-zero amounts |
diff --git a/content/docs/references/data/currency/CurrencyValue.mdx b/content/docs/references/data/currency/CurrencyValue.mdx
@@ -0,0 +1,15 @@
+---
+title: CurrencyValue
+description: CurrencyValue Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **amount** | `number` | ✅ | Numeric amount |
+| **currency** | `string` | ✅ | Currency code (ISO 4217) |
+| **convertedAmount** | `number` | optional | Converted amount in corporate currency |
+| **convertedCurrency** | `string` | optional | Corporate currency code |
+| **exchangeRate** | `number` | optional | Exchange rate used for conversion |
+| **conversionDate** | `string` | optional | When the conversion was performed |
diff --git a/content/docs/references/data/currency/MultiCurrencyFieldConfig.mdx b/content/docs/references/data/currency/MultiCurrencyFieldConfig.mdx
@@ -0,0 +1,15 @@
+---
+title: MultiCurrencyFieldConfig
+description: MultiCurrencyFieldConfig Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **defaultCurrency** | `string` | optional | Default currency for new records |
+| **alwaysStoreConverted** | `boolean` | optional | Always store converted values |
+| **allowCurrencyChange** | `boolean` | optional | Allow changing currency after creation |
+| **restrictedCurrencies** | `string[]` | optional | Restrict to specific currencies |
+| **showConversion** | `boolean` | optional | Show conversion information in UI |
+| **roundingMode** | `Enum<'half_up' \| 'half_down' \| 'half_even' \| 'up' \| 'down'>` | optional | Rounding mode for calculations |
diff --git a/content/docs/references/data/currency/meta.json b/content/docs/references/data/currency/meta.json
@@ -0,0 +1,3 @@
+{
+ "title": "Currency"
+}
diff --git a/content/docs/references/data/field/Field.mdx b/content/docs/references/data/field/Field.mdx
@@ -49,6 +49,11 @@ description: Field Schema Reference
 | **qrErrorCorrection** | `Enum<'L' \| 'M' \| 'Q' \| 'H'>` | optional | QR code error correction level (L=7%, M=15%, Q=25%, H=30%). Only applicable when barcodeFormat is "qr" |
 | **displayValue** | `boolean` | optional | Display human-readable value below barcode/QR code |
 | **allowScanning** | `boolean` | optional | Enable camera scanning for barcode/QR code input |
+| **currencyCode** | `string` | optional | Default currency code for this field (ISO 4217) |
+| **allowCurrencyChange** | `boolean` | optional | Allow users to change currency on records (multi-currency only) |
+| **restrictedCurrencies** | `string[]` | optional | Restrict field to specific currencies (multi-currency only) |
+| **showConversion** | `boolean` | optional | Display conversion to corporate/user currency (multi-currency only) |
+| **roundingMode** | `Enum<'half_up' \| 'half_down' \| 'half_even' \| 'up' \| 'down'>` | optional | Rounding mode for currency calculations |
 | **hidden** | `boolean` | optional | Hidden from default UI |
 | **readonly** | `boolean` | optional | Read-only in UI |
 | **encryption** | `boolean` | optional | Encrypt at rest |

diff --git a/content/docs/references/data/meta.json b/content/docs/references/data/meta.json
@@ -2,6 +2,7 @@
  "title": "Data Protocol",
  "root": true,
  "pages": [
+ "currency",
  "dataset",
  "field",
  "filter",

diff --git a/content/docs/references/system/currency/Currency.mdx b/content/docs/references/system/currency/Currency.mdx
@@ -0,0 +1,17 @@
+---
+title: Currency
+description: Currency Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **code** | `string` | ✅ | ISO 4217 currency code |
+| **name** | `string` | ✅ | Currency name (e.g., US Dollar, Euro) |
+| **symbol** | `string` | ✅ | Currency symbol (e.g., $, €, £, ¥) |
+| **decimalPlaces** | `integer` | optional | Number of decimal places |
+| **isActive** | `boolean` | optional | Whether this currency is active |
+| **isCorporate** | `boolean` | optional | Whether this is the corporate/base currency |
+| **conversionRate** | `number` | optional | Conversion rate to corporate currency |
+| **conversionRateUpdatedAt** | `string` | optional | Last conversion rate update timestamp |
diff --git a/content/docs/references/system/currency/CurrencyCode.mdx b/content/docs/references/system/currency/CurrencyCode.mdx
@@ -0,0 +1,7 @@
+---
+title: CurrencyCode
+description: ISO 4217 currency code (e.g., USD, EUR, GBP)
+---
+
+ISO 4217 currency code (e.g., USD, EUR, GBP)
+
diff --git a/content/docs/references/system/currency/CurrencyFormatting.mdx b/content/docs/references/system/currency/CurrencyFormatting.mdx
@@ -0,0 +1,15 @@
+---
+title: CurrencyFormatting
+description: CurrencyFormatting Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **format** | `Enum<'symbol' \| 'code' \| 'name' \| 'symbol_code'>` | optional | Currency display format |
+| **locale** | `string` | optional | Locale for number formatting (e.g., en-US, fr-FR, zh-CN) |
+| **showSymbol** | `boolean` | optional | Show currency symbol |
+| **showCode** | `boolean` | optional | Show currency code |
+| **decimalSeparator** | `Enum<'.' \| ','>` | optional | Decimal separator |
+| **thousandsSeparator** | `Enum<',' \| '.' \| ' ' \| ''>` | optional | Thousands separator |
diff --git a/content/docs/references/system/currency/CurrencySettings.mdx b/content/docs/references/system/currency/CurrencySettings.mdx
@@ -0,0 +1,19 @@
+---
+title: CurrencySettings
+description: CurrencySettings Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **enabled** | `boolean` | optional | Enable multi-currency support |
+| **corporateCurrency** | `string` | ✅ | Corporate/base currency code |
+| **activeCurrencies** | `object[]` | ✅ | Active currencies |
+| **defaultFormatting** | `object` | optional | Default currency formatting |
+| **allowUserCurrency** | `boolean` | optional | Allow users to select preferred currency |
+| **enableAutoConversion** | `boolean` | optional | Enable automatic currency conversion |
+| **enableDatedExchangeRates** | `boolean` | optional | Enable dated exchange rates |
+| **exchangeRates** | `object[]` | optional | Historical exchange rates |
+| **aggregationStrategy** | `Enum<'convert_to_corporate' \| 'convert_to_user' \| 'group_by_currency'>` | optional | Currency conversion strategy for aggregations |
+| **sortingStrategy** | `Enum<'convert_to_corporate' \| 'convert_to_user' \| 'native_value'>` | optional | Currency conversion strategy for sorting |
diff --git a/content/docs/references/system/currency/ExchangeRate.mdx b/content/docs/references/system/currency/ExchangeRate.mdx
@@ -0,0 +1,15 @@
+---
+title: ExchangeRate
+description: ExchangeRate Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **fromCurrency** | `string` | ✅ | Source currency code |
+| **toCurrency** | `string` | ✅ | Target currency code |
+| **rate** | `number` | ✅ | Exchange rate |
+| **effectiveDate** | `string` | ✅ | Effective start date for this rate |
+| **expiryDate** | `string` | optional | Expiry date for this rate |
+| **source** | `Enum<'manual' \| 'api' \| 'system'>` | optional | Exchange rate source |
diff --git a/content/docs/references/system/currency/UserCurrencyPreferences.mdx b/content/docs/references/system/currency/UserCurrencyPreferences.mdx
@@ -0,0 +1,12 @@
+---
+title: UserCurrencyPreferences
+description: UserCurrencyPreferences Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **preferredCurrency** | `string` | ✅ | Preferred display currency |
+| **formatting** | `object` | optional | User-specific formatting preferences |
+| **alwaysConvert** | `boolean` | optional | Always convert to preferred currency |
diff --git a/content/docs/references/system/currency/meta.json b/content/docs/references/system/currency/meta.json
@@ -0,0 +1,3 @@
+{
+ "title": "Currency"
+}
diff --git a/content/docs/references/system/meta.json b/content/docs/references/system/meta.json
@@ -5,6 +5,7 @@
  "api",
  "audit",
  "auth",
+ "currency",
  "datasource",
  "discovery",
  "driver",

diff --git a/docs/MULTI_CURRENCY.md b/docs/MULTI_CURRENCY.md
@@ -0,0 +1,144 @@
+# Multi-Currency Support
+
+ObjectStack provides comprehensive multi-currency support following Salesforce best practices for international business scenarios.
+
+## Features
+
+### 🌍 Organization-Level Configuration
+- Enable/disable multi-currency at organization level
+- Configure corporate (base) currency
+- Manage active currencies and exchange rates
+- Support for 150+ currencies (ISO 4217 standard)
+- Dated exchange rates for historical accuracy
+
+### 💱 Field-Level Control
+- Default currency per field
+- Restrict currencies for specific fields
+- Control currency mutability after record creation
+- Configurable rounding modes
+- Display conversion information in UI
+
+### 👤 User Preferences
+- User-specific preferred display currency
+- Custom formatting options per user
+- Automatic currency conversion
+- Locale-specific number formatting
+
+### 📊 Reporting & Analytics
+- Multiple aggregation strategies:
+ - Convert to corporate currency
+ - Convert to user's preferred currency
+ - Group by currency (no conversion)
+- Cross-currency calculations with source tracking
+- Proper sorting across different currencies
+
+## Quick Start
+
+### 1. Enable Multi-Currency
+
+```typescript
+import { Currency, CurrencySettingsSchema } from '@objectstack/spec';
+
+const settings = {
+ enabled: true,
+ corporateCurrency: 'USD',
+ activeCurrencies: [
+ Currency.USD(),
+ { ...Currency.EUR(), conversionRate: 0.85 },
+ { ...Currency.GBP(), conversionRate: 0.73 },
+ ],
+ aggregationStrategy: 'convert_to_corporate',
+ sortingStrategy: 'convert_to_corporate',
+};
+
+CurrencySettingsSchema.parse(settings);
+```
+
+### 2. Define Currency Fields
+
+```typescript
+import { Field } from '@objectstack/spec';
+
+const amountField = Field.currency({
+ name: 'amount',
+ label: 'Amount',
+ currencyCode: 'USD',
+ allowCurrencyChange: true,
+ restrictedCurrencies: ['USD', 'EUR', 'GBP'],
+ showConversion: true,
+ roundingMode: 'half_up',
+});
+```
+
+### 3. Store Currency Values
+
+```typescript
+import { CurrencyValue } from '@objectstack/spec';
+
+// Simple value
+const value = CurrencyValue.create(1000.00, 'EUR');
+
+// Value with conversion
+const valueWithConversion = CurrencyValue.createWithConversion(
+ 1000.00, // Amount
+ 'EUR', // Currency
+ 1176.47, // Converted amount in USD
+ 'USD', // Corporate currency
+ 1.17647 // Exchange rate
+);
+```
+
+### 4. Display with Intl Formatting
+
+```typescript
+const formatter = new Intl.NumberFormat('en-US', {
+ style: 'currency',
+ currency: 'USD',
+});
+
+console.log(formatter.format(1234.56)); // "$1,234.56"
+```
+
+## Architecture
+
+### System Layer (`src/system/currency.zod.ts`)
+
+**Core Schemas:**
+- `CurrencySchema` - Individual currency definition
+- `ExchangeRateSchema` - Exchange rate between currencies
+- `CurrencySettingsSchema` - Organization-wide configuration
+- `CurrencyFormattingSchema` - Display formatting options
+- `UserCurrencyPreferencesSchema` - User-specific preferences
+
+**Helper Functions:**
+- `Currency.define()` - Create custom currency
+- `Currency.USD()`, `Currency.EUR()`, etc. - Pre-configured currencies
+
+### Data Layer (`src/data/currency.zod.ts`)
+
+**Core Schemas:**
+- `CurrencyValueSchema` - Compound value object (amount + currency + conversion)
+- `MultiCurrencyFieldConfigSchema` - Field-level configuration
+- `CurrencyCalculationResultSchema` - Cross-currency calculation results
+- `CurrencyValidationSchema` - Validation rules for currency fields
+
+**Helper Functions:**
+- `CurrencyValue.create()` - Create simple currency value
+- `CurrencyValue.createWithConversion()` - Create with conversion
+- `CurrencyValue.zero()` - Create zero value
+
+## Examples
+
+See [`examples/multi-currency-example.ts`](../examples/multi-currency-example.ts) for comprehensive examples.
+
+## Related Documentation
+
+- [Field Types](../content/docs/specifications/field-types.mdx)
+- [Data Protocol](../content/docs/specifications/architecture/data-layer.mdx)
+- [System Configuration](../content/docs/specifications/architecture/system-layer.mdx)
+
+## References
+
+- [ISO 4217 Currency Codes](https://www.iso.org/iso-4217-currency-codes.html)
+- [Intl.NumberFormat MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)
+- [Salesforce Multi-Currency](https://help.salesforce.com/s/articleView?id=sf.admin_enable_multicurrency.htm)