Jira progress: loading…

FOGE

FOGE -Form Generator Engine

Add to the Pages text (EcoWorld Manual)

FOGE output: database or YAML/JSON?

For 20–30 active forms, storing the canonical form definitions as source-controlled files is preferable to making the database the only source of truth.

However, I would not choose exclusively between files and database storage. The robust model is:

Authoritative form definitions
        │
        ▼
YAML source files
        │
        ▼
Schema validation and compilation
        │
        ▼
Canonical JSON release bundle
        │
        ├── runtime database projection
        ├── search projection
        ├── UI form rendering
        └── CUP bindings

Recommended separation

1. FOGE form definitions

Store the definitions as version-controlled YAML.

Example:

/foge/
├── frameworks/
│   └── esrs/
│       └── 1.0.2/
│           ├── framework.yaml
│           ├── forms/
│           │   ├── esrs-2-general-disclosures.yaml
│           │   ├── esrs-e1-climate-change.yaml
│           │   ├── esrs-e2-pollution.yaml
│           │   └── ...
│           ├── items/
│           ├── rules/
│           ├── mappings/
│           └── manifest.yaml

YAML is convenient for human maintenance because it supports readable multiline text and comments.

Example:

form_id: FOGE-ESRS-E1
framework_id: ESRS
framework_version: 1.0.2
title: ESRS E1 Climate Change
status: active

sections:
  - section_id: E1-1
    title: Transition plan for climate change mitigation
    items:
      - item_id: ESRS-E1-1-01
        type: narrative
        required_when:
          rule_ref: ESRS-E1-APPLICABILITY-001

2. Canonical compiled representation

At release time, compile the YAML into deterministic canonical JSON.

Example:

/dist/foge/esrs/1.0.2/foge-esrs-1.0.2.json

The canonical JSON should:

• have normalized ordering;
• contain no comments;
• resolve internal references;
• pin item and rule versions;
• include a content digest;
• be digitally signable;
• support deterministic replay.

This yields:

YAML = authoring representation
JSON = canonical machine representation

3. Runtime database projection

Load the canonical release into database tables for efficient runtime querying.

For example:

foge_framework_releases
foge_forms
foge_form_versions
foge_sections
foge_items
foge_item_versions
foge_form_item_memberships
foge_item_relationships
foge_rules
foge_mappings

This projection is useful even with only 20–30 forms because each form may contain hundreds or thousands of:

disclosure requirements;

• data points;
• conditions;
• relationships;
• enumerations;
• validation rules;
• presentation instructions;
• calculation dependencies.

The number of forms is not the most important scaling dimension. The important dimensions are:

forms × items × versions × organizations × reporting periods

Twenty forms may still produce millions of organization-level state and response records.

What belongs in files and what belongs in the database?

Information	Canonical storage
FOGE form definition	YAML source plus canonical JSON release
Framework item definition	YAML/JSON package
Item relationships	YAML/JSON package
Validation rule definition	YAML/JSON package
CUP-to-FOGE mappings	CUP package files or governed mapping package
Active FOGE release metadata	CPR/configuration plus runtime projection
Organization applicability	Database
Organization item state	Database
Responses and values	Database
Evidence links	Database
Confidence assessments	Database/artifact store
Validation results	Database/artifact store
Published completed form	Immutable JSON artifact/object storage

Do not store organization responses in YAML files

The following are operational and should remain in the database:

ECO-000-000-001-01
    ├── ESRS E1 applicable
    ├── E1-6 partially complete
    ├── reported value: 12,500 tCO2e
    ├── evidence references
    ├── confidence: 0.91
    └── validation outcome

These values are:

• tenant-specific;
• frequently updated;
• temporally versioned;
• permission-sensitive;
• query-intensive;
• transaction-dependent;
• subject to concurrent workflows.

Files are not a good primary persistence mechanism for this data.

FOGE release model

Each FOGE release should be immutable.

Example:

release_id: FOGE-ESRS-1.0.2
framework_id: ESRS
version: 1.0.2
status: active
content_digest: sha256:...
supersedes: FOGE-ESRS-1.0.1

A later correction produces: FOGE-ESRS-1.0.3

It does not modify 1.0.2.

CUP mappings must pin the release:

package_id: cup.esg.esrs
package_version: 2.1.0

foge_dependencies:

text
  - release_id: FOGE-ESRS-1.0.2
    content_digest: sha256:...

Recommended final model

FOGE source repository
├── YAML definitions
├── JSON Schemas
├── validation rules
├── tests
└── release manifests
        │
        ▼
FOGE compiler
        │
        ├── validates
        ├── resolves references
        ├── canonicalizes
        ├── calculates digest
        └── produces signed JSON release
                │
                ├── runtime database projection
                ├── CPR/CUP dependency resolution
                ├── form-rendering service
                └── immutable artifact storage

This provides the simplicity appropriate for 20–30 active form definitions without sacrificing runtime performance, governance, versioning, or replayability.

The governing rule should be:

FOGE definitions are source-controlled and released as immutable canonical JSON; organization-specific form states, responses, evidence and assessments are stored in governed database tables.

---