OPEN DATA PRODUCT RECIPE SPECIFICATION - The Linux Foundation

Version DRAFT

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in all capitals, as shown here.

The specification is shared under Apache 2.0 license. Development of the specification is under the umbrella of the Linux Foundation.

Introduction

The Data Product Recipe Specification, ODPR, is a lightweight, vendor-neutral, machine-readable recipe model for repeatable data product delivery workflows.

ODPR is part of the OpenDataProducts.org standards family. It complements the Open Data Product Specification, ODPS, Open Data Product Catalogs, ODPC, Open Data Product Graphs, ODPG, and Open Data Product Vocabulary, ODPV, by defining how workflows around those artifacts can be declared and automated.

ODPR standardizes how data product work gets done, not only what the final artifact looks like.

Why ODPR is needed

Data product work often depends on manual command sequences, scripts, notebooks, prompts, and local habits. That creates delivery variation, makes validation and review steps easy to skip, hides model-provider choices, and forces CI/CD automation and AI agents to guess the intended workflow.

ODPR solves this by turning repeatable data product work into declared recipes. A recipe describes:

• what workflow runs
• which inputs it uses
• which outputs it creates
• which steps run
• which checks or gates apply
• which context format is preferred
• which execution mode is expected
• which provider reference or provider class is used
• whether human review is required

Core design principle

A recipe is not a script.

A recipe is a portable, declarative workflow contract. Scripts tell one tool what to do. Recipes tell teams, tools, agents, and automation systems how a data product workflow should run.

Recipe and provider configuration

ODPR standardizes two clear root objects: Recipe and Provider.

A Recipe declares workflow intent: which steps run, which inputs and outputs matter, which gates apply, and which provider profile should be used.

A Provider declares a named runtime profile: provider family, model, provider class, endpoint reference, credentials reference, and safe default settings such as temperature. This prevents each SDK, CI system, MCP server, or agent runtime from inventing a different provider shape.

In an ODPR recipe, a provider is referenced by name:

execution:
  mode: hosted
  providerRef: production-quality

The provider profile itself is configured outside the recipe, as a separate ODPR Provider object:

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Provider
provider:
  id: production-quality
  provider: openai
  model: gpt-4.1
  providerClass: hosted
  temperature: 0.2

This two-part model keeps recipes portable and safe to share. The same recipe can use providerRef: production-quality in development, CI, staging, or production while each environment resolves that reference to the right local model, hosted model, internal gateway, credentials, and operational settings. ODPR standardizes both the workflow contract and the provider profile shape; the executing implementation owns runtime resolution, credentials, and provider connectivity.

Relationship to the standards family

The OpenDataProducts.org standards family follows a separation of concerns:

• ODPS defines the product.
• ODPC defines catalogs and reusable portfolio objects.
• ODPG defines relationships and graphs.
• ODPV defines shared vocabulary and terms.
• ODPR defines repeatable workflows for data product delivery.

ODPR does not define the product, catalog, graph, or vocabulary model. It defines the workflow contract around those artifacts.

Example recipe

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Recipe
recipe:
  metadata:
    id: RCP-CI-001
    name:
      en: CI Validate Generated Fragments
    description:
      en: Generate and validate draft fragments during CI.
  version: "1.0.0"
  type: ci
  environment: ci
  execution:
    mode: local
    providerRef: local-fast
  context:
    format: gcf
    fallback:
      - toon
      - yaml
  steps:
    - id: generate-signals
      command: generate
      with:
        kind: signal
        input: source_docs/signals/
        output: generated/fragments/
    - id: validate-fragments
      command: validate
      with:
        input: generated/fragments/
  outputs:
    - id: generated-fragments
      path: generated/fragments/
  gates:
    - id: fragments-valid
      type: validation
      required: true
  review:
    required: false

This recipe declares what a CI runner or SDK executor should do when source documents for signals change. The expected run is:

1. The executor loads the recipe and validates it against https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml.
2. It reads recipe.version: "1.0.0" as the version of this workflow contract.
3. It sees type: ci and treats the recipe as an automated CI workflow, not as an interactive authoring or release-review workflow.
4. It reads environment: ci and labels the run as a CI workflow context.
5. It prepares a local execution run using the configured provider named local-fast. ODPR only stores the providerRef; credentials, model settings, command bindings, and runtime configuration stay in the executing SDK, CI system, MCP server, or platform.
6. It prepares recipe context in GCF format. If GCF is not available, the executor can fall back first to TOON and then to YAML.
7. It runs the generate-signals step by invoking the executor's generate operation with kind: signal, reading inputs from source_docs/signals/, and writing generated fragments to generated/fragments/.
8. It runs the validate-fragments step by invoking the executor's validate operation against generated/fragments/.
9. It exposes generated-fragments as the durable output path that CI jobs or agents can inspect after the run.
10. It evaluates the fragments-valid validation gate. Because the gate is required, failed validation means the CI workflow fails.
11. It does not pause for manual review after the gate passes, because review.required is false.

