Conversation
tiangolo
changed the title
contentMediaTypecontentMediaType instead of format: binary
|
But it will now also change schema for other parameters (not only from typing import Annotated
from pydantic import BaseModel
from fastapi import FastAPI, Query
class Model(BaseModel):
data: bytes
app = FastAPI()
@app.get("/")
def read_root(params: Annotated[Model, Query()]):
pass
@app.post("/")
def post_root(params: Model):
passSee schema{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/": {
"get": {
"summary": "Read Root",
"operationId": "read_root__get",
"parameters": [
{
"name": "data",
"in": "query",
"required": true,
"schema": {
"type": "string",
"contentMediaType": "application/octet-stream", # <= contentMediaType for Query parameter
"title": "Data"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"summary": "Post Root",
"operationId": "post_root__post",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Model"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"Model": {
"properties": {
"data": {
"type": "string",
"contentMediaType": "application/octet-stream", # <= contentMediaType for Json Body
"title": "Data"
}
},
"type": "object",
"required": [
"data"
],
"title": "Model"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
}Will it be correct? |
|
Ah, the thing is that using I also checked with Swagger UI and the behavior is the same with both 
|
I agree about Query parameters (and other non-Body parameters). But it also affects JSON Body parameters (see previous schema example). Not sure how useful it is to use |
|
Ah, yes, this would be the actual correct format. JSON also doesn't support direct bytes, it has to be strings encoded in UTF-8, it would have to be in base64 or similar. So, if anyone is using I'm also making a PR to Pydantic, just added here another part to support base64. This would work: from fastapi import FastAPI
from pydantic import BaseModel
class Model(BaseModel):
data: bytes
model_config = {"ser_json_bytes": "base64"}
app = FastAPI()
@app.post("/")
def post_root(params: Model):
passAnd now it has the proper JSON Schema defininig it, and tools like Swagger UI can represent it correctly: 
I also added all the references to the description in this PR. |
tiangolo
changed the title
contentMediaType instead of format: binary"contentMediaType": "application/octet-stream" instead of "format": "binary"
|
Hi @tiangolo, 
|
|
Hi, same issue here. I rolled back my local FastAPI version and noticed that 0.129.1 breaks our schemas. When generating TS clients from openapi.json, some File arrays are now interpreted as arrays of strings. It may be related to this. |
4 participants
♻️ Fix JSON Schema for bytes, use
"contentMediaType": "application/octet-stream"instead of"format": "binary"Background
format: binarywas defined in OpenAPI 3.0.x, in OpenAPI 3.1.x the schema was aligned with the latest JSON Schema, recommending insteadcontentMediaType: application/octet-stream.I suspect the JSON Schema for
bytesusing"format": "binary"comes from my first implementation in Pydantic 1.x.It was defined and suggested in OpenAPI 3.0.x (not in JSON Schema): https://spec.openapis.org/oas/v3.0.3.html#considerations-for-file-uploads
OpenAPI 3.1.x aligned support with JSON Schema draft 07, so it was suggested to upate file uploads to use the regular JSON Schema format:
"contentMediaType": "application/octet-stream": https://learn.openapis.org/upgrading/v3.0-to-v3.1This is defined in JSON Schema 07: https://json-schema.org/draft-07/json-schema-validation#rfc.section.8.4
JSON Schema 2020-12 Note
Now OpenAPI 3.2 is aligned with JSON Schema 2020-12, which is what Pydantic v2 implements (except for this, I'm implementing it there too).
It's the same as in JSON Schema draft 07, so this still applies: https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-01#name-contentmediatype
Usage in JSON
JSON as a format actually doesn't support bytes, everything has to be in UTF-8 strings. Transporting bytes in JSON would require encoding bytes in a string, e.g. with base64.
But as JSON Schema is not only defined to declare JSON payloads but also payloads that could have a comparable structure and defined with JSON Schema, it's still there in the spec.