HomeSupportContact UsAbout

Chapter 9: Project Design Document (PDD) Schema Development

This chapter teaches you how to build Guardian schemas step-by-step for PDD implementation. You'll learn the exact field-by-field process used for VM0033, translating methodology analysis from Part II into working Guardian schema structures.

By the end of this chapter, you'll know how to create the VM0033 PDD schema like structure yourself, understanding each Guardian field type, conditional logic implementation, and how methodology parameters become functional data collection forms.

Guardian Schema Development Process

Complex Guardian schemas can be built using Excel templates that define the data structure, and then imported into Guardian. The schema template shows all available field types and their configuration options.

Alternative Schema Building Methods:

  • Excel-first approach (recommended for complex methodologies): Design in Excel, then import - covered in this chapter

  • Guardian UI approach: Build directly in Guardian interface - see Creating Schemas Using UI

Excel-first approach also enables easier collaboration with carbon domain experts and non-technical stakeholders to provide better feedback with back-and-forth when schemas are complex.

PDD Schema Screenshot

Schema Template Structure

Every Guardian schema follows this Excel structure:

Required Field
Field Type
Parameter
Visibility
Question
Allow Multiple Answers
Answer

Yes/No

String/Number/Enum/etc

Reference to enum

TRUE/FALSE/hidden

User-facing question

Yes/No

Default value

Field Configuration Meaning:

  • Required Field: Whether users must complete this field before submission

  • Field Type: Data type (String, Number, Date, Enum, Boolean, Sub-Schema, etc.)

  • Parameter: Reference to enum options or calculation parameters

  • Visibility: Field display conditions (TRUE=always visible, FALSE=hidden unless condition met)

  • Question: Text that users see as the field label

  • Allow Multiple Answers: Whether field accepts multiple values

  • Answer: Default value or example shown to users

Building the Primary Schema Structure

Let's build a PDD schema step-by-step, starting with the main schema definition like VM0033's "Project Description (Auto)" tab.

Project description tab Excel Screenshot

Step 1: Create Main Schema Header

Start your Excel file with these header rows:

This establishes your schema as a Verifiable Credentials type that Guardian will process into on-chain records.

Step 2: Add Certification Pathway Selection

The first functional field should be your primary conditional logic driver. For VM0033, this is certification type selection:

This creates an enum field that determines which additional requirements appear. The parameter reference "Choose project certific (enum)" points to a separate enum tab defining the options.

