Money Field

Overview

In the Nacelle Order Management System (NOMS), financial data read using GraphQL is represented by the Money field. This field is designed to provide a standardized way of representing monetary values across the platform. The Money field captures essential aspects of a financial value, including the amount, currency, and precision.

Structure

The Money type is defined in GraphQL as follows:

"""
Represents a single price
"""
type Money {
  """
  An amount for the money
  """
  amount: Int!

  """
  A currencyCode identifier for the amount
  """
  currencyCode: String!

  """
  The precision to which the currency amount should be displayed
  """
  precisionDigits: Int
}

Fields

• amount: Represents the numerical value of the money without decimals.
• currencyCode: An identifier representing the type of currency using the ISO standard (e.g., USD, EUR, GBP). This field helps ensure that the monetary value is understood and processed correctly across different geographies and systems.
• precisionDigits: A field indicating the number of decimal places to which the currency amount should be displayed (e.g., 0, 1, 2, 3).

Advantages Over Floating Point Numbers

Traditional floating point representations like floats or doubles are not accurate for all decimal fractions. Due to the binary nature of their storage, they can introduce subtle errors when representing decimal values. This inaccuracy can lead to significant errors, especially when dealing with financial data where every cent matters.

The Money type avoids these pitfalls by:

1. Storing Values as Integers: By storing values as whole numbers (e.g., storing $19.99 as 1999), Money avoids the precision issues associated with floats.

2. Explicit Precision Handling: With the precisionDigits field, it's clear how many decimal places the amount represents, allowing for consistent and accurate calculations.

3. Standardized Currency Representation: Using an ISO standard currency code avoids ambiguity and ensures that the value is interpreted consistently across systems.

Therefore, when dealing with financial data, it's generally recommended to use specialized structures like Money rather than relying on generic float types.

Usage

The Money field can be used in various parts of the NOMS platform where financial values are relevant. Examples include representing the price of an item, total order value, tax amounts, and more.

Example

When querying for the price of a product, the response might look like:

{
  "data": {
    "order": {
      "id": "16374a95-d48a-561d-a8d1-104544139e39",
      "totalPrice": {
        "amount": 1999,
        "currencyCode": "USD",
        "precisionDigits": 2
      }
    }
  }
}

In this example, the order's total price is represented as $19.99 (USD) with a precision of 2 decimal places.

Best Practices

1. Consistency: Always ensure that the amount and currencyCode fields are filled out consistently and correctly to avoid misinterpretations.

2. Validation: Implement validation checks to ensure the correct format and values for the currencyCode.

3. Precision Handling: When using the precisionDigits field, ensure your application handles rounding correctly to maintain accurate financial calculations.

4. Display: While displaying monetary values in your application, consider using localization libraries or APIs that can format the amount based on user preferences and locale.

Remember, while the Money field offers a standardized way to represent financial values, it's essential to handle and display these values accurately in your applications to ensure clarity and correctness for your users.