Specification aims

ODPR aims to:

• make data product workflows portable, repeatable, inspectable, and automation-ready
• support standard development, CI, release, localization, hybrid, and agent-safe workflows
• let teams switch between local, hosted, and hybrid model execution
• standardize provider profile shape without storing raw secrets or defining provider-specific APIs
• support compact context policy such as YAML, TOON, GCF, or automatic fallback
• expose safe workflows to AI agents before they run tools

Note! In "Open Data Product" the focus is on the latter words and the prefix "open" refers to the openness of the standard. Any connotations to open data are not intentional, intended, or desirable.

Recipe Toolkit

Snippet of YAML version:

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Recipe
recipe:
  metadata:
    id: RCP-DEV-001
    name:
      en: Local Fragment Draft
    description:
      en: Generate draft ODPC fragments locally for fast iteration.
  type: dev
  execution:
    mode: local
    providerRef: local-fast
  steps:
    - id: generate-signals
      command: generate
      with:
        kind: signal
        input: source_docs/signals/
        output: generated/fragments/

ODPR is published in several forms for different users and tools. This specification provides the human-readable documentation, while the schema, recipe records, provider records, and example files provide machine-readable resources for validation, workflow automation, AI retrieval, and agent use.

Use odpr.yaml or odpr.json to validate Recipe and Provider files, recipes.jsonl for lightweight object selection and retrieval, and the examples when generating or repairing ODPR YAML.

The ODP Agent SDK supports ODPR and is the first reference implementation for validating and executing ODPR recipes. Use it when building agents or automation across ODPS, ODPC, ODPG, and ODPV workflows. ODPR recipes remain portable workflow contracts and can also be used with other conforming SDKs, CI/CD systems, MCP servers, or platform implementations.

Agent-oriented helper scripts are available in the source repository for maintaining and using recipe artifacts.

The Markdown tables in this specification are intended for human readers. The schema, JSONL, and YAML example files are intended for programmable use, automation, validation, AI retrieval, and recipe tooling.

Recipe Library

ODPR publishes a small library of canonical recipes under /recipes/examples/. These examples are not decorative snippets. They are complete recipe files that can be copied, validated, adapted, and used by SDKs, CI/CD systems, MCP servers, or other ODPR-aware platforms.

Agents and tools can also use /recipes/recipes.jsonl as a lightweight lookup file for selecting the right recipe pattern before loading the full YAML example.

The library is intentionally small. Each example should demonstrate a distinct workflow pattern rather than every possible command option. Local organizations can extend these recipes with x- fields or implementation-specific command bindings without changing ODPR semantics.

ODPR also publishes Provider examples under /providers/examples/. Use these when a recipe references a provider profile such as local-fast, local-graph, production-quality, or internal-secure.

AI Agent Usage Patterns

ODPR is designed to be usable by AI agents, SDKs, CI/CD systems, and automation tools. From an agent perspective, ODPR provides an inspectable workflow contract before an action is run: it names the workflow, lists the steps, declares the execution mode, points to context policy, and describes gates or review expectations.

ODPS defines one data product. ODPC defines catalogs and reusable portfolio objects. ODPG defines relationships between data product artifacts. ODPV provides shared vocabulary terms. ODPR defines repeatable workflows around those artifacts.

Agent capabilities enabled by ODPR

Agents can use ODPR to:

• discover safe workflow recipes before running SDK tools
• explain what a recipe will do before execution
• validate recipe files against odpr.yaml or odpr.json
• select a development, CI, release, localization, hybrid, or agent recipe
• inspect whether a workflow expects local, hosted, hybrid, or no model execution
• follow declared gates and review requirements
• reuse a recipe in CI/CD or production automation
• preserve stable workflow intent while model providers vary by environment

Common agent workflows

Agent behavior constraints

Agents using ODPR should keep boundaries clear:

• Do not treat ODPR as a data product definition; use ODPS for product metadata.
• Do not treat ODPR as a catalog object model; use ODPC for catalogs and portfolio objects.
• Do not treat ODPR as a graph model; use ODPG for nodes, edges, and relationships.
• Do not embed secrets or API keys in recipes.
• Do not assume providerRef is globally meaningful; it must be resolved by the executing SDK, CI system, or platform.
• Do not silently skip required gates or human review requirements.

Example prompts ODPR enables

• "Validate this ODPR recipe and suggest schema-compliant repairs."
• "Create a CI recipe that generates signal fragments and validates them."
• "Create a release recipe that refreshes, localizes, and explains a portfolio."
• "Explain which steps this recipe will run and whether human review is required."
• "Convert this local development workflow into a hosted production recipe."

ODPR Recipe

