Olive Recipe Schema
Relevant source files
The following files were used as context for generating this wiki page:
The Olive Recipe Schema defines the structural and configuration requirements for Microsoft Olive model optimization workflows within Olive Studio. It acts as the contract between the user interface, where users build pipelines visually, and the Olive CLI engine, which executes the optimization passes. The schema ensures that JSON documents contain the necessary keys—such as input models, optimization passes, system configurations, and engine settings—required for a valid run.
Sources: src/lib/oliveRecipeSchema.ts:1-12, ABOUT.md:5-10
Core Schema Structure
A valid Olive recipe is an object composed of four primary high-level segments: input_model, passes, systems, and engine. Each segment must adhere to specific object types and internal property requirements to pass validation.
The diagram above illustrates the object hierarchy required for a structural valid recipe.
Sources: src/lib/oliveRecipeSchema.ts:31-77, src/lib/tests/oliveRecipeSchema.test.ts:7-30
1. Input Model
The input_model defines the source of the model to be optimized. It requires a type (e.g., PyTorchModel) and a config object which typically includes framework-specific details or Hugging Face configurations.
Sources: src/lib/oliveRecipeSchema.ts:36-44
2. Optimization Passes
The passes object contains a mapping of pass names to their respective configurations. Each pass must specify a valid Olive pass type (validated against a known pass catalog) and may optionally include a config object.
Sources: src/lib/oliveRecipeSchema.ts:50-68
3. Systems and Accelerators
The systems segment defines the execution environments. Each system configuration must include an accelerators array. Each accelerator object within that array must specify a device and a list of execution_providers.
Sources: src/lib/oliveRecipeSchema.ts:83-110
4. Engine Configuration
The engine object controls the execution logic. It must define a host and a target, both of which must reference valid keys existing within the systems object.
Sources: src/lib/oliveRecipeSchema.ts:70-79, src/lib/oliveRecipeSchema.ts:112-113
Validation Logic and Data Flow
Olive Studio implements structural validation through the validateOliveRecipeStructure function. This function performs deep object checking and returns a result indicating validity along with a list of descriptive error messages.
The flow represents how UI interactions are converted into a validated schema artifact.
Sources: src/lib/recipePipeline.ts:24-34, src/lib/oliveRecipeSchema.ts:31-33
Validation Requirements Table
| Path | Required Type | Constraint |
|---|---|---|
input_model.type | String | Must be non-empty |
input_model.config | Object | Must be present |
passes.[name].type | String | Must be a known Olive pass name |
systems.[key].config.accelerators | Array | Must be a non-empty array of objects |
engine.host | String | Must match a key in systems |
engine.target | String | Must match a key in systems |
Sources: src/lib/oliveRecipeSchema.ts:31-115, src/lib/tests/oliveRecipeSchema.test.ts:38-160
Pipeline Integration
The schema validation is a critical component of the RecipePipelineResult. Before a recipe is considered "runnable," it must satisfy both the structural schema requirements and separate pipeline compatibility rules (e.g., ensuring a pass is compatible with the selected hardware device).
Key Functions
validateOliveRecipeStructure(recipe): Performs a structural check of the JSON object.assertValidOliveRecipeStructure(recipe): Throws an error if the recipe does not meet schema requirements.parseRecipeJson(text): Converts a JSON string into a recipe object and immediately validates it against the schema.buildRecipeFromState(state): The "single source of truth" function that generates a recipe from UI state, serializes it, and validates the output.
Sources: src/lib/oliveRecipeSchema.ts:121-126, src/lib/recipePipeline.ts:24-36, src/lib/recipePipeline.ts:63-80
Implementation Example: Minimal Valid Recipe
A recipe must at least define a model source and a local system to be structurally valid.
{
"input_model": {
"type": "PyTorchModel",
"config": {}
},
"systems": {
"local_system": {
"type": "LocalSystem",
"config": {
"accelerators": [{ "device": "cpu", "execution_providers": ["CPUExecutionProvider"] }]
}
}
},
"passes": {},
"engine": {
"host": "local_system",
"target": "local_system"
}
}
Sources: src/lib/tests/oliveRecipeSchema.test.ts:7-30, src/lib/recipePipeline.ts:104-120
Conclusion
The Olive Recipe Schema is the foundational validation layer for Olive Studio. By enforcing strict object structures and cross-references between engine settings and system definitions, it prevents malformed configurations from being sent to the Microsoft Olive execution engine. This ensures that errors are caught early in the development lifecycle within the web interface rather than during the hardware-intensive optimization process.