Skip to main content

Specifications & Validation

The Smart EPD specification system is a declarative framework for defining validation rules, input forms, and compliance checks for EPDs and PCFs. A single specification encodes everything needed to validate a document, render an input form, and produce compliance reports, with inheritance allowing product-specific specifications to extend shared base specifications.

The specification chain​

Specifications exist at two levels, each inheriting from the one above:

Standard Specification defines baseline rules that apply across product categories: structural requirements from ISO 21930 or EN 15804.

PCR Specification inherits from the standard and adds category-specific rules: which modules must be declared, what impact categories are required, product-specific reporting formats, input validation ranges, required fields, field types and formats, and visibility rules based on product type.

The EPD Template is what results when the full chain is evaluated for a specific project. It is not separately authored; it is the combined, flattened output of both levels.

How inheritance works​

Each specification level can:

  • Add new requirements, fields, and constraints not present in the parent
  • Supersede inherited items — a child requirement or field with the same ID replaces the parent's version entirely
  • Remove inherited requirements or fields that don't apply (remove_requirement, remove_field overrides)
  • Amend specific parameters of inherited items without full replacement (amend_requirement, amend_field overrides)

Inheritance is resolved recursively. A specification can have multiple parents (via SpecInheritanceLink records with merge ordering). During resolution, parent specs are merged depth-first; child items supersede parent items on duplicate IDs, and unmatched parent items are preserved. Configuration blobs (bindings, normalizers, AI context, conventions) are deep-merged.

This means a concrete PCR specification doesn't need to redefine everything from scratch. It inherits the standard's structural requirements and only specifies what's different for concrete products.

Versioning​

Specifications follow semantic versioning:

  • Patch (1.0.0 → 1.0.1) -Minimal, non-breaking updates to the spec.
  • Minor (1.0 → 1.1) -Minor changes to the spec like requirement adjustments, new fields.
  • Major (1.x → 2.0) -Fundamental methodology changes. Does not auto-apply; existing projects stay on their current version.

What specifications define​

A specification contains several types of content:

Requirements (validation rules)​

Each requirement defines one or more checks that evaluate whether EPD data meets a specific criterion. Requirements have:

  • A type: direct (maps to a standard clause), derived (inferred from multiple clauses), or contextual (depends on product context)
  • A severity: error (must fix before publication), warning (should fix, not blocking), or info (informational)
  • One or more checks: the actual validation logic

Conditional guards​

Checks can be conditionally applied: they only run when certain conditions are met. This handles product configurations where validation rules vary by variant:

Example: "If product type is concrete, compressive strength must be declared" -the check for compressive strength only runs when the product type field equals "concrete".

Spec parameters (instantiation-time flags)​

Conditional guards react to document values — answers the manufacturer has already given. Spec parameters gate content on facts known before any document exists, decided when the spec is instantiated for an EPD.

A specification declares its parameters (each a boolean with a default, e.g. tool: false), and any requirement, input field, or field group can opt in with an include_if_params gate. When an EPD is created, the platform binds concrete values — the tool parameter follows the project's Is a Tool flag (the single, owner-editable source of truth for whether a project's EPDs come from a pre-verified tool), and admins can layer additional per-category overrides on top — then snapshots them onto the EPD alongside its pinned spec version. Everything downstream (the input form, document validation, the verifier checklist, AI conformance evaluation, and the rendered PDF) resolves through that binding, so a gated-off question or requirement simply does not exist for that EPD.

Example: the Smart EPD GPI declares a tool parameter. Its EPD Tool requirements (§6.12 — methodology report, representative-EPD verification, tool documentation, validity period, change log) are gated tool: true, so they only appear on checklists for EPDs in projects flagged as tools.

Parameters merge through the inheritance chain like other content (child redeclarations win), and the binding is editable while the EPD is a draft, frozen from submission onward.

Input fields (form definitions)​

Specifications also define input forms, which are the fields that EPD authors fill in. Each field has a type (text, number, select, date, file, etc.), validation rules, and conditional display logic (show/hide based on other field values).

Fields are organized into collapsible groups for a clean editing experience. When the specification chain resolves, the form is what manufacturers interact with to create EPDs.

Cross references​

Each requirement may reference one or more input fields via cross_ref_ids (an ordered list). Cross references let specs link a requirement clause directly to the field(s) that satisfy it.

  • Terminology -Platform concepts and constraint types reference
  • EPD Templating -How templates enforce constraints and handle out-of-bounds inputs