CDOP v1-v2 Technical migration infographic

Light Dark

⚙️ For a technical audience

CDOP v1 → v2: Technical Migration Reference

Schema-level changes, field mappings, and the adapter pattern for migrating off the legacy CDOP JSON Schema files onto the standardized json_schema/ set.

Supported schemas effective 2026‑05‑26 · repo: Carbon-Data-Open-Protocol/Carbon-Data-Open-Protocol

Schema files

4 legacy → 11 current

additionalProperties

false → true (broad)

Required-object rule

any nested field required ⇒ object required

Enum source

CDOP Enumerated Values Lists.xlsx

Repo layout

json_schema/ — canonical, supported (v2)
  Location_Details.schema.json
  Project_Approach_Details.schema.json
  Issuances.schema.json
  Disclosures.schema.json
  Unit_Description.schema.json — new, no legacy counterpart
  Crediting_Period.schema.json — new
  Estimations.schema.json — new
  Co-Benefits.schema.json — new
  Durability_Permanence.schema.json — new
  Project_Finance.schema.json — new
  Full_List.schema.json — union of all supported schemas
  unmatched_enum_fields.csv — enum-typed fields with no workbook match → left unconstrained
json_schema_legacy/ — reference only, do not validate against
  location_details.json · project_approach_and_details.json · issuances.json · disclosures.json
  migration-guide.md
scripts/generate_json_schemas.py — Excel (field_path column) → nested-array JSON Schema

Standard entity objects (v2)

project project_stakeholder facility geolocation_file crediting_program methodology registry validation issuance

What changed across all schemas

Change	Detail
File naming	Legacy snake_case files (e.g. project_approach_and_details.json) → standardized Project_Approach_Details.schema.json
Payload shape	Flattened/mixed fields → grouped into fixed entity objects; a transformation layer is required if your current API flattens fields
additionalProperties	Set to true at top level and inside every entity object — undeclared/pass-through fields no longer fail validation
Required objects	An entity object is required if any field anywhere in its subtree — including fields nested inside its arrays — is required, not just direct fields
Validation style	Less emphasis on URI/email/phone formats, x_* extension patterns, and array-pairing rules; more emphasis on stable names, consistent nesting, and real enum constraints
Metadata annotations	x-cdop-field-id, x-cdop-cardinality, x-cdop-pre-issuance-inclusion, x-cdop-data-source, x-cdop-mutability, x-cdop-public-private — non-validating, for docs/UI/governance tooling

Field mapping example — Project Approach & Details (highest-impact schema)

−project.name

+project.project_name

−project.status / project.status_updated_at

+project.status[].project_status, .is_current // history array, no timestamp field

−project.identifiers[].identifier_type / .value // array

+project.project_id_type, project.project_id // single scalar pair only

−project.documents[].document_type / .link

+project.documents[].other_project_documentation_type / _link // still object array, fields renamed

−project_stakeholder.primary_developer.name

+project_stakeholder.project_developer_name

Migration impact by schema

Location_Details

Low

• Requires project, project_stakeholder, geolocation_file
• facility optional

Disclosures

Low

• list_of_landowners → project_stakeholder
• project_status removed

Issuances

High

• Consolidates to project + issuance
• Forecasts moved to Estimations

Project_Approach_Details

High

• Most fields renamed
• identifiers[] → single scalar pair

Recommended adapter patterns

Pattern 1 · recommended

Keep internal model, export CDOP separately

1. Keep current internal domain objects/relational model
2. Build a dedicated CDOP export mapper
3. Validate only the export payload against json_schema/*.schema.json

Pattern 2

Pre-validation normalization step

1. Rename fields
2. Move values into correct entity object
3. Split/align record collections; strip unsupported extras

Pattern 3

Layer schema + business validation

1. Schema validation for CDOP contract compliance
2. Business validation for org rules: URI/email/phone format, duplicate detection, cross-array alignment, date sequencing

Migration checklist

Update schema file references to json_schema/*.schema.json

Regenerate typed models / DTOs / OpenAPI components from the new files

Add a transformation layer: legacy payload shape → new CDOP entity-object shape

additionalProperties: true is set — extra fields won't fail validation

Move renamed/relocated fields into their new entity sections

Collapse project.identifiers[] into project_id_type / project_id

Use each field's generated enum list instead of free text

Check unmatched_enum_fields.csv for enum fields left unconstrained

Keep legacy-only business rules as a second validation layer if still needed

Test sample submissions against the new schema before switching production

Source: json_schema_legacy/migration-guide.md, Carbon-Data-Open-Protocol/Carbon-Data-Open-Protocol. New schemas effective 2026‑05‑26. Field mappings shown are illustrative highlights, not the full table — see the migration guide for the complete schema-by-schema field list.