froga.yaml Reference

🟡 Partial — The schema is v1alpha1: the field set described here is implemented, but the schema version still evolves alongside the engine (it may change without notice between versions).

froga.yaml is the AI system manifest the engine reads at the start of every subcommand. It is the single declarative file: each repository contains exactly one froga.yaml at its root and governs a single system. It declares the system’s intended purpose, the task, the regulatory context, the evaluation pipeline, and the risk programme (Art. 9) inline, in the risk section.

froga init generates a minimal froga.yaml if one does not exist. The oscal.assessment_plan field is populated by froga compile.

Evidence signing

The evidence the engine derives from this manifest (.froga/bundle.json and the other artifacts) is signed with ECDSA-P256 (RFC 6979) + DSSE + in-toto, via a pluggable signer (local or Scaleway KMS, per FROGA_SIGNING_BACKEND). See Sign and verify evidence.

---

Example manifest — a credit system

The following manifest is an illustrative example of a consumer credit system (high-risk, EU AI Act Annex III §5), meant to teach the structure of a froga.yaml. The values are indicative; adapt them to your own system:

froga.yaml — credit system (tabular / classification)

apiVersion: venturalitica.ai/v1alpha1
kind: AISystem

# 1. System identity and intended purpose
system:
  name: loan-scoring
  intended_purpose: "Scoring crediticio para aprobacion de prestamos al consumo."
  organization: acme-bank
  version: "1.0.0"
  decisions: [loan_approval, loan_denial]
  affected_persons: [solicitantes]
  component_type: ai-model
  # Reasonably foreseeable misuse (ISO 42001 6.1.4 / EU AI Act Art.9(2)(b));
  # `addressed_by` links each one to the risk(s) that address it.
  potential_misuses:
    - id: mu.proxy-discrimination
      description: "Introducir variables proxy de atributos protegidos para sortear los controles de equidad."
      addressed_by: [risk.unfair-credit-exclusion, risk.data-governance]

# 2. Nature of the task
task:
  modality: tabular
  type: classification

# 3. Regulatory context
context:
  applicable_standards:
    - eu/pren-18228@2026
    - iso/23894@2023
    - eu/ai-act@2024
    - eu/dora@2022

# 3b. Human-declared assessment (REQUIRED for `froga run`)
# The KAG is not available: the QM/dev declares the classification by hand.
classification:
  tier: high                                  # high | limited | minimal | prohibited
  basis:
    - "EU AI Act Annex III §5(b)"             # legal basis of the classification
  rationale: |
    Credit scoring that governs access to consumer credit (high-risk, Annex III §5).

# 4. Data and model
dataset: { croissant: data/german_credit.croissant.json }   # eval loads the dataset via Croissant
artifacts:
  model: { kind: logreg, seed: 42 }

# 5. Measurement and reproduction
eval: { script: train.py }   # the WHAT: the TREATMENT (training variant; its digest → model drift)
pipeline: { tool: dvc, metrics: metrics.json, params: params.yaml }   # the HOW: reproducible recomputation (dvc repro → dvc.lock)
oscal: { assessment_plan: shared_data/policies/assessment_plan.oscal.yaml }   # generated by froga compile

