# Farm Fuel Calculator scenario authoring

Calculator: https://agrowknow.com/farm-fuel/
Schema: https://agrowknow.com/farm-fuel/integrations/scenario-v1.schema.json
Examples: https://agrowknow.com/farm-fuel/integrations/examples/conventional.json and no-till.json
Catalog: https://agrowknow.com/farm-fuel/integrations/catalog.json

New saves use version 2: scenario-v2.schema.json and examples/operation-months.json. Version 1 remains supported for the original current-price examples. Both are complete state documents with app, version, savedAt, and state. It is not a patch. Copy an example and retain both crops and all three named programs per crop. Use only operation keys from catalog.json; a custom activity uses key custom and its own name and measured or explicitly labelled estimated rate. Do not invent unknown farm inputs.

Use numeric values, never numeric strings. All quantities allow null for unknown; zero is a real zero. Acres, prices, yield and other unrestricted quantities range from 0 to 1e9. Percentages range from 0 to 100. Each program has at most 250 operations; activity names have at most 90 characters. Imported files must be below 1,000,000 bytes/characters. The calculator checks usable truck capacity, MPG, enabled irrigation and drying moisture relationships when calculating; structural validation alone does not guarantee a complete estimate.

Units: acres; bushels per crop acre; USD per US gallon; operation diesel gallons per acre per pass; passes as a count; coverage/share as percent 0-100; hauling distance as ONE-WAY miles, capacity as bushels per load, mpg as round-trip miles per gallon, idleMinutes per load, idleRate as gallons/hour; irrigation gallons as seasonal gallons per irrigated acre; drying initial/target as moisture percent and rate as propane gallons per wet bushel per moisture percentage point.

Fuel IDs: offroad (USDA Illinois farm diesel FOB distributor asking price), road (EIA Midwest on-highway retail diesel including taxes), propane (USDA Iowa FOB distributor asking price). Replace benchmarks with the user's delivered/contract quote when provided. Gasoline is a historical comparison series and is not an allowed scenario fuel.

Historical overrides: null means resolve from the loaded observation snapshot; a numeric value is frozen; empty string means frozen unavailable. Exported examples freeze historical prices, including unavailable values. Keep that behavior unless the user expressly wants a changing reference. Baseline year is 2019-9999; month is 1-12. Comparisons keep the entire farm program fixed and change only prices.

The schema is the canonical authoring format and rejects extra fields. The existing importer also tolerates and strips unknown fields and does not require savedAt; this broader compatibility does not change the published canonical format. Row IDs are omitted; the importer assigns fresh IDs. savedAt is an ISO 8601 timestamp and does not change model behavior.

Examples use the calculator's 1,000 corn/1,000 soybean acre starting farm, editable default operations/yields, hauling and corn drying settings. They are illustrative planning scenarios, not observed farm data or recommendations. Prices and savedAt come from the dated verified build snapshot. Review all assumptions with the user. Version 2 adds pricing (mode current or operations, season year, overrides and frozen prices). Every operation and hauling/irrigation/drying group requires schedule: an array of {month:1-12 or null, yearOffset:0 or -1, share:0-100 or null}. Shares allocate existing fuel use and must total 100 percent for a valid seasonal calculation. Keys in pricing.overrides and pricing.frozen use YYYY-MM:fuel, for example 2025-11:offroad. Overrides are numeric USD/gallon or an empty string for unavailable; frozen entries contain price (number or null), status, dates and sources. Preserve frozen values unless the user requests a refresh. A newly introduced month resolves from the loaded snapshot. Unknown past-month prices stay missing. Only future-month current-season prices may use the current quote, explicitly labelled estimated. Current-month benchmarks are month to date. Compare the same schedule and fuel quantities in both years. Version 1 files open with approved schedules and current-price mode. Do not change the version number of a file without migrating its structure. No estimate covers machinery ownership, repairs, labor, fertilizer materials, electricity, crop returns or yield effects of tillage.

Validate against the schema, then use Open scenario in the browser. There is currently no hosted calculation API or MCP server and no farm-input upload. Schema/data URLs are public static resources, not automatic registration with AI providers.