stac-utils · vincentsarago · Apr 15, 2025 · Apr 14, 2025 · Apr 15, 2025 · Apr 15, 2025
diff --git a/CHANGES.md b/CHANGES.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Remove defaults in OpenAPI schemas
+
 ### Added
 
 - add `enable_direct_response` settings to by-pass Pydantic validation and FastAPI serialization for responses

diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/collection_search/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/collection_search/request.py
@@ -40,21 +40,21 @@ class BaseCollectionSearchPostRequest(BaseModel):
     bbox: Optional[BBox] = Field(
         default=None,
         description="Only return items intersecting this bounding box. Mutually exclusive with **intersects**.",  # noqa: E501
-        json_schema_extra={
-            "example": [-175.05, -85.05, 175.05, 85.05],
+        openapi_examples={
+            "user-provided": {"value": None},
+            "Montreal": {"value": "-73.896103,45.364690,-73.413734,45.674283"},
         },
     )
     datetime: Optional[str] = Field(
         default=None,
         description="""Only return items that have a temporal property that intersects this value.\n
 Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.""",  # noqa: E501
-        json_schema_extra={
-            "examples": {
-                "datetime": {"value": "2018-02-12T23:20:50Z"},
-                "closed-interval": {"value": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"},
-                "open-interval-from": {"value": "2018-02-12T00:00:00Z/.."},
-                "open-interval-to": {"value": "../2018-03-18T12:31:12Z"},
-            },
+        openapi_examples={
+            "user-provided": {"value": None},
+            "datetime": {"value": "2018-02-12T23:20:50Z"},
+            "closed-interval": {"value": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"},
+            "open-interval-from": {"value": "2018-02-12T00:00:00Z/.."},
+            "open-interval-to": {"value": "../2018-03-18T12:31:12Z"},
         },
     )
     limit: Optional[Limit] = Field(

diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/fields/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/fields/request.py
@@ -49,8 +49,9 @@ def _fields_converter(
         Optional[str],
         Query(
             description="Include or exclude fields from items body.",
-            json_schema_extra={
-                "example": "properties.datetime",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "datetime": {"value": "properties.datetime"},
             },
         ),
     ] = None,

diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/filter/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/filter/request.py
@@ -23,8 +23,11 @@ class FilterExtensionGetRequest(APIRequest):
             description="""A CQL filter expression for filtering items.\n
 Supports `CQL-JSON` as defined in https://portal.ogc.org/files/96288\n
 Remember to URL encode the CQL-JSON if using GET""",
-            json_schema_extra={
-                "example": "id='LC08_L1TP_060247_20180905_20180912_01_T1_L1TP' AND collection='landsat8_l1tp'",  # noqa: E501
+            openapi_examples={
+                "user-provided": {"value": None},
+                "landsat8-item": {
+                    "value": "id='LC08_L1TP_060247_20180905_20180912_01_T1_L1TP' AND collection='landsat8_l1tp'"  # noqa: E501
+                },
             },
         ),
     ] = attr.ib(default=None)
@@ -51,19 +54,25 @@ class FilterExtensionPostRequest(BaseModel):
         default=None,
         alias="filter",
         description="A CQL filter expression for filtering items.",
-        json_schema_extra={
-            "example": {
-                "op": "and",
-                "args": [
-                    {
-                        "op": "=",
-                        "args": [
-                            {"property": "id"},
-                            "LC08_L1TP_060247_20180905_20180912_01_T1_L1TP",
-                        ],
-                    },
-                    {"op": "=", "args": [{"property": "collection"}, "landsat8_l1tp"]},
-                ],
+        openapi_examples={
+            "user-provided": {"value": None},
+            "landsat8-item": {
+                "value": {
+                    "op": "and",
+                    "args": [
+                        {
+                            "op": "=",
+                            "args": [
+                                {"property": "id"},
+                                "LC08_L1TP_060247_20180905_20180912_01_T1_L1TP",
+                            ],
+                        },
+                        {
+                            "op": "=",
+                            "args": [{"property": "collection"}, "landsat8_l1tp"],
+                        },
+                    ],
+                },
             },
         },
     )

diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/free_text/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/free_text/request.py
@@ -15,8 +15,9 @@ def _ft_converter(
         Optional[str],
         Query(
             description="Parameter to perform free-text queries against STAC metadata",
-            json_schema_extra={
-                "example": "ocean,coast",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "Coastal": {"value": "ocean,coast"},
             },
         ),
     ] = None,
@@ -48,8 +49,9 @@ class FreeTextAdvancedExtensionGetRequest(APIRequest):
         Optional[str],
         Query(
             description="Parameter to perform free-text queries against STAC metadata",
-            json_schema_extra={
-                "example": "ocean,coast",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "Coastal": {"value": "ocean,coast"},
             },
         ),
     ] = attr.ib(default=None)

diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/query/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/query/request.py
@@ -18,8 +18,9 @@ class QueryExtensionGetRequest(APIRequest):
         Optional[str],
         Query(
             description="Allows additional filtering based on the properties of Item objects",  # noqa: E501
-            json_schema_extra={
-                "example": '{"eo:cloud_cover": {"gte": 95}}',
+            openapi_examples={
+                "user-provided": {"value": None},
+                "cloudy": {"value": '{"eo:cloud_cover": {"gte": 95}}'},
             },
         ),
     ] = attr.ib(default=None)
@@ -31,7 +32,8 @@ class QueryExtensionPostRequest(BaseModel):
     query: Optional[Dict[str, Dict[str, Any]]] = Field(
         None,
         description="Allows additional filtering based on the properties of Item objects",  # noqa: E501
-        json_schema_extra={
-            "example": {"eo:cloud_cover": {"gte": 95}},
+        openapi_examples={
+            "user-provided": {"value": None},
+            "cloudy": {"value": '{"eo:cloud_cover": {"gte": 95}}'},
         },
     )
diff --git a/stac_fastapi/extensions/stac_fastapi/extensions/core/sort/request.py b/stac_fastapi/extensions/stac_fastapi/extensions/core/sort/request.py
@@ -16,8 +16,10 @@ def _sort_converter(
         Optional[str],
         Query(
             description="An array of property names, prefixed by either '+' for ascending or '-' for descending. If no prefix is provided, '+' is assumed.",  # noqa: E501
-            json_schema_extra={
-                "example": "-gsd,-datetime",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "resolution": {"value": "-gsd"},
+                "resolution-and-dates": {"value": "-gsd,-datetime"},
             },
         ),
     ],
@@ -38,12 +40,15 @@ class SortExtensionPostRequest(BaseModel):
     sortby: Optional[List[PostSortModel]] = Field(
         None,
         description="An array of property (field) names, and direction in form of '{'field': '<property_name>', 'direction':'<direction>'}'",  # noqa: E501
-        json_schema_extra={
-            "example": [
-                {
-                    "field": "properties.created",
-                    "direction": "asc",
-                }
-            ],
+        openapi_examples={
+            "user-provided": {"value": None},
+            "creation-time": {
+                "value": [
+                    {
+                        "field": "properties.created",
+                        "direction": "asc",
+                    }
+                ],
+            },
         },
     )
diff --git a/stac_fastapi/types/stac_fastapi/types/search.py b/stac_fastapi/types/stac_fastapi/types/search.py
@@ -46,8 +46,10 @@ def _collection_converter(
         Optional[str],
         Query(
             description="Array of collection Ids to search for items.",
-            json_schema_extra={
-                "example": "collection1,collection2",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "single-collection": {"value": "collection1"},
+                "multi-collections": {"value": "collection1,collection2"},
             },
         ),
     ] = None,
@@ -60,8 +62,10 @@ def _ids_converter(
         Optional[str],
         Query(
             description="Array of Item ids to return.",
-            json_schema_extra={
-                "example": "item1,item2",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "single-item": {"value": "item1"},
+                "multi-items": {"value": "item1,item2"},
             },
         ),
     ] = None,
@@ -74,8 +78,9 @@ def _bbox_converter(
         Optional[str],
         Query(
             description="Only return items intersecting this bounding box. Mutually exclusive with **intersects**.",  # noqa: E501
-            json_schema_extra={
-                "example": "-175.05,-85.05,175.05,85.05",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "Montreal": {"value": "-73.896103,45.364690,-73.413734,45.674283"},
             },
         ),
     ] = None,
@@ -99,6 +104,7 @@ def _validate_datetime(instance, attribute, value):
         description="""Only return items that have a temporal property that intersects this value.\n
 Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.""",  # noqa: E501
         openapi_examples={
+            "user-provided": {"value": None},
             "datetime": {"value": "2018-02-12T23:20:50Z"},
             "closed-interval": {"value": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"},
             "open-interval-from": {"value": "2018-02-12T00:00:00Z/.."},
@@ -162,6 +168,7 @@ class BaseSearchGetRequest(APIRequest, DatetimeMixin):
             description="""Only return items intersecting this GeoJSON Geometry. Mutually exclusive with **bbox**. \n
 *Remember to URL encode the GeoJSON geometry when using GET request*.""",  # noqa: E501
             openapi_examples={
+                "user-provided": {"value": None},
                 "madrid": {
                     "value": {
                         "type": "Feature",