diff --git a/CHANGELOG.md b/CHANGELOG.md
index fbe31d4b..2fb30bfc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,9 @@ way to update this template, but currently, we follow a pattern:
 
 ## Upcoming version 2019-XX-XX
 
+- [add] a comment about category and amenities filters. They don't work out-of-the-box, extended
+  data needs a schema before it can work as a search filter.
+  [#1055](https://github.com/sharetribe/flex-template-web/pull/1055)
 - [fix] EditListingWizard: currentUser was null when the EditListingPage got reloaded causing
   TypeError. [#1056](https://github.com/sharetribe/flex-template-web/pull/1056)
 
diff --git a/src/containers/SearchPage/README.md b/src/containers/SearchPage/README.md
index 42cd2788..7ed11dda 100644
--- a/src/containers/SearchPage/README.md
+++ b/src/containers/SearchPage/README.md
@@ -1,5 +1,14 @@
 # SearchPage
 
+> **Note:** _category_ and _amenities_ filters are not actually filtering anything by default. They
+> are tied to [extended data](https://www.sharetribe.com/docs/references/extended-data/), which is
+> likely to be customized in every marketplace. You can add public data to listing entity in your
+> client app, but to make it work as a search filter, we need to manually add
+> [a schema](https://www.sharetribe.com/docs/references/extended-data/#data-schema) for it - so that
+> search engine understands what is the nature of a given data key.
+
+## Structure
+
 SearchPage component has roughly 3 sections inside its layout: Topbar, MainPanel (for results and
 filters), and Map
 
diff --git a/src/containers/SearchPage/SearchPage.js b/src/containers/SearchPage/SearchPage.js
index 68033c38..accef6be 100644
--- a/src/containers/SearchPage/SearchPage.js
+++ b/src/containers/SearchPage/SearchPage.js
@@ -54,6 +54,11 @@ export class SearchPageComponent extends Component {
   filters() {
     const { categories, amenities, priceFilterConfig, dateRangeFilterConfig } = this.props;
 
+    // Note: "category" and "amenities" filters are not actually filtering anything by default.
+    // Currently, if you want to use them, we need to manually configure them to be available
+    // for search queries. Read more from extended data document:
+    // https://www.sharetribe.com/docs/references/extended-data/#data-schema
+
     return {
       categoryFilter: {
         paramName: 'pub_category',