Data Description and Requirements
This document summarizes the producer-level and associated third-party data collected by the ESMC portal. The objectives of this document are to provide the reader with the following:
- an understanding of the data being collected;
- an overview of the database structures employed to collect and manage the data; and
- an introduction on how to utilize and read the detailed data specifications given as part of the OpenAPI specification at https://www.esmcportal.org/wp-content/oapi, which is the definitive source of record for the data and its interpretation.
Please note that in addition to collecting producer data, the ESMC portal imports data from other platforms, integrates third-party data, generates data, and exports data. An overview of this data is provided below.
Data Intake
Data is collected by the ESMC portal through the following, non-exclusive methods.
- Direct data entry into the portal (https://producer.esmcportal.org)
- Import through the ESMC API (see https://www.esmcportal.org/wp-content/oapi for details).
- Use-case specific manual or scripted inputs directly into the database.
- (Future) Producer-initiated import from another platform.
In addition to collecting the data from various sources, the data requested and required by ESMC varies based on the asset or credit for which the producer (or project) is seeking. The five assets and credits presently supported by the portal are as follows:
- Scope 1 Green House Gas (GHG) Credit
- Scope 1 Water Quality (WQL) Credit
- Scope 3 GHG Asset
- Scope 3 WQL Asset
- Scope 3 Water Quantity (WQN) Asset
The data requirements for each credit/asset are given below.
Data Structure
The ESMC database is structured in an hierarchical manner as illustrated in the following image. In general terms, every project has a list of producers, each producer has a set of fields (which can change on an annual basis), each field has crops and herds which change over time, and each crop and herd are managed with a program.
As noted above, the master data specification for each of the above components is maintained in an OpenAPI format at https://www.esmcportal.org/wp-content/oapi). However, for the reader’s convenient, the following is provided as an introduction to the OpenAPI specification and as a quick data overview summary. For detailed specification, direct links to the relevant OpenAPI specification are provided for the readers convenience.
Since the OpenAPI specification may be new to the reader, the following graphic has been created using the Drainage Component to explain how to read the documentation. As shown, the Drainage Component collect 4 data inputs: percentOfField, tileDepth, treatmentTypes, and treatmentPercentOfFields. Also note that these parameters are required for all credits and assets except for Scope 3 Water Quantity assets as stated in the top table.
Furthermore, note that a description for each parameter (unless the description is self-explanatory, e.g., percentOfField), the valid range of the input parameter, the units of the parameter (when applicable), and the allowable parameter options are provided.
A detailed description of each data element collected on import or provided on export is provided as shown in the following figure. Simply click on a component in the left toolbar to see the detailed data specification for that component. Also, please note that while an example JSON file is given for each component in the right panel (not shown), the JSON format is provided as an aid to the developers and is not needed to understand the parameters.
Data Components
A summary of the data collected for ESMC is organized below by the above data components.
Project Information
The data collected for each project includes the following:
| Parameter | Description | Example |
| project | The name of the project | TNC Minnesota Project |
| id | An internal UUID used to reference the project in the database | 5f6392058a936e07360cca91 |
| date | The last date the project was updated | Thu Apr 15 2021 16:49:01 GMT+0100 (Ame) |
| version | The version number of the data structures | 1 |
| assets | The GHG, WQL, and WQN credits/assets the project is applying for | Scope 1 GHG Credit Scope 1 WQL Credit |
Producer Information
The data collected for each producer enrolled in ESMC is summarized below.
| Parameter | Description | Example |
| name | The name of the producer | John Smith |
| address | The producer’s address | 10 Main Street |
| city | The producer’s city | Centerville |
| state | The producer’s state | Illinois |
| zip | The producer’s US postal code | 61820 |
| phone | The producer’s phone number | 555-555-5555 |
| The producer’s email address | producer@email.com | |
| userByProjectId | An automatically generated anonymized id for the producer | TNCMN-Producer-1 |
| id | An internal UUID used to identify the user in the database | 5f6392058a936e07360cca91 |
| narrative | Historical information about the producer’s farm | (see narrative below) |
Field Information
The data collected for each of the producer’s fields is summarized below. A detailed summary follows the table below and is given at https://www.esmcportal.org/wp-content/oapi/#tag/model_field.
| Parameter | Description | Example |
| name | The name of the field | East 80 |
| fieldByProjectId | An automatically generated anonymized id for the field | TNCMN-Field-1 |
| id | An internal UUID used to identify the field in the database | 5f6392058a936e07360cca91 |
| description | A description of the field and the practices on the field as provided by the producer | Tried using with covers over the last 5 years. Recently, included livestock grazing in recent years. Have been practicing conservation till for the last 7 years. |
| boundary | The GIS coordinates of the field boundary | (See field) |
| area | The area of the field in acres | 82.43 |
| crops | The crops planted on the field for one or more growing seasons | (See crops) |
| tract | The FSA tract number | |
| ownershipType | The producer’s ownership status of the field | rented Options include the corporation-owned, individual-owned-private, individual-owned-multiple, leased, and rented. |
| leaseRentTermExpirationYear | The year producer’s lease expires | 2026 |
| irrigation | Details regarding the irrigation system | (See irrigation) |
| historicalPractices | A summary of the historical practices on the field | |
| what’sNew | The new practices that the producer is implementing that will qualify them for ESMC | Tillage Options include nutrientManagement, coverCrop, conservationPractices, tillage, prescribedGrazing, and other. |
Crop Information
The crop data collected for each field is summarized below.
| Parameter | Description | Example |
| name | The name of the crop | GMO corn |
| type | The crop type | Corn |
| yield | The crop yield in bu/acre | 210 |
| growingSeason | The growing season of the crop (the crop growing season is defined from harvest of the previous crop to harvest of the current crop) | (see growing season) |
| coverCrop | The details about the cover crop, if planted | (see covercrop) |
| residue | The details about the amount of residue left on the field after harvesting the previous crop | (see residue) |
| programName | The name of the program used to manage the crop | Conservation till corn |
| programDescription | A description of the program used to manage the crop | A conservation, strip till program |
| operations | The field operations used to manage the program | (see Operations) |
Operations
Data is collected in the ESMC portal for the following operations. Please note that only data for the operations that are performed on a specific field for each specific year needs to be collected.
- Baling: https://www.esmcportal.org/wp-content/oapi/#tag/model_baling
- Burning: https://www.esmcportal.org/wp-content/oapi/#tag/model_burning
- Cutting: https://www.esmcportal.org/wp-content/oapi/#tag/model_cutting
- Harvest: https://www.esmcportal.org/wp-content/oapi/#tag/model_harvest
- Manure fertilizer: https://www.esmcportal.org/wp-content/oapi/#tag/model_manureFertilizer
- Non-manure fertilizer: https://www.esmcportal.org/wp-content/oapi/#tag/model_nonManureFertilizer
- Planting: https://www.esmcportal.org/wp-content/oapi/#tag/model_planting
- Tillage: https://www.esmcportal.org/wp-content/oapi/#tag/model_tillage