feat:Update OpenAPI spec with generalized schemas and expanded streaming events #207
Conversation
WalkthroughThe OpenAPI specification for the Cohere API was updated to generalize schema names, unify message and content types, and introduce new schemas for content and tool messages. Example code snippets were revised to use the updated types, and streaming response schemas were expanded to cover detailed event types. Endpoint summaries now include versioning. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
participant MessageHandler
participant ContentHandler
participant ToolHandler
Client->>API: Send chat request (V1/V2)
API->>MessageHandler: Parse UserMessage/SystemMessage/ToolMessage
MessageHandler->>ContentHandler: Handle TextContent/ImageContent
MessageHandler->>ToolHandler: Process ToolSource/ToolMessage
API-->>Client: Return response (with new schema types and streaming events)
Poem
✨ Finishing Touches🧪 Generate Unit Tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (79)
src/libs/Cohere/Generated/Cohere..JsonSerializerContext.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Chatv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Embed.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Embedv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Rerank.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Rerankv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chatv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Embed.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Embedv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Rerank.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Rerankv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ChatMessageV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Content2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentDiscriminatorTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentItem.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentVariant2Item.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentVariant2Item2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Message.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Source.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageContentVariant2ItemDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageContentVariant2ItemDiscriminatorTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageRoleNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.TextContentType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.TextContentTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ToolContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.UserMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.UserMessageRoleNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonSerializerContextTypes.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatDocumentSourceDocument.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatMessageV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatTextResponseFormatV2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatToolSourceToolOutput.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Content2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Content2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminator.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentItem.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentVariant2Item.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentVariant2Item2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSource.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSource.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSourceDocument.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSourceDocument.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.EmbedByTypeResponse.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Message.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.MessageContentDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Source.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminator.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContent.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContentType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormat.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormatV2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSource.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSource.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSourceToolOutput.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSourceToolOutput.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessageRole.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Cohere/openapi.yaml(25 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test / Build, test and publish
🔇 Additional comments (26)
src/libs/Cohere/openapi.yaml (26)
20-23: Versioned endpoint summaries updated correctly
Including “V1” in the summaries for/v1/chatprovides clear versioning information. The description remains accurate and complementary.
2148-2151: Consistent versioning in summary for/v1/embed
The “Embed V1 API” summary and description are aligned and informative.
6856-6859: Rerank V1 API summary is clear and precise
The summary “Rerank V1 API” accurately reflects the endpoint’s purpose and version.
7382-7385: Updated/v2/chatsummary for versioning
The “Chat V2 API” summary and streaming description are properly versioned.
7558-7561: Go example updated to use v2 client and general message types
The snippet correctly initializes the v2 client and employsUserMessage/AssistantMessagebuilders instead of older V2-specific content types.
7596-7602: Java/Go document example aligned with updated schemas
The document-based chat examples now use the newV2ChatRequeststructure and general message/content types.
7738-7744: Streaming examples reflect detailed event schemas
Python, Java, and Go streaming snippets correctly iterate over the new discriminator-basedStreamedChatResponseV2events.
7866-7872: Tool usage examples adopt unified tool message schemas
Java and Go samples now use the newToolV2andToolV2Functiondefinitions consistent with updated schemas.
7938-7946: Non-streamed response schema enriched with additional properties
The addition offinish_reason,id,logprobs,message, andusageproperties improves feedback granularity.
7957-7984: Streaming response schema mapping updated to detailed event types
Theresponse-streamdiscriminator now covers all fine-grained events (ChatMessageStartEvent,ChatContentDeltaEvent, etc.), enhancing client parsing.
11275-11278: Consistent versioning in summary for/v2/rerank
The “Rerank V2 API” summary and description align with v2 conventions.
11535-11539: Content array now referencesTextContent
Replaced legacy chat-specific content with the newTextContentschema.
11565-11570: Nested message content correctly updated toTextContent
The oneOf mapping and discriminator for message items now useTextContent.
11905-11908: ChatMessageV2 oneOf references updated
Now usesUserMessage/SystemMessagein place of the older V2 variants.
16490-16499:ResponseFormatmapping correctly updated
The oneOf now referencesTextResponseFormatandJSONResponseFormatwith proper discriminator values.
16520-16529:ResponseFormatV2mapping correctly updated
The oneOf discriminator for V2 now mapstextandjson_objectto the appropriate schemas.
16624-16628:Sourceschema oneOf updated
Replaced the old chat-specific source variants with the generalizedToolSourceandDocumentSourceschemas.
16711-16714: Verify completeness ofSystemMessageschema
The snippet shows onlytitleandrequired: - role. Ensure that thecontentproperty (and any other necessary fields) is defined and matches other message schemas.
16721-16728: SystemMessage content mapping updated toTextContent
The oneOf for message arrays now correctly referencesTextContentwith a matching discriminator.
16734-16735: Thex-fern-type-nameannotation for codegen is expected and does not require changes.
16735-16748: TextContent schema well-defined
Defines requiredtype/textproperties and uses a clear discriminator.
16749-16760: TextResponseFormat schema correct
TheTextResponseFormatobject is properly specified with audiences and thetypeproperty.
16761-16769: TextResponseFormatV2 schema correct
The V2 variant matches the naming and mapping conventions of the new response formats.
16885-16893: ToolContent schema updated
The oneOf correctly usesTextContentandDocumentContent, with a matching discriminator mapping.
16894-16901: ToolMessage schema properly defined
Includes requiredroleandtool_resultsfields referencingToolResult.
17154-17165: UserMessage schema leveragesContentunion
Thecontentproperty correctly allows a string or array ofContentblocks, and the role is constrained touser.
| Content: | ||
| oneOf: | ||
| - $ref: '#/components/schemas/TextContent' | ||
| - $ref: '#/components/schemas/ImageContent' | ||
| description: A Content block which contains information about the content type and the content itself. | ||
| discriminator: | ||
| propertyName: type | ||
| mapping: | ||
| image_url: '#/components/schemas/ImageContent' | ||
| text: '#/components/schemas/TextContent' | ||
| x-fern-type-name: Content |
There was a problem hiding this comment.
Mismatch between Content discriminator mapping and ContentType enum
The mapping includes image_url but the ContentType enum only defines text, which will cause validation failures. Please add image_url to the ContentType enum.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 12549 to 12559, the discriminator
mapping for the Content schema includes "image_url" but the ContentType enum
only defines "text". To fix this, add "image_url" as a valid value in the
ContentType enum to ensure consistency and prevent validation errors.
| ToolSource: | ||
| title: Tool Output | ||
| type: object | ||
| properties: | ||
| id: | ||
| type: string | ||
| description: The unique identifier of the document | ||
| tool_output: | ||
| type: object | ||
| x-fern-type-name: ToolSource-z53ra6 | ||
| x-fern-type-name: ToolSource | ||
| ToolV2: |
There was a problem hiding this comment.
Untyped tool_output in ToolSource schema
The tool_output property is declared as a free-form object. It should reference the appropriate schema (e.g., ToolContent or ToolResult) instead of object.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 16947 to 16958, the property
tool_output in the ToolSource schema is currently typed as a generic object.
Replace this with a reference to the correct schema, such as ToolContent or
ToolResult, by updating the type declaration to use $ref pointing to the
appropriate schema definition instead of using type: object.
| - $ref: '#/components/schemas/ChatMessage' | ||
| - $ref: '#/components/schemas/ChatToolMessage' | ||
| - $ref: '#/components/schemas/ToolMessage' | ||
| discriminator: | ||
| propertyName: role | ||
| mapping: | ||
| CHATBOT: '#/components/schemas/ChatMessage' | ||
| SYSTEM: '#/components/schemas/ChatMessage' | ||
| TOOL: '#/components/schemas/ChatToolMessage' | ||
| TOOL: '#/components/schemas/ToolMessage' | ||
| USER: '#/components/schemas/ChatMessage' |
There was a problem hiding this comment.
Incorrect discriminator mapping keys in Message schema
The mapping uses uppercase role values (TOOL, USER, etc.), but actual payloads use lowercase (tool, user, etc.). This mismatch will break resolution. Update the keys to match case-sensitive role values.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 16313 to 16321, the discriminator
mapping keys in the Message schema use uppercase role values, but the actual
payloads use lowercase. Update the mapping keys from uppercase (e.g., TOOL,
USER) to lowercase (e.g., tool, user) to ensure correct schema resolution.
| DocumentSource: | ||
| type: object | ||
| properties: | ||
| document: | ||
| type: object | ||
| x-fern-type-name: DocumentSource-w70a62 | ||
| id: | ||
| type: string | ||
| description: The unique identifier of the document | ||
| description: A document source object containing the unique identifier of the document and the document itself. | ||
| x-fern-type-name: DocumentSource |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Reference DocumentContent in DocumentSource schema
The document property is currently a free-form object. Replace its definition with $ref: '#/components/schemas/DocumentContent' to leverage the existing schema.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 12988 to 12998, the DocumentSource
schema defines the document property as a generic object. Replace this with a
reference to the existing DocumentContent schema by changing the document
property's type to use $ref: '#/components/schemas/DocumentContent'. This will
ensure the document property conforms to the defined DocumentContent structure.
Pull request was closed
Summary by CodeRabbit
New Features
Improvements
Bug Fixes