From 17ae470cdc1d9f9b3133437ef3f31896721a6aa4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Mus=C3=ADlek?= <jan.musilek@nic.cz>
Date: Fri, 15 Sep 2023 14:41:57 +0200
Subject: [PATCH] Fix #166 - Add docs for validating default values

---
 docs/index.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/index.md b/docs/index.md
index e3217046..d893636c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -104,6 +104,40 @@ print(Settings().model_dump())
 
     Check the [Environment variable names documentation](#environment-variable-names) for more information.
 
+## Validation of default values
+
+Unlike pydantic `BaseModel`, default values of `BaseSettings` fields are validated by default.
+You can disable this behaviour by setting `validate_default=False` either in `model_config`
+or on field-by-field basis:
+
+```py
+import datetime as dt
+
+from pydantic import Field
+from pydantic.functional_validators import BeforeValidator
+from typing_extensions import Annotated
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class GlobalSettings(BaseSettings):
+    model_config = SettingsConfigDict(validate_default=False)
+
+    # default won't be validated
+    date: Annotated[dt.date, BeforeValidator(dt.date.fromisoformat)] = dt.date(
+        2000, 1, 1
+    )
+
+
+class LocalSettings(BaseSettings):
+    # default won't be validated
+    date: Annotated[dt.date, BeforeValidator(dt.date.fromisoformat)] = Field(
+        default=dt.date(2000, 1, 1), validate_default=False
+    )
+```
+
+Check the [Validation of default values](validators.md#validation-of-default-values) for more information.
+
 ## Environment variable names
 
 By default, the environment variable name is the same as the field name.