From 3130f2fc099ab04bdc740b7e1ec0af3b96e1ebdc Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Sun, 19 Apr 2026 12:27:17 -0700
Subject: [PATCH] docs: clarify response_schema vs response_json_schema

---
 README.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e409383c8..b808eeb6c 100644
--- a/README.md
+++ b/README.md
@@ -918,6 +918,10 @@ output might be lower in quality.
 
 #### JSON Schema support
 
+Use `response_json_schema` when you want to pass a standard JSON Schema
+dictionary directly. If you are passing Python types, Pydantic models, or
+other SDK-native schema helpers, use `response_schema` instead.
+
 Schemas can be provided as standard JSON schema.
 
 ```python
@@ -954,7 +958,8 @@ print(response.text)
 
 #### Pydantic Model Schema support
 
-Schemas can be provided as Pydantic Models.
+Schemas can also be provided as Python types or Pydantic models through
+`response_schema`.
 
 ```python
 from pydantic import BaseModel