Skip to main content

Creating Expected Fields

Using Expected Fields to Collect Data from Evidence​

Expected Fields are defined data inputs within Document Instances that can be referenced in Models. They represent the specific values you need to collect to perform calculations, such as:

  • Production quantities
  • Emission factors
  • Carbon Content
  • Boolean confirmations
  • Aggregated calculations from evidence

Field Types​

Expected Fields support several data types:

NUMERIC​

For numerical values with optional units and validation ranges.

TEXT​

For text-based inputs.

DATE​

For date and time values with optional min/max validation.

BOOLEAN​

For yes/no or true/false inputs.

AGGREGATE_REF​

For aggregated calculations (SUM, AVG) from evidence template columns.

Field Validation​

Expected Fields can include validation constraints:

Numeric Fields​

  • minValue - Minimum acceptable value
  • maxValue - Maximum acceptable value
  • unit - Unit of measurement

Date Fields​

  • minDate - Earliest acceptable date
  • maxDate - Latest acceptable date

These constraints help ensure data quality when Expected Field Values are submitted.

Creating Expected Fields​

To create an expected field, use POST /v0/expected-fields:

Creating a Numeric Field​

Create expected field
curl -X 'POST' "/v0/expected-fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "NUMERIC", \
    "documentInstanceId": "document-instance-uuid", \
    "label": "Total Production Weight", \
    "unit": "kg", \
    "minValue": "0", \
    "maxValue": "1000000" \
  }'

Creating a Text Field​

Create expected field
curl -X 'POST' "/v0/expected-fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "TEXT", \
    "documentInstanceId": "document-instance-uuid", \
    "label": "Supplier Name" \
  }'

Creating a Date Field​

Create expected field
curl -X 'POST' "/v0/expected-fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "DATE", \
    "documentInstanceId": "document-instance-uuid", \
    "label": "Production Date", \
    "minDate": "2024-01-01T00:00:00Z", \
    "maxDate": "2024-12-31T23:59:59Z" \
  }'

Creating a Boolean Field​

Create expected field
curl -X 'POST' "/v0/expected-fields" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "BOOLEAN", \
    "documentInstanceId": "document-instance-uuid", \
    "label": "Quality Check Passed" \
  }'

Listing Expected Fields​

To view all expected fields:

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

Response Schema​

type
required
object
Default: "NUMERIC"
unit
required
string or null
minValue
required
string or null
maxValue
required
string or null
id
required
string
documentInstanceId
required
string
label
required
string

Getting a Specific Expected Field​

To retrieve details about a specific expected field:

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

Updating Expected Fields​

To update an expected field, use PATCH /v0/expected-fields/{id}:

Update expected field
curl -X 'PATCH' "/v0/expected-fields/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "NUMERIC", \
    "label": "Updated Field Name", \
    "unit": "tonnes", \
    "minValue": "0", \
    "maxValue": "5000000" \
  }'
Type Required

When updating an expected field, you must include the type parameter matching the field's original type.

Deleting Expected Fields​

To delete an expected field:

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

Using Expected Fields in Models​

Expected Fields serve as the data inputs for your Model calculations. When creating Fields in your Model (covered in a later section), you'll reference these Expected Fields to:

  • Pull values from evidence submissions
  • Perform calculations
  • Aggregate data across batches
  • Track emissions and sequestration

Next Steps​

With Expected Fields defined, you can now create Evidence Requests to specify when and how this data should be collected.