# Data Product Recipe Specification (ODPR) ODPR is a lightweight, vendor-neutral, machine-readable standard for reusable data product delivery work. It has three primary composite flows: delivery flows, product handoff flows for one data product, and trigger-based flows driven by graph changes. Recipe, RuntimeProfile, and RecipeCatalog objects are supporting building blocks. Base URL: - https://opendataproducts.org/odpr-v1.0 Human-readable specification: - / (https://opendataproducts.org/odpr-v1.0/) - The "Recipe Toolkit" section lists the ODP Agent SDK, validation schemas, recipe examples, retrieval file, and source helper scripts. Family-level toolkit: - ODP Agent SDK: https://opendataproducts.org/sdk/ - The ODP Agent SDK supports ODPR and is the first reference implementation for validating and executing ODPR recipes. - ODPR recipes are reusable workflow units inside delivery and trigger-based flows. They may also be used with other conforming SDKs, CI/CD systems, MCP servers, or platform implementations. - Use ODPR-specific schemas, examples, recipes.jsonl, and helper scripts together with the ODP Agent SDK when the task focuses on recipe documents. - When explaining or running a recipe, inspect command names, step parameters, declared outputs, gates, review policy, environment, and runPolicy. - When explaining graph-triggered recipes, inspect `recipe.trigger` and `recipe.graphContext`. Treat triggers as graph change patterns, not graph queries or bindings to one graph node id. - Do not model SDK invocation mode, dry-run responses, run manifests, logs, provider readiness, planned writes, write-scope checks, or run ids as ODPR root objects. - Do not put concrete LLM model settings, endpoints, credentials, or temperature values in ODPR recipes. Resolve those through ODPR RuntimeProfile objects and the executing SDK, CI/CD system, MCP server, agent runtime, or platform. Standards-family context: - ODPS is the Open Data Product Specification. Use ODPS when describing one data product and its detailed product metadata. Homepage: https://opendataproducts.org/ - ODPC is the Open Data Product Catalog specification. Use ODPC when describing catalogs, portfolios, product references, use cases, objectives, and signals. - ODPG is the Open Data Product Graph specification. Use ODPG when describing graph structures and relationships between data product artifacts. - ODPV is the Open Data Product Vocabulary. Use ODPV when stable shared term ids, labels, definitions, relationship names, and vocabulary guidance are needed. Documentation: https://opendataproducts.org/odpv-v1.0/ - ODPR does not replace ODPS, ODPC, ODPG, or ODPV. It defines repeatable workflow recipes around those artifacts. Canonical schema files: - /schema/odpr.yaml (https://opendataproducts.org/odpr-v1.0/schema/odpr.yaml) - /schema/odpr.json (https://opendataproducts.org/odpr-v1.0/schema/odpr.json) Agent-friendly retrieval file: - /recipes/recipes.jsonl (https://opendataproducts.org/odpr-v1.0/recipes/recipes.jsonl) Recipe catalog file: - /recipes/catalog.yaml (https://opendataproducts.org/odpr-v1.0/recipes/catalog.yaml) Recipe example files: - /recipes/examples/minimal.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/minimal.yaml) - /recipes/examples/ci-validate-generated-fragments.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/ci-validate-generated-fragments.yaml) - /recipes/examples/release-portfolio-review.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/release-portfolio-review.yaml) - /recipes/examples/portfolio-localization.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/portfolio-localization.yaml) - /recipes/examples/hybrid-graph-review.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/hybrid-graph-review.yaml) - /recipes/examples/data-product-delivery.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/data-product-delivery.yaml) - /recipes/examples/graph-triggered-impact-review.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/graph-triggered-impact-review.yaml) - /recipes/examples/data-product-recipe.yaml (https://opendataproducts.org/odpr-v1.0/recipes/examples/data-product-recipe.yaml) RuntimeProfile example files: - /runtime-profiles/examples/production-quality.yaml (https://opendataproducts.org/odpr-v1.0/runtime-profiles/examples/production-quality.yaml) - /runtime-profiles/examples/local-fast.yaml (https://opendataproducts.org/odpr-v1.0/runtime-profiles/examples/local-fast.yaml) - /runtime-profiles/examples/local-graph.yaml (https://opendataproducts.org/odpr-v1.0/runtime-profiles/examples/local-graph.yaml) - /runtime-profiles/examples/internal-secure.yaml (https://opendataproducts.org/odpr-v1.0/runtime-profiles/examples/internal-secure.yaml) Agent-oriented source scripts: - scripts/build_recipe_catalog.py regenerates source/recipes/catalog.yaml from canonical recipe examples. Use `python scripts/build_recipe_catalog.py --check` to detect catalog drift. - scripts/check_agent_artifacts.py checks schema alignment, example files, recipe JSONL records, and llms.txt references. - scripts/generate_recipe_artifacts.py regenerates derived recipe artifacts such as source/schema/odpr.json from canonical source/schema/odpr.yaml. Use `python scripts/generate_recipe_artifacts.py --check` to detect drift. - scripts/search_recipes.py searches /recipes/recipes.jsonl by keyword or exact recipe id. Use `--json` for machine-readable results. - scripts/validate_recipe.py validates ODPR YAML or JSON Recipe, RuntimeProfile, or RecipeCatalog files against /schema/odpr.yaml and rejects embedded secrets or API keys. Install dependencies with `python -m pip install -r scripts/requirements-agent.txt`. Source repository: - https://github.com/Open-Data-Product-Initiative/odpr-v1.0 Knowledge base: - https://opendataproducts.org/howto/ Core ODPR concepts: - Delivery flow: repeatable delivery work such as portfolio building, validation, localization, publishing, and release review. - Recipe: supporting workflow unit used by delivery flows and trigger-based flows; represented with `kind: Recipe`. - DataProductRecipe: root Data Product Recipe handoff document for developers and AI agents planning and implementing one data product. - Trigger-based flow: recipe applicability driven by an ODPG graph change. - GraphTrigger: optional Recipe trigger contract that declares which ODPG graph change pattern can make a recipe applicable. - GraphContext: optional Recipe graph context contract that declares the ODPG graph reference, trigger-derived start point, and context depth needed by a graph-triggered recipe. - RuntimeProfile: supporting runtime generation configuration document that declares SDK-compatible provider profiles, model defaults, generation paths, portfolio intake policy, and API-key environment variable names. - RecipeCatalog: supporting metadata-only discovery document that lists available recipes and points to complete Recipe files. - Step: one operation in a recipe, such as generate, validate, portfolio.build, portfolio.localize, portfolio.explain, or odpg.build. - Execution: runtime policy for local, hosted, hybrid, or model-free execution. - Context: preferred context format policy such as yaml, toon, gcf, or auto. - Gate: validation, review, or quality check that must pass before a workflow is accepted. - Review: human or agent review expectations for the recipe output. Recommended agent workflow: 1. Fetch /llms.txt first to understand the standards-family context and ODPR resources. 2. Use the ODP Agent SDK for implementation work that validates or executes recipes. 3. Load /recipes/recipes.jsonl for recipe selection and lightweight lookup. 4. Load /recipes/catalog.yaml when metadata-only discovery of complete Recipe files is needed. 5. Load /recipes/examples/*.yaml when generating ODPR content. 6. Load /schema/odpr.yaml or /schema/odpr.json to validate ODPR Recipe, RuntimeProfile, RecipeCatalog, and DataProductRecipe files. 7. Use runtime references in recipes as references only; load matching RuntimeProfile objects and resolve URI fragments against `runtimeProfile.providers`. 8. Inspect declared outputs, gates, review policy, environment, and runPolicy before running recipe steps. 9. Use DataProductRecipe documents for Markdown-heavy data product handoff work. Optional recipe references are provenance, not implementation dependencies. 10. Keep recipes declarative. Do not turn ODPR into a shell scripting language or RuntimeProfile objects into raw secret stores. Modeling constraints: - ODPR defines three primary composite flows: delivery flows, product handoff flows, and trigger-based flows. Recipe, RuntimeProfile, and RecipeCatalog documents are supporting building blocks. ODPR does not define data products, ODPC catalog object models, graphs, vocabularies, SDK internals, CI/CD engines, or provider-specific APIs. - Recipe documents use `kind: Recipe`. RuntimeProfile documents use `kind: RuntimeProfile`. Recipe catalog documents use `kind: RecipeCatalog`. Data Product Recipe documents use `kind: DataProductRecipe`. - Do not use `ProductRecipe`. The ODPR root kind is `DataProductRecipe`. - ODPR v1 root kinds do not include `RecipeRunPlan`, `RecipeRunManifest`, or `RecipeInspection`. - Recipe metadata requires stable id and name fields. Description is recommended for human readability. Recipe objects also require `recipe.version`, which is separate from the top-level ODPR specification version. - RuntimeProfile documents use the SDK-compatible generation config shape: `runtimeProfile.provider` selects the default profile and `runtimeProfile.providers` contains the named provider profile map. - Recipe steps should describe SDK or platform operations, not arbitrary shell scripts. - Execution mode should be one of local, hosted, hybrid, or none. It is not SDK invocation mode such as validate, dry-run, execute, or resume. - Context format should be one of yaml, toon, gcf, or auto. - Graph-triggered recipes use `recipe.trigger.source: odpg` and a closed `recipe.trigger.event` value such as `node.added`, `node.removed`, `node.attributeChanged`, `edge.added`, `edge.removed`, `edge.attributeChanged`, or `graph.conditionMatched`. - Graph trigger subjects match graph change patterns. `subject.nodeType` may be a controlled node type or `*`; `subject.attribute.name` must be explicit and must not be `*`. - ODPG may reference ODPR recipes for graph-local discovery, but ODPR remains the source of truth for trigger semantics, steps, runtime references, gates, and review policy. - Provider profiles inside RuntimeProfile documents should use `apiKeyEnv` environment variable names instead of raw credentials. - Validation should reject embedded secrets or API keys in Recipe, RuntimeProfile, and RecipeCatalog documents. - Use extension fields beginning with `x-` for local implementation details.