# 6. Risk programme (Art.9) — formerly a separate file; now inline
risk:
  appetite: { individual: MEDIUM, society: MEDIUM, organization: HIGH }   # inherent HIGH exceeds MEDIUM → treatment required (6.4.4)
  criteria: { scale: "5x5" }
  overall_residual_criterion: HIGH   # prEN 18228 cl. 10: GLOBAL residual criterion (≠ per-risk appetite)
  risks:
    - id: risk.unfair-credit-exclusion
      title: "Unfair Credit Exclusion of Minorities"
      impact: { individual: HIGH, society: HIGH, organization: HIGH }
      likelihood: LIKELY            # ISO 6.4.3 analysis — inherent LIKELY×HIGH = HIGH
      treat:
        - method: REDUCE
          action: "Acotar la paridad demográfica de la decisión y el balance de clase por grupo."
          controls: [eu/ai-act@2024#art-15]
          residual_likelihood: UNLIKELY   # 6.5 target; held-out n=200, the CI crosses the threshold → INCONCLUSIVE (does not confirm)
          measures:
            - id: unfair-credit-exclusion
              metric: demographic_parity_diff
              constraint: "< 0.092"
              severity: high
              enforcement: gate
              lifecycle: [validation]
              article: "15"
              control_tier: protective
              standard_clauses: ["eu/pren-18228@2026#9.2", "iso/23894@2023#6.5"]
              inputs: { prediction: prediction, dimension: gender }
  applicability: {}

The risk register is now a section of froga.yaml (risk.risks[]), not a separate AssuranceProgram.yaml file. The full structure of each risk and measure is described in AssuranceProgram / OSCAL.

---

Field reference

apiVersion

Type: string — Current value: venturalitica.ai/v1alpha1

Schema version. The v1alpha1 prefix indicates the structure may evolve without backward compatibility until the engine reaches API stability.

---

kind

Type: string — Current value: AISystem

Resource type discriminator. Reserved for future extension (e.g. AIDataset, AIPipeline).

---

system

System identity and scope metadata.

Field	Type	Description
name	string	System identifier. Appears in the evidence bundle and in the Annex IV the cloud assembles.
intended_purpose	string	Intended purpose of the system (EU AI Act Art. 13(3)(b); Annex IV §1). Changing this field may trigger Drift A (mandatory re-triage).
organization	string	Organisation responsible for the system.
version	string	System version (semver). Appears in Annex IV §1.
decisions	list	Decisions the system makes (e.g. loan_approval, loan_denial). Consumed by froga impact.
affected_persons	list	Categories of persons affected by the system’s decisions.
component_type	string	AI component type (e.g. ai-model).
potential_misuses	list	Reasonably foreseeable misuse (ISO 42001 §6.1.4 / EU AI Act Art. 9(2)(b)). Each entry has id, description, and addressed_by (ids of the risks that address it). froga impact flags unaddressed misuse as a GAP (advisory).

system.potential_misuses[]

Field	Type	Description
id	string	Misuse case identifier (e.g. mu.proxy-discrimination).
description	string	Description of the unintended but anticipable use.
addressed_by	list	Ids of risk.risks entries that address it; empty = unaddressed (advisory).

---

context

Regulatory context of the system.

Field	Type	Description
applicable_standards	list	Canonical ids of the applicable standards (e.g. eu/pren-18228@2026, iso/23894@2023, eu/ai-act@2024, eu/dora@2022). The first one is the highest priority. froga conformance without --standard emits all those with a clause catalog.

---

task

Describes the nature of the AI task.

Field	Type	Known values	Description
modality	string	tabular, image, text, …	Input data modality. Determines which bias and performance metrics are relevant. Free-form string (no enum); the froga init skeleton names tabular, image, text.
type	string	classification, segmentation, …	Task type (read by the engine from the manifest). Free-form string (no enum). In the future it will inform the KAG which risks to propose; today risks are declared by hand.

Medical scenario

In medical, modality: image and type: segmentation. The engine does not change; only the metric selection in the evaluation script and the risks the team declares.

---

classification

Required for froga run. Human-declared assessment: the Quality Manager / dev declares the system’s classification by hand (the KAG that would propose it is a future line, not available today). If this block is missing, froga run aborts with an explicit error: “El manifiesto no declara classification. El KAG no está disponible — declara la evaluación a mano en froga.yaml (tier/basis/rationale) y commitea.”

Field	Type	Description
tier	enum	Risk category of the system. Values: high, limited, minimal, prohibited.
basis	list	Legal basis of the classification (e.g. "EU AI Act Annex III §5(b)"). Optional; empty by default.
rationale	string	Justification for why the system falls into that tier. Optional; supports multi-line text.

The classification travels signed in the evidence bundle. froga init leaves this block commented out as TODO: fill it in before the first froga run.

---

eval

Field	Type	Description
script	path	The WHAT: the treatment. Points to the evaluation/training script. The digest of this file, together with the resulting model digest, enters froga.lock. A script change triggers Drift B (re-measurement without re-triage if the intended purpose does not change).

The eval.script defines the treatment variant: the difference between model V1 and V2 is a change to this script. See Treatment modalities.

---

pipeline

Field	Type	Known values	Description
tool	string	dvc, mlflow, dagster	Selects the Reproducer seam adapter. The Rust core never imports the tool directly: the adapter encapsulates the corresponding CLI invocation (dvc repro, mlflow run, dagster job execute).
metrics	path	—	Path to the JSON metrics file the pipeline writes after execution, of the form { measure-id: value } (the key is each measures[] id, not the value of its metric field). The engine reads it and matches each key against the OSCAL control-id to evaluate the risk gate controls.
params	path	params.yaml	Pipeline hyperparameter file. Its digest feeds the model-phase hash. Default: params.yaml.

All three backends are tested in CI. See Typed drift for the relationship between pipeline.tool and the pipeline_lock_digest in the bundle.

---

oscal

Field	Type	Description
assessment_plan	path	Path to the OSCAL assessment plan file generated by froga compile. Defines which controls are measured and under what conditions. The froga run gate consumes it to evaluate each control declared in the risk section.

This file is not edited by hand: it is an artifact derived from the risk section of froga.yaml. If the risk programme changes, run froga compile to regenerate it.

---

dataset

Field	Type	Description
croissant	path	Path to the dataset’s Croissant descriptor. The eval.script loads the dataset through this descriptor. Croissant-RAI allows declaring fairness metadata (distributions, sensitive attributes) which the team uses to declare bias risks (EU AI Act Art. 10; the future KAG will assist that identification).

---

artifacts

Declares system artifacts other than the script and dataset.

Field	Type	Description
model.kind	string	Model family or architecture (logreg, totalsegmentator, …). Informational; appears in the Annex IV.
model.seed	integer	Randomness seed for deterministic reproducibility of the pipeline.

---

risk

This is the assurance programme (EU AI Act Art. 9) inline, formerly a separate AssuranceProgram.yaml file. It configures the ISO 23894 risk model and holds the living risk register. Fields in this section govern the froga run risk gate, the OSCAL plan compilation by froga compile, and the froga conformance compliance evaluation.

Field	Type	Description
appetite	object	Risk appetite per impact dimension (see below).
criteria	object	Analysis criteria (the matrix scale).
overall_residual_criterion	enum	Criterion for the overall system residual risk (prEN 18228 cl. 10).
review_interval	string (ISO 8601)	Cadence of the periodic risk review (ISO 23894 §6.6); optional (see below).
risks	list	Risk register: each risk with its impact, likelihood, treatment (treat), and measures. Its full structure is documented in AssuranceProgram / OSCAL. Each risk can include optional canonical primitives from the agnostic risk model (see below).
applicability	object	Control applicability (Statement of Applicability); {} if nothing is declared.

The risk register grows during development; git blame on the risk section of froga.yaml is the risk identification audit log (ISO 23894 §6.4.2). See the froga CLI Reference for froga compile.

risk.risks[] — canonical primitives of the agnostic model

The following fields are optional (serde(default)) on each risk.risks[] entry. Their absence does not alter existing signed bundles (non-breaking). They are used by risk-projection catalogs (froga risk-projection) to map each risk to the vocabulary of the target framework:

Field	Type	Description
source	string (optional)	Risk source or origin (ISO 14971/prEN 18228 vocabulary: “hazard source”).
pathway	string (optional)	The pathway or mechanism through which the hazard leads to harm.
consequence	string (optional)	The final consequence or harm if the risk materialises.
benefit_risk	string (optional)	Benefit-risk assessment statement (ISO 14971 §9: justifies accepting the residual risk when the benefit outweighs the potential harm).

risk.appetite

Risk appetite per impact dimension. Each dimension accepts LOW, MEDIUM, HIGH, or CRITICAL.

Dimension	Description
individual	Impact on individual persons affected by system decisions.
society	Impact on groups, communities, or society as a whole.
organization	Impact on the organisation deploying the system.

The appetite is the evaluation threshold (ISO 23894 §6.4.4): a risk whose inherent level exceeds the declared appetite requires treatment before the risk gate can be green.

In loan, the individual and social appetite is MEDIUM; the inherent level of the unfair-credit-exclusion risk (gender discrimination) is HIGH, which requires the bias treatment (in the loan-scoring demo, the mitigate flag of params.yaml); with the underpowered held-out (n=200) evidence, the fairness control reads INCONCLUSIVE rather than green.

risk.criteria

Field	Current value	Description
scale	"5x5"	Analysis matrix scale: Likelihood (1–5) × Impact (1–5) = level 1–25, mapped to LOW/MEDIUM/HIGH/CRITICAL. Fixed at 5x5; other scales are not implemented in v1alpha1.

risk.overall_residual_criterion

Type: LOW | MEDIUM | HIGH | CRITICAL

Criterion for the overall system residual risk (prEN 18228 cl. 10). This is distinct from the per-risk appetite: while the appetite evaluates each individual risk, overall_residual_criterion evaluates whether the sum of individual residuals keeps the system within an acceptable range for the system as a whole.

In v1alpha1 this criterion is reported as advisory by froga conformance; see Status & gaps.

risk.review_interval

Type: a string with an ISO 8601 duration (e.g. P6M = six months, P1Y = one year). Optional.

Declares the cadence of the periodic risk review (ISO 23894 §6.6). It enters the signed evidence bundle, so froga reconstruct can determine when the review falls due by TIME: an approval older than review_interval reopens the cycle (state “under periodic review”) until management approves again. The review is recorded with froga review (a commit with the Froga-Reviewed-by: trailer). The loan scenario declares P6M (semi-annual review).

Medical scenario — differences

In medical, the manifest sets all appetite dimensions to HIGH, reflecting the risk profile of medical imaging (EU AI Act Art.6(1) — safety component of a SaMD medical device, MDR Class IIb). The treatment modality is human HOTL oversight (Art.14) plus the audit of the per-subgroup Dice gap (a confirming control in audit mode), not a code change to the BYO model (totalsegmentator).

See The two gates for the relationship between both scenarios and the same engine.

---

roles

Optional. Declares the EU AI Act role of the system (Art. 3 / Art. 25). froga run seals it in the signed bundle; the cloud reads it from the verified bundle (never from the database or unsigned config).

roles:
  - role: provider                   # provider | deployer | importer | distributor |
                                     # authorised_representative | product_manufacturer |
                                     # gpai_provider | integrator
    since: "2026-01-01"              # date the role was assumed (ISO 8601)
    market_phase: placed_on_market   # research | development | real_world_testing |
                                     # placed_on_market | put_into_service
    # trigger / supersedes (Art. 25) — optional

The field is key-specific (non-transferable): it is signed with the ECDSA-P256 key of that system’s engine; it cannot be transferred to another system without re-signing. The cloud shows the role in Annex IV only when it comes from the verified bundle.

---

Manifest lifecycle

froga init          →  creates minimal froga.yaml (if it does not exist)
[edit froga.yaml]   →  declare system, task, context, classification (required), pipeline and the risk section
froga compile       →  generates oscal.assessment_plan from the risk section of froga.yaml
froga run           →  reads full froga.yaml; risk gate; writes .froga/bundle.json

The Annex IV (EU AI Act Art. 11) is not emitted by the engine: it is assembled and rendered by the control plane (the cloud) from the signed bundle.json. See The .froga/* artifacts.

Consult the froga CLI Reference for the flags of each subcommand.