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

reference-data-structure.json

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

Basic Example

tax-rate-lookup.json

{
  "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

shipping-rates.json

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

Nested Objects

product-catalog.json

{
  "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

constants.json

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

Use Cases

Tax Calculation by Region

tax-by-region.json

{
  "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

tiered-pricing.json

{
  "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

unit-conversions.json

{
  "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

engineering-tables.json

{
  "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