The Recipe object is the root ODPR object. It declares one repeatable workflow for data product delivery, validation, review, localization, publishing, or automation.

Recipes are intended to be readable by humans and executable by tools. A recipe should be specific enough for an SDK, CI/CD system, MCP server, or agent to understand the workflow before it runs, while staying portable enough to avoid binding the standard to one implementation.

Root structure

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Recipe
recipe:
  metadata:
    id: RCP-DEV-001
    name:
      en: Local Fragment Draft
    description:
      en: Generate draft fragments locally.
  version: "1.0.0"
  type: dev
  steps: []

Recipe fields

recipe:
  metadata:
    id: RCP-CI-001
    name:
      en: CI Validate Generated Fragments
    description:
      en: Generate and validate fragments.
  version: "1.0.0"
  type: ci
  environment: ci
  execution:
    mode: local
    providerRef: local-fast
  context:
    format: gcf
    fallback:
      - toon
      - yaml
  steps:
    - id: validate-fragments
      command: validate
      with:
        input: generated/fragments/
  outputs:
    - id: generated-fragments
      path: generated/fragments/
  gates:
    - id: fragments-valid
      type: validation
      required: true
  review:
    required: false
  runPolicy:
    timeoutSeconds: 300

Recipe types

Execution modes

Context formats

Provider references

providerRef identifies a standardized ODPR Provider profile by provider.id. The recipe does not embed provider internals; it only names the profile that should be used.

A recipe can declare a default provider in execution.providerRef. Individual steps can override it with step.providerRef when one workflow mixes local and hosted execution.

The referenced Provider object defines the provider family, model, provider class, endpoint reference, credentials reference, and safe runtime defaults. Raw secrets MUST NOT be stored in recipes or provider documents.

ODPR validation tools SHOULD reject embedded secrets or API keys in recipes. Use providerRef in recipes and credentialsRef in Provider documents instead of fields such as apiKey, token, password, or inline secret values.

Recommended commands

ODPR keeps commands lightweight so recipes stay portable across implementations. Implementations SHOULD support the recommended command names where the underlying capability exists. Implementations MAY support additional commands.

with is the argument object for the selected command. ODPR standardizes where command arguments live, but v1.0 does not define the complete argument schema for every command.

Outputs

Use outputs when a workflow creates durable artifacts that later steps, CI jobs, reviewers, or agents should inspect. Outputs are named paths. They do not replace the command-specific with.output argument; they make expected durable results visible at the recipe level.

Gates, review, and runtime policy

Required gates SHOULD be evaluated or reported by the executing tool. Tools SHOULD NOT silently skip required gates.

review.required declares whether a recipe expects review after automated steps complete. review.mode can be human, agent, both, or none.

runPolicy gives lightweight runtime guidance such as timeout and retry expectations. It is useful for CI jobs, local model calls, portfolio localization, and hosted provider calls.

Environment labels

Use environment to label the intended operating context, such as development, ci, staging, or production. The value is a string so teams can use local naming conventions while keeping common labels readable.

Example

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Recipe
recipe:
  metadata:
    id: RCP-RELEASE-001
    name:
      en: Release Portfolio Review
    description:
      en: Refresh, localize, and explain a portfolio for release review.
  version: "1.0.0"
  type: release
  execution:
    mode: hosted
    providerRef: production-quality
  environment: production
  context:
    format: gcf
    fallback:
      - toon
      - yaml
  runPolicy:
    timeoutSeconds: 900
  steps:
    - id: refresh-portfolio
      command: portfolio.refresh
      with:
        workspace: portfolio/
    - id: localize-portfolio
      command: portfolio.localize
      with:
        workspace: portfolio/
        languages:
          - fi
          - sv
    - id: explain-portfolio
      command: portfolio.explain
      with:
        workspace: portfolio/
  outputs:
    - id: localized-portfolio-fi
      path: portfolio/index.fi.html
    - id: localized-portfolio-sv
      path: portfolio/index.sv.html
    - id: release-explanation
      path: portfolio/explanation.md
  gates:
    - id: human-review
      type: review
      required: true
  review:
    required: true
    mode: human
    instructions: Review localized pages and generated reports before publishing.

This release recipe describes a portfolio review workflow. When an executor runs it, the expected flow is:

1. Validate the recipe against the ODPR schema and confirm it is a Recipe.
2. Treat the workflow as a release recipe, which means it is intended for a publication or release-review process rather than local drafting.
3. Use hosted execution through the configured provider reference production-quality. The matching ODPR Provider object describes the runtime profile, while raw credentials and live endpoint resolution stay in the executing SDK or platform.
4. Prepare compact context in GCF format, with TOON and YAML as fallback formats.
5. Run portfolio.refresh for the portfolio/ workspace.
6. Run portfolio.localize for the same workspace and produce Finnish and Swedish localized outputs.
7. Run portfolio.explain so reviewers get generated explanation material for the refreshed portfolio.
8. Require human review before the release workflow is considered complete.

