Obsługiwane typy i schematy JSON
Na tej stronie
Elementy budulcowe Twoich schematów
Aby zdefiniować strukturę swoich odpowiedzi, masz do dyspozycji siedem typów JSON. Każdy z nich spełnia określoną rolę w modelowaniu danych. Zrozumienie tych typów jest kluczowe dla projektowania skutecznych schematów.
Siedem obsługiwanych typów
string
Najczęstszy typ. Służy do nazw, opisów, identyfikatorów i wszelkiej treści tekstowej.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"description": { "type": "string" }
}
}
number
Obejmuje liczby całkowite i zmiennoprzecinkowe. Nie ma rozróżnienia między integer a float – pojedynczy typ number obsługuje oba przypadki.
{
"properties": {
"price": { "type": "number" },
"quantity": { "type": "number" }
}
}
boolean
Prawda lub fałsz. Idealny do flag, walidacji i decyzji binarnych.
{
"properties": {
"in_stock": { "type": "boolean" },
"express_delivery": { "type": "boolean" }
}
}
object
Pozwala na zagnieżdżanie struktur. Obiekt może zawierać inne obiekty, tablice lub wartości proste – bez limitu głębokości.
{
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postal_code": { "type": "string" }
}
}
}
}
array
Listy elementów tego samego typu. Możesz mieć tablice ciągów znaków, liczb, obiektów, a nawet innych tablic.
{
"properties": {
"skills": {
"type": "array",
"items": { "type": "string" }
}
}
}
enum
Skończony zbiór dozwolonych wartości. Niezbędny do kategoryzacji i klasyfikacji.
{
"properties": {
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
anyOf
Pozwala definiować unie typów. Pole może akceptować kilka różnych struktur. Przydatne, gdy pojedyncze pole może przybierać różne formy.
{
"properties": {
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": { "type": "string" }
}
},
{
"type": "object",
"properties": {
"phone": { "type": "string" }
}
}
]
}
}
}
Łączenie typów
Siła schematów polega na łączeniu tych typów. Oto realistyczny schemat do analizy produktu:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"in_stock": { "type": "boolean" },
"category": {
"type": "string",
"enum": ["electronics", "clothing", "grocery", "other"]
},
"tags": {
"type": "array",
"items": { "type": "string" }
},
"manufacturer": {
"type": "object",
"properties": {
"name": { "type": "string" },
"country": { "type": "string" }
}
}
}
}
Ten schemat miesza typy proste, enum, tablicę i zagnieżdżony obiekt. Model będzie respektował każde ograniczenie przy każdym wywołaniu.
Pola opcjonalne
Aby uczynić pole opcjonalnym, użyj anyOf z null:
{
"properties": {
"phone": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
}
}
}
W Pydantic odpowiada to zapisowi phone: str | None.
Kluczowe wnioski
- Siedem dostępnych typów:
string,number,object,array,boolean,enum,anyOf - Typy można dowolnie łączyć, aby modelować złożone struktury
- Pola opcjonalne definiuje się za pomocą
anyOfznull - Brak rozróżnienia na liczby całkowite i zmiennoprzecinkowe – istnieje jeden typ
number enumwymusza użycie predefiniowanych wartości do klasyfikacji