Skip to content

feat: SDK with x-speakeasy-name-override schema naming#358

Draft
louis-sanna-dev wants to merge 3 commits intomainfrom
test/speakeasy-schema-naming
Draft

feat: SDK with x-speakeasy-name-override schema naming#358
louis-sanna-dev wants to merge 3 commits intomainfrom
test/speakeasy-schema-naming

Conversation

@louis-sanna-dev
Copy link
Contributor

@louis-sanna-dev louis-sanna-dev commented Feb 19, 2026

Summary

SDK regenerated from V2 spec with improved schema naming.

Related: dashboard#17924

Naming Convention

We use x-speakeasy-name-override to control SDK type names. The convention follows OpenAI/Google patterns:

1. Request Body Schemas (POST/PUT body)

Pattern: {Verb}{Entity}Request

CreateBatchJobRequest   (was: BatchJobIn)
CreateLibraryRequest    (was: LibraryIn)

2. Response Schemas (list/delete wrappers)

Pattern: {Verb}{Entity}Response

ListBatchJobsResponse   (was: BatchJobsOut)
ListFilesResponse       (was: ListFilesOut)
DeleteFileResponse      (was: DeleteFileOut)

3. Entity Schemas (the actual resource)

Pattern: Just the entity name

BatchJob                (was: BatchJobOut)
Library                 (was: LibraryOut)
Document                (was: DocumentOut)
FileObject              (was: FileSchema)

Example Usage

from mistralai.client import Mistral
from mistralai.client.models import BatchJob, ListBatchJobsResponse, FileObject

client = Mistral(api_key="...")

# create() returns BatchJob entity
job: BatchJob = client.batch.jobs.create(endpoint="/v1/chat/completions", ...)
print(job.id)       # BatchJob has .id, .status, .created_at, etc.
print(job.status)

# get() also returns BatchJob entity  
job: BatchJob = client.batch.jobs.get(job_id="...")

# list() returns ListBatchJobsResponse which contains BatchJob entities
response: ListBatchJobsResponse = client.batch.jobs.list()
for job in response.data:  # each item is a BatchJob
    print(job.id)

# Files use FileObject entity
files_response: ListFilesResponse = client.files.list()
for file in files_response.data:  # each item is a FileObject
    print(file.id, file.filename)

Where users see each type:

  • Entity (BatchJob, FileObject) - Return type of create(), get(), items in list responses
  • Response (ListBatchJobsResponse) - Return type of list(), wraps entities + pagination
  • Request (CreateBatchJobRequest) - Internal, users pass kwargs instead

Test plan

  • Lint passes
  • Examples pass
  • Typed example with mypy check added

@louis-sanna-dev louis-sanna-dev force-pushed the test/speakeasy-schema-naming branch from c493a25 to 0f16983 Compare February 19, 2026 17:21
Generated from V2 spec with x-speakeasy-name-override for cleaner type names.

Naming convention (follows OpenAI/Google patterns):
- Entity: {Entity} (e.g., BatchJob, FileObject, Library)
- Request: {Verb}{Entity}Request (e.g., CreateBatchJobRequest)
- Response: {Verb}{Entity}Response (e.g., ListFilesResponse, GetFileResponse)

Related: dashboard#17924
Shows how to use typed Entity, Response schemas:
- BatchJob, Library, FileObject (entities)
- ListBatchJobsResponse, ListFilesResponse (responses)

This file is type-checked by mypy in scripts/lint_custom_code.sh.
@louis-sanna-dev louis-sanna-dev force-pushed the test/speakeasy-schema-naming branch from 0f16983 to 86c46de Compare February 19, 2026 17:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

Comments