ODPR Provider

The Provider object is the second ODPR root object. It defines a named runtime provider profile that recipes can reference with providerRef.

Providers standardize the shape of LLM and execution-provider configuration without putting provider details inside workflow recipes. A recipe stays focused on what should happen. A provider profile declares how a named runtime profile resolves to a provider family, model, endpoint reference, credentials reference, and model settings.

Provider profiles MUST NOT contain raw secrets. Use credentialsRef or implementation-specific secret references instead. ODPR validation tools SHOULD reject embedded secrets or API keys, including fields such as apiKey, token, password, or raw secret-looking values.

Root structure

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Provider
provider:
  id: production-quality
  provider: openai
  model: gpt-4.1
  providerClass: hosted
  temperature: 0.2

Provider fields

provider:
  id: production-quality
  provider: openai
  model: gpt-4.1
  providerClass: hosted
  endpointRef: platform:openai
  credentialsRef: env:OPENAI_API_KEY
  temperature: 0.2
  settings:
    maxOutputTokens: 4000

Provider references

A recipe uses providerRef to select a Provider profile by provider.id:

execution:
  mode: hosted
  providerRef: production-quality

The Provider object with id: production-quality defines the runtime profile:

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Provider
provider:
  id: production-quality
  provider: openai
  model: gpt-4.1
  providerClass: hosted
  temperature: 0.2
  credentialsRef: env:OPENAI_API_KEY

This keeps the recipe portable while avoiding a provider wild west. Recipes standardize workflow intent. Providers standardize named runtime profiles. Executing SDKs, CI/CD systems, MCP servers, agent runtimes, and platforms then resolve endpointRef, credentialsRef, and any implementation-specific settings during execution.

Example profiles

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Provider
provider:
  id: local-fast
  provider: ollama
  model: gemma
  providerClass: local
  temperature: 0.1
  environment: development

These examples show how Provider profiles turn recipe-level providerRef names into standardized runtime profiles.

local-fast is intended for development and fast CI-style checks. A recipe that uses providerRef: local-fast asks the executor to use a local provider profile backed by Ollama and the gemma model. The low temperature keeps local drafting runs predictable while avoiding any hosted model dependency.

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Provider
provider:
  id: internal-secure
  provider: gateway
  model: approved-llm
  providerClass: hosted
  endpointRef: platform:internal-gateway
  credentialsRef: vault:odp-agent-runtime
  temperature: 0.0
  environment: production

internal-secure is intended for controlled production or enterprise environments. A recipe that uses providerRef: internal-secure asks the executor to route model calls through an approved internal gateway. The profile names the gateway endpoint and credential reference, but it does not embed the actual credential or API key.

Specification extensions

While ODPR defines the core recipe object and attributes, organizations may need to add implementation-specific metadata for local tools, CI/CD systems, governance workflows, or platform-specific requirements.

Extension properties are patterned fields prefixed with x-. These fields may appear inside recipe objects where the schema allows extension properties.

Extensions are not part of the official ODPR object model unless they are later adopted into the specification. Tooling may ignore extension fields unless explicit support has been added.

Extensions should not redefine core ODPR semantics. They should be used only for additional metadata that does not fit standard attributes.

Useful and widely adopted extensions may become candidates for future versions of the standard. To propose useful extensions, raise an issue in GitHub:

Open Data Product Initiative GitHub issues

Example of extension usage:

schema: https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml
version: "1.0"
kind: Recipe
recipe:
  metadata:
    id: RCP-CI-001
    name:
      en: CI Validate Generated Fragments
    description:
      en: Generate and validate fragments during CI.
    x-internal-owner-group: data-product-platform
  type: ci
  steps:
    - id: validate-fragments
      command: validate
      with:
        input: generated/fragments/
      x-ci-job-name: validate-generated-fragments

Editors and contributors

This specification is openly developed and a lot of the work comes from community. We list all community contributors as a sign of appreciation. Maintainers process the feedback and draft new candidate releases, which may become the versions of the specification.

Maintainers:

• Jarkko Moilanen

Terms used

ODPR uses the Open Data Product Vocabulary, ODPV, as the shared vocabulary for the OpenDataProducts.org standards family. Use ODPV for common terms, stable ids, labels, definitions, aliases, and relationship names across ODPS, ODPC, ODPG, ODPR, and related tools.

The terms below explain ODPR-specific usage where this specification gives a shared vocabulary term a concrete recipe meaning or modeling constraint.

Shared terms from ODPV

ODPR-specific usage notes

ODPR should stay focused on workflow contracts. Product metadata belongs to ODPS. Catalog and portfolio objects belong to ODPC. Graph structures and relationships belong to ODPG. Shared vocabulary belongs to ODPV.