Versioning the UI

Overview

Because OUAS acts as a strict API between your UI and the AI Agent, changing a component's props is equivalent to introducing a breaking API change.

If you rename a required prop in your React component (e.g., from title to header), the AI model will continue to hallucinate the old title prop until it is fine-tuned or re-prompted with the new Component Manifest.

The ouas_version Flag

The root of every manifest.json requires an ouas_version flag.

{
  "ouas_version": "1.0.0",
  "app_id": "mailflow-dashboard",
  "components": [ ... ]
}

Whenever you make a breaking change to any component's schema:

1. Increment the ouas_version (e.g., to 1.1.0 or 2.0.0 following Semantic Versioning).
2. Deploy the new manifest alongside your updated UI.
3. The AI Agent router should inspect this version and route the request to the appropriate model or system prompt that understands the new schema.

Backward Compatibility Strategies

If you cannot immediately update the AI Agent, you should maintain backward compatibility in your React components.

Instead of deleting the old prop, keep it in the component but mark it as deprecated in the schema, and map it internally to the new UI structure:

export const WeatherCard = withOUAS(WeatherCardBase, {
  id: 'weather-card',
  schema: {
    // New prop
    header: { type: 'string' },
    // Deprecated but maintained for older AI models
    title: { type: 'string', description: '@deprecated Use header instead' }
  }
});

By maintaining the deprecated prop in the schema, older AI models will continue to function seamlessly until they are updated to use the new header prop.