Skip to main content

Building Fields & Formulas

Overview​

Fields and Formulas are the computational components of your Model. They reference data from Expected Fields through Field variables and perform calculations to determine emissions and carbon sequestration. Building the Formulas starts bottom-up from defining the Fields which pull data from Expected Fields, and then creating Formulas that build upon those Fields.

Fields vs Formulas​

  • Fields - Reference Expected Field Values from Document Instances and can perform calculations
  • Formulas - Reference other Fields and/or Formulas to perform calculations

Creating Fields​

Fields pull data from Expected Fields you defined in your Document Instances and can apply calculations.

Creating a Field​

The following example creates a field which references an Expected Field which connects the Model Field to the collected evidence.

To create a field within a field library, use POST /v0/field-libraries/{id}/fields:

Create field
curl -X 'POST' "/v0/field-libraries/{id}/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Total Production Emissions", \
    "description": "Sum of all production emissions per batch", \
    "expression": "_expected_field_id", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "type": "EXPECTED_FIELD", \
        "refId": "expected-field-uuid", \
        "aggregateFn": "sum" \
      } \
    ] \
  }'

Parameters​

expression
string or null

The mathematical expression. You can reference variable values using the escaped refId. To escape the refId, replace any dashes with underscores and add an underscore prefix.

emissionImpactType
string or null
Enum: "SEQUESTRATION" "EMISSION"
Array of any or null
label
string or null
description
string or null

Understanding Expressions​

Expressions are mathematical formulas that reference variables in the Formula. Each Variable can refrence another Field or Formula. Variables are referenced using their escaped refId.

Escaping Variable IDs​

To escape a refId for use in the Formula's expression:

  1. Replace all dashes (-) with underscores (_)
  2. Add an underscore (_) prefix

Example:

  • refId: abcd-1234-efgh-5678
  • Escaped: _abcd_1234_efgh_5678

Expression Syntax​

Create field
curl -X 'POST' "/v0/field-libraries/{id}/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Emission Factor Calculation", \
    "expression": "_307d545b_6b93_4df9_8b09_4290150efd60 * _451e2f3c_0c8e_4d2a_9f4b_123456789abc * 100", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "refId": "307d545b-6b93-4df9-8b09-4290150efd60", \
        "type": "FIELD_OR_FORMULA" \
      }, \
      { \
        "refId": "451e2f3c-0c8e-4d2a-9f4b-123456789abc", \
        "type": "FIELD_OR_FORMULA" \
      } \
    ] \
  }'

Field Variable Types​

EXPECTED_FIELD​

References Expected Field Values from documents:

{
  "type": "EXPECTED_FIELD",
  "refId": "expected-field-uuid",
  "aggregateFn": "sum" // or "mean"
}

Aggregate Functions:

  • sum - Sum all values
  • mean - Average all values

MONITORING_PERIOD_START_DATE / END_DATE​

References monitoring period dates:

{
  "type": "MONITORING_PERIOD_START_DATE",
  "refId": "monitoring-period-uuid"
}

Marking Direct Emissions or Sequestration​

When creating fields for direct emissions or sequestration (not intermediary calculations), set the emissionImpactType:

  • EMISSION - For emissions that contribute to carbon footprint
  • SEQUESTRATION - For carbon removal/storage
Create field
curl -X 'POST' "/v0/field-libraries/{id}/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Direct Production Emissions", \
    "expression": "_energy_use * _emission_factor", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "energy-use" \
      }, \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "emission-factor" \
      } \
    ] \
  }'

Listing Fields​

To view all fields in a field library:

Get fields
curl -X 'GET' "/v0/field-libraries/{id}/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Response Schema​

emissionImpactType
required
string or null
Enum: "SEQUESTRATION" "EMISSION"
required
Array of any
id
required
string
label
required
string or null
description
required
string or null
expression
required
string or null
fieldLibraryId
required
string

Getting Field Details​

To retrieve details about a specific field:

Get field
curl -X 'GET' "/v0/fields/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Getting Field Values​

One can fetch the current value of a field which can originate from Expected Field Value. To retrieve the computed value of a field:

Get field values
curl -X 'GET' "/v0/fields/{id}/values" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