Create the Enum Tab: Add a new worksheet named "Choose project certific (enum)" with(sheet names might be trimmed to accomodate excel's limitations):

Step 3: Add Conditional Sub-Schemas

Based on the certification selection, different sub-schemas should appear. Add conditional schema references:

The VCS sub-schema always appears (TRUE visibility), while CCB appears only when CCB certification is selected (FALSE = conditional visibility based on enum selection).

Step 4: Create Sub-Schema Structures

VCS Project Description Sub-Schema

Create a new worksheet "VCS Project Description v4.4" with basic project information:

CCB Sub-Schema (Conditional)

Create "CCB" worksheet for additional community/biodiversity requirements:

Implementing Project Information Fields

Geographic Data Capture

Add geographic information fields to your main schema or sub-schema:

Create the unit selection enum tab "AcresHectares (enum)":

Project Timeline Fields

Adding Methodology-Specific Parameters

Now translate your Part II parameter analysis into Guardian fields. For VM0033's biomass parameters:

Step 1: Add Parameter Collection Fields

Step 2: Add Calculation Method Selection

Create the method enum tab:

Step 3: Add Method-Specific Parameter Fields

Add conditional fields that appear based on method selection:

These fields have FALSE visibility, meaning they appear conditionally based on the method selection enum.

Integrating AR Tools and External Modules

Adding AR Tool Integration

VM0033 uses AR Tool 14 for biomass calculations. Add tool integration:

Create AR Tool Sub-Schema

Create "AR Tool 14" worksheet for tool-specific parameters:

Implementing Baseline and Project Calculations

Baseline Scenario Fields

Create a sub-schema for baseline emissions:

Create "(New) Final Baseline Emissions" worksheet:

Project Emissions Structure

Similarly create project emissions calculation fields:

Advanced Field Types and Features

Auto-Calculate Fields

For calculated results that update automatically:

File Upload Fields

For evidence documentation:

Help Text Fields

Add contextual guidance:

Hidden Fields for System Use

Conditional Logic Implementation

Simple Conditional Visibility

Use TRUE/FALSE in the Visibility column:

  • TRUE: Always visible

  • FALSE: Visible only when referenced condition is met

  • Hidden: Never visible to users (system fields)

Complex Conditional Logic

For multiple conditions, Guardian evaluates enum selections to determine field visibility. The FALSE visibility fields become visible when their referenced enum is selected appropriately.

Quality Control and Validation

Required Field Validation

Use "Yes" in Required Field column to enforce completion:

Data Type Validation

Guardian automatically validates based on Field Type:

  • Number: Only accepts numeric values

  • Date: Validates date format (2000-01-01)

  • Email: Validates email format

  • URL: Validates URL format

Pattern Validation

For custom validation patterns:

Testing Your Schema Structure

Validation Checklist

Before importing to Guardian, verify:

Import Testing and Schema Refinement

  1. Save Excel file with proper structure

  2. Import to Guardian

  3. Test conditional logic with different selections

  4. Validate auto-calculate fields

  5. Review and rename field keys for meaningful calculation code

  6. Update the schema ID in relevant policy workflow block

alt text

Important: Field Key Management

When Guardian imports Excel schemas, it generates default field keys that may not be meaningful for calculation code. For example:

  • Excel field "Biomass density (t d.m. ha⁻¹)" becomes field key "G5" as per excel cell it was found in

  • Default keys make calculation code harder to read and maintain

Best Practice: After import, open the schema in Guardian UI to rename field keys:

  1. Navigate to schema management in Guardian

  2. Open your imported schema for editing

  3. Review each field's "Field Key" property

  4. Rename keys to be calculation-friendly:

    • biomass_density_stratum_i instead of field0

    • carbon_stock_baseline_t instead of carbonStockBaselineT

    • emission_reduction_total instead of emissionReductionTotal

Guardian schema UI showing field key editing interface

Why This Matters: Meaningful field keys make calculation code much easier to write and maintain:

Connecting to Monitoring Schemas

Your PDD schema establishes the foundation that monitoring schemas build upon. Key connections:

Parameter Continuity

Ensure PDD parameters have corresponding monitoring equivalents:

  • PDD: Initial biomass density estimate

  • Monitoring: Annual biomass density measurements

Calculation Consistency

Use same parameter names and calculation approaches:

  • PDD parameter key: biomass_density_initial

  • Monitoring parameter key: biomass_density_year_t

Conditional Logic Alignment

Method selections in PDD should drive monitoring parameter requirements:

  • Direct method PDD β†’ Direct measurement monitoring fields

  • Indirect method PDD β†’ Indirect calculation monitoring fields

Best Practices Summary

Start Simple: Begin with basic project information, then add complexity systematically.

Test Incrementally: Validate each section before adding the next level of complexity.

Use Sub-Schemas: Break complex sections into manageable sub-schema components.

Plan Conditionals: Design conditional logic to reduce user interface complexity while maintaining requirement coverage.

Link to Analysis: Every parameter should trace back to specific methodology requirements from Part II analysis.

Validate with Stakeholders: Test schema workflows with actual Project Developers and VVBs before production deployment.

The next chapter builds on this PDD foundation to create monitoring schemas that handle time-series data collection and calculation updates over project lifetimes.

PreviousChapter 8: Schema Architecture and FoundationsNextChapter 10: Monitoring Report Schema Development

Last updated