Configuration makes experiments reproducible only when it is validated and versioned. Unchecked YAML is untrusted input: a typo can change a threshold, a string can appear where a number was expected, and an unknown key can be silently ignored. Parse configuration into a strict schema, reject extras, and save the resolved configuration hash with every run.
Use YAML for research choices, not safety choices:
schema_version: 1
dataset:
source: fixture_v3
max_age_seconds: 900
required_fields: [source_id, observed_at_utc, bid, ask]
research:
hypothesis_id: baseline_spread_v1
min_observations: 30
abstain_on_missing: true
paper:
starting_points: 1000
max_points_per_event: 10
report:
timezone: Asia/Karachi
Notice what is absent: endpoint methods, credentials, account identifiers, currency, and an execution mode. The program always runs paper-only. source selects a known fixture or a public GET adapter from a code-owned registry; it cannot be an arbitrary URL.
Validation rules should be precise. schema_version must equal a supported integer. Ages and counts have sensible positive bounds. Starting points and per-event limits are fictional integers, with no conversion to money. Unknown keys cause an error. Normalize the validated object to canonical JSON and calculate SHA-256; store that hash as config_hash in each event.
Layer configurations in an explicit order: packaged defaults, a named project file, and safe command-line overrides. Print the resolved non-secret configuration at startup. Never allow environment variables to bypass schema validation. A run is reproducible when the repository commit, fixture hashes, config hash, and parser version are all known.
Failure cases
max_age_seconds: "fast" must fail. max_points_per_event: -5 must fail. live_execution: true must fail as an unknown key. A duplicated YAML key should be rejected by the loader rather than accepting the last occurrence. A newer schema version should stop with an upgrade message, not be guessed.
🇵🇰 Pakistan Angle
Use Asia/Karachi only for display; store event time in UTC. Do not encode country access assumptions in configuration. A Pakistan label changes presentation and regulatory notes, never venue eligibility. Keep low-data and outage-friendly schedules configurable so a learner can run from cached fixtures.
Hands-On Exercise
Create default.yaml, a strict settings model, and five invalid fixtures covering the cases above. Produce a run_manifest.json containing commit ID, config hash, fixture hashes, UTC start time, and application version. Rerun from the manifest and compare analytical output.
Completion Rubric
- YAML accepts research parameters but cannot enable execution.
- Types, ranges, versions, duplicate keys, and extras are checked.
- Resolved configuration is canonically hashed and stored per run.
- UTC storage and Pakistan-time display are separate.
- Invalid configurations fail before any network or database work.
Sources
Key takeaway: Configuration creates trustworthy experiments when every value is constrained, hashed, and unable to weaken safety invariants.