Reference Data

Reference data provides lookup tables and external data that can be used in computed fields and expressions. This is useful for calculations that depend on static data like tax rates, pricing tables, or conversion factors.

Structure

{
  "referenceData": {
    "tableName": {
      "key1": { "property": "value" },
      "key2": { "property": "value" }
    }
  }
}

Basic Example

{
  "referenceData": {
    "taxRates": {
      "CA": 0.0725,
      "NY": 0.08,
      "TX": 0.0625
    }
  },
  "computed": {
    "taxRate": {
      "expression": "get value(ref.taxRates, state)"
    },
    "tax": {
      "expression": "subtotal * computed.taxRate"
    }
  }
}

Accessing Reference Data

Static Path

For fixed paths, use ref.path notation:

{
  "expression": "ref.constants.conversionFactor"
}

Dynamic Lookup

For dynamic keys based on form values, use get value():

{
  "expression": "get value(ref.prices, productCode)"
}

Lookup Tables

Simple Key-Value

{
  "referenceData": {
    "shippingRates": {
      "standard": 5.99,
      "express": 12.99,
      "overnight": 24.99
    }
  },
  "computed": {
    "shippingCost": {
      "expression": "get value(ref.shippingRates, shippingMethod)"
    }
  }
}

Nested Objects

{
  "referenceData": {
    "products": {
      "SKU001": {
        "name": "Widget",
        "price": 9.99,
        "weight": 0.5
      },
      "SKU002": {
        "name": "Gadget",
        "price": 19.99,
        "weight": 1.2
      }
    }
  },
  "computed": {
    "productPrice": {
      "expression": "get value(ref.products, selectedSku).price"
    },
    "productWeight": {
      "expression": "get value(ref.products, selectedSku).weight"
    }
  }
}

Constants

{
  "referenceData": {
    "constants": {
      "taxRate": 0.0825,
      "discountThreshold": 100,
      "maxQuantity": 999
    }
  },
  "computed": {
    "tax": {
      "expression": "subtotal * ref.constants.taxRate"
    }
  }
}

Use Cases

Tax Calculation by Region

{
  "referenceData": {
    "stateTaxRates": {
      "AL": 0.04,
      "AK": 0.0,
      "AZ": 0.056,
      "CA": 0.0725,
      "CO": 0.029,
      "CT": 0.0635
    }
  },
  "fields": {
    "state": {
      "label": "State",
      "type": "select",
      "options": [
        { "value": "CA", "label": "California" },
        { "value": "NY", "label": "New York" }
      ]
    }
  },
  "computed": {
    "taxRate": {
      "expression": "get value(ref.stateTaxRates, state)",
      "format": "percent"
    },
    "salesTax": {
      "expression": "subtotal * computed.taxRate",
      "format": "currency"
    }
  }
}

Tiered Pricing

{
  "referenceData": {
    "pricingTiers": {
      "1": 100,
      "10": 90,
      "50": 80,
      "100": 70
    }
  },
  "computed": {
    "unitPrice": {
      "expression": "if quantity >= 100 then ref.pricingTiers[\"100\"] else if quantity >= 50 then ref.pricingTiers[\"50\"] else if quantity >= 10 then ref.pricingTiers[\"10\"] else ref.pricingTiers[\"1\"]"
    }
  }
}

Unit Conversion

{
  "referenceData": {
    "conversions": {
      "km_to_miles": 0.621371,
      "kg_to_lbs": 2.20462,
      "celsius_to_fahrenheit_factor": 1.8,
      "celsius_to_fahrenheit_offset": 32
    }
  },
  "computed": {
    "distanceInMiles": {
      "expression": "distanceKm * ref.conversions.km_to_miles",
      "format": "decimal(2)"
    }
  }
}

Engineering Tables

{
  "referenceData": {
    "bolts": {
      "M6": { "pitch": 1.0, "tensileArea": 20.1 },
      "M8": { "pitch": 1.25, "tensileArea": 36.6 },
      "M10": { "pitch": 1.5, "tensileArea": 58.0 },
      "M12": { "pitch": 1.75, "tensileArea": 84.3 }
    }
  },
  "computed": {
    "threadPitch": {
      "expression": "get value(ref.bolts, boltSize).pitch"
    },
    "tensileStrength": {
      "expression": "get value(ref.bolts, boltSize).tensileArea * materialStrength"
    }
  }
}

Error Handling

When a lookup key doesn't exist, get value() returns null. Handle this in your expressions:

{
  "computed": {
    "rate": {
      "expression": "if get value(ref.rates, category) != null then get value(ref.rates, category) else ref.rates.default"
    }
  }
}

Best Practices

1. Use meaningful names - Name tables descriptively (e.g., taxRates not data1)

2. Keep data static - Reference data should not change during form filling

3. Document your data - Use comments or descriptions to explain lookup tables

4. Provide defaults - Handle cases where lookup keys might not exist

5. Consider data size - Very large reference data sets may impact performance