This returns either a single value (for non-batch fields) or a paginated list of values per batch (for batch fields).

Updating Fields​

To update a field:

Update field
curl -X 'PATCH' "/v0/fields/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Updated Field Name", \
    "expression": "_var_a + _var_b", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "type": "EXPECTED_FIELD", \
        "refId": "var-a-uuid", \
        "aggregateFn": "sum" \
      } \
    ] \
  }'

Deleting Fields​

To delete a field:

Delete field
curl -X 'DELETE' "/v0/fields/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Creating Formulas​

Formulas perform calculations by referencing other Fields and Formula within the same Model Section.

Creating a Formula​

To create a formula within a section, use POST /v0/model-sections/{id}/formulas:

Create formula
curl -X 'POST' "/v0/model-sections/{id}/formulas" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Net Carbon Stored", \
    "description": "Total sequestration minus total emissions", \
    "expression": "_sequestration_total - _emission_total", \
    "emissionImpactType": "SEQUESTRATION", \
    "variables": [ \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "sequestration-field-uuid" \
      }, \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "emission-field-uuid" \
      } \
    ] \
  }'

Formula Variable Types​

FIELD_OR_FORMULA​

References other Fields or Formulas in the model:

{
  "type": "FIELD_OR_FORMULA",
  "refId": "field-or-formula-uuid"
}

MONITORING_PERIOD_START_DATE / END_DATE​

Same as for Fields - references monitoring period dates.

Listing Formulas​

To view all formulas in a section:

Get formulas
curl -X 'GET' "/v0/model-sections/{id}/formulas" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Response Schema​

emissionImpactType
required
string or null
Enum: "SEQUESTRATION" "EMISSION"
id
required
string
label
required
string or null
description
required
string or null
expression
required
string or null
required
Array of objects (FormulaVariable)
sectionId
required
string

Getting Formula Details​

To retrieve details about a specific formula:

Get formula
curl -X 'GET' "/v0/formulas/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Getting Formula Values​

To retrieve the computed value of a formula:

Get formula values
curl -X 'GET' "/v0/formulas/{id}/values" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Updating Formulas​

To update a formula:

Update formula
curl -X 'PATCH' "/v0/formulas/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Updated Formula Name", \
    "expression": "_field_a * (_field_b + _field_c)", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "field-a-uuid" \
      }, \
      { \
        "type": "FIELD_OR_FORMULA", \
        "refId": "field-b-uuid" \
      } \
    ] \
  }'

Deleting Formulas​

To delete a formula:

Delete formula
curl -X 'DELETE' "/v0/formulas/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Carried Forward Emissions Example​

For LCA emissions carried over from a prior monitoring period:

Create field
curl -X 'POST' "/v0/field-libraries/{id}/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "label": "Carried Forward Production Emissions", \
    "description": "Emissions from previous period batches used in current period", \
    "expression": "_prev_emissions * _fraction_used", \
    "emissionImpactType": "EMISSION", \
    "variables": [ \
      { \
        "type": "EXPECTED_FIELD", \
        "refId": "previous-period-emissions-uuid", \
        "aggregateFn": "sum" \
      }, \
      { \
        "type": "EXPECTED_FIELD", \
        "refId": "fraction-material-used-uuid" \
      } \
    ] \
  }'

Best Practices​

  1. Test expressions - Verify your mathematical expressions are correct
  2. Use clear names - Make field and formula labels self-explanatory
  3. Document calculations - Use descriptions to explain complex formulas
  4. Mark emissions correctly - Set appropriate emissionImpactType values
  5. Organize logically - Group related calculations together
  6. Reference methodology - Ensure calculations align with your methodology
  7. Validate outputs - Check computed values make sense

Common Calculation Patterns​

Simple Multiplication​

expression: "_quantity * _factor"

Sum with Conversion​

expression: "(_value_a + _value_b) * 0.001"

Percentage Calculation​

expression: "(_numerator / _denominator) * 100"

Conditional Logic (using formulas)​

Build separate fields for each condition, then combine in a formula.

Next Steps​

With your fields and formulas configured, you're ready to upload evidence and submit Expected Field Values to populate these calculations.