From 9e6da9df8d4ba729672df127e7166c1625da3f67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 <16805946+edgarrmondragon@users.noreply.github.com>
Date: Thu, 23 May 2024 09:39:12 -0600
Subject: [PATCH] docs: Add a short guide on defining a configuration schema
 (#2449)

---
 docs/dev_guide.md            |  4 ++++
 docs/guides/config-schema.md | 34 ++++++++++++++++++++++++++++++++++
 docs/guides/index.md         |  1 +
 3 files changed, 39 insertions(+)
 create mode 100644 docs/guides/config-schema.md

diff --git a/docs/dev_guide.md b/docs/dev_guide.md
index 5d520916e..cc7cd9004 100644
--- a/docs/dev_guide.md
+++ b/docs/dev_guide.md
@@ -98,6 +98,10 @@ detailed guide.
   ```
 ````
 
+### Application configuration
+
+The SDK lets you define a configuration schema for your tap or target with full support for JSON schema validation. Read the more in-depth guide on [defining a configuration schema](./guides/config-schema.md).
+
 ### Using an existing library
 
 In some cases, there may already be a library that connects to the API and all you need the SDK for
diff --git a/docs/guides/config-schema.md b/docs/guides/config-schema.md
new file mode 100644
index 000000000..e5aad4378
--- /dev/null
+++ b/docs/guides/config-schema.md
@@ -0,0 +1,34 @@
+# Defining a configuration schema
+
+The Singer SDK provides a way to define a configuration schema for your tap or target. This schema is used to validate the configuration provided by the user and to provide a default configuration when the user does not provide one.
+
+The configuration schema is defined as a JSON object that describes the configuration options that your tap or target supports. We recommend using the [JSON Schema helpers](../typing.rst) provided by the SDK to define the schema.
+
+Here is an example of a configuration schema for a tap:
+
+```python
+from singer_sdk import Tap
+from singer_sdk import typing as th
+
+
+class MyTap(Tap):
+    name = "my-tap"
+
+    config_jsonschema = th.PropertiesList(
+        th.Property("api_key", th.StringType, required=True),
+        th.Property("base_url", th.StringType, default="https://api.example.com"),
+        th.Property("start_date", th.DateTimeType),
+    ).to_dict()
+```
+
+Explanation of the configuration schema defined above:
+
+- The `config_jsonschema` attribute is a JSON object that describes the configuration options that the tap supports.
+- The `th.PropertiesList` helper is used to define a list of properties.
+- The `th.Property` helper is used to define a property with a name, type, and other attributes.
+- The `th.StringType`, `th.DateTimeType`, etc. helpers are used to define the type of the property.
+- The `required` attribute is used to mark a property as required. The tap will throw an error if the user does not provide a value for a required property.
+- The `default` attribute is used to provide a default value for a property. The tap will use this if the user does not provide a value, so this can be accessed in the tap or streams with square bracket syntax, i.e. `self.config["base_url"]`.
+- The `to_dict()` method is used to convert the JSON object to a Python dictionary.
+
+See the full reference for the [typing module](../typing.rst) for more information on how to define a configuration schema.
diff --git a/docs/guides/index.md b/docs/guides/index.md
index e86aa149c..268f27957 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -8,4 +8,5 @@ The following pages contain useful information for developers building on top of
 porting
 pagination-classes
 custom-clis
+config-schema
 ```