Recipe Time Fields Should Be Queryable

Time is product logic, not display copy

Meal planning apps often treat recipe time as a label: "30 minutes," "weeknight," or "slow cooker." That is fine for a card, but it is not enough for scheduling, filtering, grocery prep, or AI-generated plans. If users ask for dinners that fit between work and school pickup, the app needs queryable time fields, not a paragraph of instructions.

A builder-friendly recipe API should separate at least three concepts: preparation time, cooking time, and total time. Schema.org's Recipe type models those as prepTime, cookTime, and totalTime, each as a duration. Google's recipe structured data examples use the same split with ISO-style values such as PT1M, PT2M, and PT3M.

Store durations as data, then format them later

The database should not store only "about 45 minutes". Keep that copy if it improves the page, but also store a normalized duration in minutes or seconds. When the source provides an ISO 8601 duration, keep the original value and parse it into numeric fields your product can query.

A practical internal shape can look like this:

{
  "prepMinutes": 15,
  "cookMinutes": 25,
  "totalMinutes": 40,
  "activeMinutes": 20,
  "timeText": "About 40 minutes"
}

activeMinutes is not always present in public recipe markup, but it matters for product behavior. A recipe that simmers for two hours may be easy on a worknight if only 15 minutes are active. A recipe with 35 minutes of chopping may feel harder than its total time suggests.

Make meal planning queries explicit

Once time is structured, the app can answer useful questions without brittle text search:

• show dinners under 35 total minutes
• avoid recipes with more than 20 active minutes on weekdays
• pair one oven recipe with one no-cook side
• sort by prep burden rather than total duration
• explain why a recipe was selected for a plan

That last point is important for AI meal planning. If a model recommends a recipe, the product should be able to say, "This fits because it takes 30 minutes total and only 10 minutes of active prep." The explanation should come from stored facts, not from asking the model to infer time from prose.

Validate time fields before they reach search

Recipe time data is messy. Some sources omit prep time. Some put resting time into total time. Some write "overnight" or "hands-off" instead of a duration. Rather than forcing every recipe into fake precision, keep validation states alongside the normalized values.

Useful flags include:

• timeConfidence: whether the duration came from structured data, parser inference, or manual entry
• includesRestTime: whether chilling, marinating, or proofing is counted in total time
• hasActiveTime: whether active effort was measured separately
• timeWarnings: parser notes such as "overnight found in instructions"

The W3C XML Schema duration datatype is a useful reminder that durations have a formal lexical shape, but product code still needs domain rules. PT30M is syntactically clear; deciding whether a two-hour marinade belongs in a weeknight filter is a product decision.

What to expose in an API response

For recipe and meal planning APIs, expose both machine fields and user-facing copy. That lets clients build filters without re-parsing strings, while still displaying natural text.

A clean response includes:

{
  "times": {
    "prepMinutes": 15,
    "cookMinutes": 25,
    "totalMinutes": 40,
    "activeMinutes": 20,
    "display": "40 minutes total, 20 minutes active"
  }
}

If a field is unknown, return null rather than 0. Zero means no time; null means the API does not know. That distinction prevents meal planners from accidentally promoting incomplete records as fast recipes.

Builder takeaway

Do not wait until search or AI planning to fix recipe time. Normalize it during ingestion, preserve the original text, expose clear duration fields, and track confidence. The result is better filtering, better scheduling, and recipe recommendations users can actually trust.