diff --git a/datasette/views/table_extras.py b/datasette/views/table_extras.py
index ce1d7bdf..948f3daa 100644
--- a/datasette/views/table_extras.py
+++ b/datasette/views/table_extras.py
@@ -184,6 +184,7 @@ class FacetResultsExtra(Extra):
     )
     scopes = {ExtraScope.TABLE}
     expensive = True
+    docs_note = "See :ref:`facets` for details of how facets work."
 
     async def resolve(self, context, facet_instances):
         facet_results = {}
@@ -215,7 +216,12 @@ class FacetResultsExtra(Extra):
 class FacetsTimedOutExtra(Extra):
     description = "Facet calculations that timed out"
     example = ExtraExample(
-        "/fixtures/facetable.json?_facet=state&_extra=facets_timed_out"
+        "/fixtures/facetable.json?_facet=state&_extra=facets_timed_out",
+        note=(
+            "A list of the names of any facets that exceeded the "
+            ":ref:`setting_facet_time_limit_ms` time limit - an empty list "
+            "if every facet calculation completed."
+        ),
     )
     scopes = {ExtraScope.TABLE}
 
@@ -236,6 +242,9 @@ class SuggestedFacetsExtra(Extra):
     )
     scopes = {ExtraScope.TABLE}
     expensive = True
+    docs_note = (
+        "Suggestions are controlled by the :ref:`setting_suggest_facets` setting."
+    )
 
     async def resolve(self, context, facet_instances):
         suggested_facets = []
@@ -278,7 +287,13 @@ class HumanDescriptionEnExtra(Extra):
 
 class NextUrlExtra(Extra):
     description = "Full URL for the next page of results"
-    example = ExtraExample("/fixtures/facetable.json?_size=1&_extra=next_url")
+    example = ExtraExample(
+        "/fixtures/facetable.json?_size=1&_extra=next_url",
+        note=(
+            "``null`` if there are no more pages of results. "
+            "See :ref:`json_api_pagination`."
+        ),
+    )
     scopes = {ExtraScope.TABLE}
 
     async def resolve(self, context):
@@ -366,6 +381,10 @@ class IsViewExtra(Extra):
 
 class DebugExtra(Extra):
     description = "Extra debug information"
+    docs_note = (
+        "The contents of this block are not a stable part of the Datasette "
+        "API and may change without warning."
+    )
     example = ExtraExample("/fixtures/facetable.json?_extra=debug")
     examples = {
         ExtraScope.ROW: ExtraExample(
@@ -482,6 +501,10 @@ class DisplayRowsExtra(Extra):
 
 class RenderCellExtra(Extra):
     description = "Rendered HTML for each cell using the render_cell plugin hook"
+    docs_note = (
+        "See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` "
+        "documentation."
+    )
     example = ExtraExample(
         value={
             "rows": [
@@ -598,7 +621,28 @@ class QueryExtra(Extra):
 
 class ColumnTypesExtra(Extra):
     description = "Column type assignments for this table"
-    example = ExtraExample(value={})
+    docs_note = (
+        "An empty object if no column types have been assigned. Column types "
+        "can be assigned in :ref:`configuration "
+        "<table_configuration_column_types>` or using the :ref:`set column "
+        "type API <TableSetColumnTypeView>`."
+    )
+    example = ExtraExample(
+        "/fixtures/facetable.json?_size=0&_extra=column_types",
+        note=(
+            "This example is from an instance where the ``tags`` column has "
+            "been assigned the ``json`` column type."
+        ),
+    )
+    examples = {
+        ExtraScope.ROW: ExtraExample(
+            "/fixtures/facetable/1.json?_extra=column_types",
+            note=(
+                "This example is from an instance where the ``tags`` column "
+                "has been assigned the ``json`` column type."
+            ),
+        )
+    }
     scopes = {ExtraScope.TABLE, ExtraScope.ROW}
 
     async def resolve(self, context):
@@ -615,7 +659,40 @@ class ColumnTypesExtra(Extra):
 
 
 class SetColumnTypeUiExtra(Extra):
-    description = "Column type UI metadata for this table"
+    description = "Information needed to build an interface for assigning column types"
+    docs_note = (
+        "``null`` unless the current actor is allowed to use the :ref:`set "
+        "column type API <TableSetColumnTypeView>` for this table."
+    )
+    example = ExtraExample(
+        value={
+            "path": "/fixtures/facetable/-/set-column-type",
+            "columns": {
+                "created": {
+                    "current": None,
+                    "options": [
+                        {"name": "email", "description": "Email address"},
+                        {"name": "json", "description": "JSON data"},
+                        {"name": "url", "description": "URL"},
+                    ],
+                },
+                "tags": {
+                    "current": {"type": "json", "config": None},
+                    "options": [
+                        {"name": "email", "description": "Email address"},
+                        {"name": "json", "description": "JSON data"},
+                        {"name": "url", "description": "URL"},
+                    ],
+                },
+            },
+        },
+        note=(
+            "Shape abbreviated to two columns, as seen by an actor with "
+            "``set-column-type`` permission. ``current`` is the column type "
+            "currently assigned to each column and ``options`` lists the "
+            "types that could be assigned to it."
+        ),
+    )
     scopes = {ExtraScope.TABLE}
 
     async def resolve(self, context):
@@ -667,13 +744,33 @@ class SetColumnTypeUiExtra(Extra):
 
 class MetadataExtra(Extra):
     description = "Metadata about the table, database or stored query"
-    example = ExtraExample("/fixtures/facetable.json?_extra=metadata")
+    docs_note = "See :ref:`metadata` for how to attach metadata to tables."
+    example = ExtraExample(
+        "/fixtures/facetable.json?_extra=metadata",
+        note=(
+            "This example is from an instance where the ``facetable`` table "
+            "has a metadata ``description`` and a :ref:`column description "
+            "<metadata_column_descriptions>` for its ``state`` column. The "
+            "``columns`` object is empty for tables with no column "
+            "descriptions."
+        ),
+    )
     examples = {
         ExtraScope.ROW: ExtraExample(
-            "/fixtures/simple_primary_key/1.json?_extra=metadata"
+            "/fixtures/simple_primary_key/1.json?_extra=metadata",
+            note=(
+                "This table has no metadata, so only an empty ``columns`` "
+                "object is returned."
+            ),
         ),
         ExtraScope.QUERY: ExtraExample(
-            "/fixtures/neighborhood_search.json?text=town&_extra=metadata"
+            "/fixtures/neighborhood_search.json?text=town&_extra=metadata",
+            note=(
+                "For stored queries this returns the full configuration of "
+                "the query, including the :ref:`stored query options "
+                "<queries_options>`. For ``?sql=`` queries it returns an "
+                "empty object."
+            ),
         ),
     }
     scopes = {ExtraScope.TABLE, ExtraScope.ROW, ExtraScope.QUERY}
@@ -733,6 +830,10 @@ class TableExtra(Extra):
 
 class DatabaseColorExtra(Extra):
     description = "Color assigned to the database"
+    docs_note = (
+        "A six character hex color, without the leading ``#``, derived from "
+        "a hash of the database name and used in the Datasette interface."
+    )
     example = ExtraExample("/fixtures/facetable.json?_extra=database_color")
     examples = {
         ExtraScope.ROW: ExtraExample(
@@ -780,6 +881,11 @@ class FiltersExtra(Extra):
 
 class CustomTableTemplatesExtra(Extra):
     description = "Custom template names considered for this table"
+    docs_note = (
+        "The first template in this list that exists will be used to render "
+        "the table on the HTML version of this page. See "
+        ":ref:`customization_custom_templates`."
+    )
     example = ExtraExample("/fixtures/facetable.json?_extra=custom_table_templates")
     scopes = {ExtraScope.TABLE}
 
@@ -793,6 +899,12 @@ class CustomTableTemplatesExtra(Extra):
 
 class SortedFacetResultsExtra(Extra):
     description = "Facet results sorted for display"
+    docs_note = (
+        "The same data as ``facet_results``, as a list in the order used by "
+        "the HTML interface: facets from :ref:`facet configuration "
+        "<facets_metadata>` first, then other facets ordered by their number "
+        "of results."
+    )
     example = ExtraExample(
         "/fixtures/facetable.json?_facet=state&_extra=sorted_facet_results"
     )
@@ -849,7 +961,15 @@ class ViewDefinitionExtra(Extra):
 
 class RenderersExtra(Extra):
     description = "Alternative output renderers available for this table"
-    example = ExtraExample("/fixtures/facetable.json?_extra=renderers")
+    example = ExtraExample(
+        "/fixtures/facetable.json?_extra=renderers",
+        note=(
+            "Each key is the name of an output format, each value the URL "
+            "for this data in that format. Plugins can add additional "
+            "formats using the :ref:`register_output_renderer() plugin hook "
+            "<plugin_register_output_renderer>`."
+        ),
+    )
     scopes = {ExtraScope.TABLE}
 
     async def resolve(self, context, expandable_columns, query):
@@ -887,6 +1007,10 @@ class RenderersExtra(Extra):
 
 class PrivateExtra(Extra):
     description = "Whether this resource is private to the current actor"
+    docs_note = (
+        "``true`` if the current actor can see this resource but an "
+        "anonymous user could not. See :ref:`authentication_permissions`."
+    )
     example = ExtraExample("/fixtures/facetable.json?_extra=private")
     examples = {
         ExtraScope.ROW: ExtraExample(
@@ -904,7 +1028,15 @@ class PrivateExtra(Extra):
 
 class ExpandableColumnsExtra(Extra):
     description = "Foreign key columns that can be expanded with labels"
-    example = ExtraExample("/fixtures/facetable.json?_extra=expandable_columns")
+    docs_note = "See :ref:`expand_foreign_keys` for how to expand these labels."
+    example = ExtraExample(
+        "/fixtures/facetable.json?_extra=expandable_columns",
+        note=(
+            "Each item is a ``[foreign_key, label_column]`` pair: the "
+            "foreign key relationship, then the column in the other table "
+            "that would be used as the label for each expanded value."
+        ),
+    )
     scopes = {ExtraScope.TABLE}
 
     async def resolve(self, context):
@@ -919,9 +1051,14 @@ class ExpandableColumnsExtra(Extra):
 class ForeignKeyTablesExtra(Extra):
     description = "Tables that link to this row using foreign keys"
     example = ExtraExample(
-        "/fixtures/simple_primary_key/1.json?_extra=foreign_key_tables"
+        "/fixtures/simple_primary_key/1.json?_extra=foreign_key_tables",
+        note=(
+            "``count`` is the number of rows in the other table that "
+            "reference this row, and ``link`` is a URL to browse those rows."
+        ),
     )
     scopes = {ExtraScope.ROW}
+    expensive = True
 
     async def resolve(self, context):
         return await context.foreign_key_tables(
@@ -930,7 +1067,30 @@ class ForeignKeyTablesExtra(Extra):
 
 
 class ExtrasExtra(Extra):
-    description = "Available ?_extra= blocks"
+    description = "List of ?_extra= blocks that can be used on this page"
+    example = ExtraExample(
+        value=[
+            {
+                "name": "count",
+                "description": "Total count of rows matching these filters",
+                "toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
+                "selected": False,
+            },
+            {
+                "name": "extras",
+                "description": "List of ?_extra= blocks that can be used on this page",
+                "toggle_url": "http://localhost/fixtures/facetable.json",
+                "selected": True,
+            },
+        ],
+        note=(
+            "Shape abbreviated from /fixtures/facetable.json?_extra=extras - "
+            "the full response lists every extra described on this page. "
+            "``toggle_url`` is the current URL with that extra added or "
+            "removed, and ``selected`` is ``true`` for extras included in "
+            "the current request."
+        ),
+    )
     scopes = {ExtraScope.TABLE, ExtraScope.ROW, ExtraScope.QUERY}
 
     async def resolve(self, context):
diff --git a/docs/json_api.rst b/docs/json_api.rst
index 6b595577..fbc3cf60 100644
--- a/docs/json_api.rst
+++ b/docs/json_api.rst
@@ -276,7 +276,7 @@ The available table extras are listed below.
         "select count(*) from facetable "
 
 ``facet_results``
-    Results of facets calculated against this data (May execute additional queries.)
+    Results of facets calculated against this data (May execute additional queries. See :ref:`facets` for details of how facets work.)
 
     Shape abbreviated from /fixtures/facetable.json?_facet=state&_extra=facet_results.
 
@@ -309,12 +309,14 @@ The available table extras are listed below.
 
     ``GET /fixtures/facetable.json?_facet=state&_extra=facets_timed_out``
 
+    A list of the names of any facets that exceeded the :ref:`setting_facet_time_limit_ms` time limit - an empty list if every facet calculation completed.
+
     .. code-block:: json
 
         []
 
 ``suggested_facets``
-    Suggestions for facets that might return interesting results (May execute additional queries.)
+    Suggestions for facets that might return interesting results (May execute additional queries. Suggestions are controlled by the :ref:`setting_suggest_facets` setting.)
 
     Shape abbreviated from /fixtures/facetable.json?_extra=suggested_facets.
 
@@ -341,6 +343,8 @@ The available table extras are listed below.
 
     ``GET /fixtures/facetable.json?_size=1&_extra=next_url``
 
+    ``null`` if there are no more pages of results. See :ref:`json_api_pagination`.
+
     .. code-block:: json
 
         "http://localhost/fixtures/facetable.json?_size=1&_extra=next_url&_next=1"
@@ -426,7 +430,7 @@ The available table extras are listed below.
         ]
 
 ``render_cell``
-    Rendered HTML for each cell using the render_cell plugin hook
+    Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
 
     The ``render_cell`` array has one item per row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
 
@@ -452,7 +456,7 @@ The available table extras are listed below.
         }
 
 ``debug``
-    Extra debug information
+    Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
 
     ``GET /fixtures/facetable.json?_extra=debug``
 
@@ -501,28 +505,108 @@ The available table extras are listed below.
         }
 
 ``column_types``
-    Column type assignments for this table
+    Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
 
-    .. code-block:: json
+    ``GET /fixtures/facetable.json?_size=0&_extra=column_types``
 
-        {}
-
-``set_column_type_ui``
-    Column type UI metadata for this table
-
-``metadata``
-    Metadata about the table, database or stored query
-
-    ``GET /fixtures/facetable.json?_extra=metadata``
+    This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
 
     .. code-block:: json
 
         {
-          "columns": {}
+          "tags": {
+            "type": "json",
+            "config": null
+          }
+        }
+
+``set_column_type_ui``
+    Information needed to build an interface for assigning column types (``null`` unless the current actor is allowed to use the :ref:`set column type API <TableSetColumnTypeView>` for this table.)
+
+    Shape abbreviated to two columns, as seen by an actor with ``set-column-type`` permission. ``current`` is the column type currently assigned to each column and ``options`` lists the types that could be assigned to it.
+
+    .. code-block:: json
+
+        {
+          "path": "/fixtures/facetable/-/set-column-type",
+          "columns": {
+            "created": {
+              "current": null,
+              "options": [
+                {
+                  "name": "email",
+                  "description": "Email address"
+                },
+                {
+                  "name": "json",
+                  "description": "JSON data"
+                },
+                {
+                  "name": "url",
+                  "description": "URL"
+                }
+              ]
+            },
+            "tags": {
+              "current": {
+                "type": "json",
+                "config": null
+              },
+              "options": [
+                {
+                  "name": "email",
+                  "description": "Email address"
+                },
+                {
+                  "name": "json",
+                  "description": "JSON data"
+                },
+                {
+                  "name": "url",
+                  "description": "URL"
+                }
+              ]
+            }
+          }
+        }
+
+``metadata``
+    Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
+
+    ``GET /fixtures/facetable.json?_extra=metadata``
+
+    This example is from an instance where the ``facetable`` table has a metadata ``description`` and a :ref:`column description <metadata_column_descriptions>` for its ``state`` column. The ``columns`` object is empty for tables with no column descriptions.
+
+    .. code-block:: json
+
+        {
+          "description": "A demo table of places, used to demonstrate facets",
+          "columns": {
+            "state": "Two letter US state code"
+          }
         }
 
 ``extras``
-    Available ?_extra= blocks
+    List of ?_extra= blocks that can be used on this page
+
+    Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
+
+    .. code-block:: json
+
+        [
+          {
+            "name": "count",
+            "description": "Total count of rows matching these filters",
+            "toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
+            "selected": false
+          },
+          {
+            "name": "extras",
+            "description": "List of ?_extra= blocks that can be used on this page",
+            "toggle_url": "http://localhost/fixtures/facetable.json",
+            "selected": true
+          }
+        ]
 
 ``database``
     Database name
@@ -543,7 +627,7 @@ The available table extras are listed below.
         "facetable"
 
 ``database_color``
-    Color assigned to the database
+    Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
 
     ``GET /fixtures/facetable.json?_extra=database_color``
 
@@ -556,6 +640,8 @@ The available table extras are listed below.
 
     ``GET /fixtures/facetable.json?_extra=renderers``
 
+    Each key is the name of an output format, each value the URL for this data in that format. Plugins can add additional formats using the :ref:`register_output_renderer() plugin hook <plugin_register_output_renderer>`.
+
     .. code-block:: json
 
         {
@@ -563,7 +649,7 @@ The available table extras are listed below.
         }
 
 ``custom_table_templates``
-    Custom template names considered for this table
+    Custom template names considered for this table (The first template in this list that exists will be used to render the table on the HTML version of this page. See :ref:`customization_custom_templates`.)
 
     ``GET /fixtures/facetable.json?_extra=custom_table_templates``
 
@@ -576,7 +662,7 @@ The available table extras are listed below.
         ]
 
 ``sorted_facet_results``
-    Facet results sorted for display
+    Facet results sorted for display (The same data as ``facet_results``, as a list in the order used by the HTML interface: facets from :ref:`facet configuration <facets_metadata>` first, then other facets ordered by their number of results.)
 
     ``GET /fixtures/facetable.json?_facet=state&_extra=sorted_facet_results``
 
@@ -643,7 +729,7 @@ The available table extras are listed below.
         true
 
 ``private``
-    Whether this resource is private to the current actor
+    Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
 
     ``GET /fixtures/facetable.json?_extra=private``
 
@@ -652,10 +738,12 @@ The available table extras are listed below.
         false
 
 ``expandable_columns``
-    Foreign key columns that can be expanded with labels
+    Foreign key columns that can be expanded with labels (See :ref:`expand_foreign_keys` for how to expand these labels.)
 
     ``GET /fixtures/facetable.json?_extra=expandable_columns``
 
+    Each item is a ``[foreign_key, label_column]`` pair: the foreign key relationship, then the column in the other table that would be used as the label for each expanded value.
+
     .. code-block:: json
 
         [
@@ -720,7 +808,7 @@ The following extras are available for row JSON responses.
         ]
 
 ``render_cell``
-    Rendered HTML for each cell using the render_cell plugin hook
+    Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
 
     The ``render_cell`` array has one item for the requested row. The object is keyed by column name. Only columns whose rendered value differs from the default are included.
 
@@ -741,7 +829,7 @@ The following extras are available for row JSON responses.
         }
 
 ``debug``
-    Extra debug information
+    Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
 
     ``GET /fixtures/simple_primary_key/1.json?_extra=debug``
 
@@ -803,17 +891,28 @@ The following extras are available for row JSON responses.
         }
 
 ``column_types``
-    Column type assignments for this table
+    Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
+
+    ``GET /fixtures/facetable/1.json?_extra=column_types``
+
+    This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
 
     .. code-block:: json
 
-        {}
+        {
+          "tags": {
+            "type": "json",
+            "config": null
+          }
+        }
 
 ``metadata``
-    Metadata about the table, database or stored query
+    Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
 
     ``GET /fixtures/simple_primary_key/1.json?_extra=metadata``
 
+    This table has no metadata, so only an empty ``columns`` object is returned.
+
     .. code-block:: json
 
         {
@@ -821,7 +920,26 @@ The following extras are available for row JSON responses.
         }
 
 ``extras``
-    Available ?_extra= blocks
+    List of ?_extra= blocks that can be used on this page
+
+    Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
+
+    .. code-block:: json
+
+        [
+          {
+            "name": "count",
+            "description": "Total count of rows matching these filters",
+            "toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
+            "selected": false
+          },
+          {
+            "name": "extras",
+            "description": "List of ?_extra= blocks that can be used on this page",
+            "toggle_url": "http://localhost/fixtures/facetable.json",
+            "selected": true
+          }
+        ]
 
 ``database``
     Database name
@@ -842,7 +960,7 @@ The following extras are available for row JSON responses.
         "simple_primary_key"
 
 ``database_color``
-    Color assigned to the database
+    Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
 
     ``GET /fixtures/simple_primary_key/1.json?_extra=database_color``
 
@@ -851,7 +969,7 @@ The following extras are available for row JSON responses.
         "9403e5"
 
 ``private``
-    Whether this resource is private to the current actor
+    Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
 
     ``GET /fixtures/simple_primary_key/1.json?_extra=private``
 
@@ -860,10 +978,12 @@ The following extras are available for row JSON responses.
         false
 
 ``foreign_key_tables``
-    Tables that link to this row using foreign keys
+    Tables that link to this row using foreign keys (May execute additional queries.)
 
     ``GET /fixtures/simple_primary_key/1.json?_extra=foreign_key_tables``
 
+    ``count`` is the number of rows in the other table that reference this row, and ``link`` is a URL to browse those rows.
+
     .. code-block:: json
 
         [
@@ -921,7 +1041,7 @@ The following extras are available for arbitrary SQL query responses and stored,
         ]
 
 ``render_cell``
-    Rendered HTML for each cell using the render_cell plugin hook
+    Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
 
     The ``render_cell`` array has one item per query result row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
 
@@ -941,7 +1061,7 @@ The following extras are available for arbitrary SQL query responses and stored,
         }
 
 ``debug``
-    Extra debug information
+    Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
 
     ``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=debug``
 
@@ -1000,10 +1120,12 @@ The following extras are available for arbitrary SQL query responses and stored,
         }
 
 ``metadata``
-    Metadata about the table, database or stored query
+    Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
 
     ``GET /fixtures/neighborhood_search.json?text=town&_extra=metadata``
 
+    For stored queries this returns the full configuration of the query, including the :ref:`stored query options <queries_options>`. For ``?sql=`` queries it returns an empty object.
+
     .. code-block:: json
 
         {
@@ -1029,7 +1151,26 @@ The following extras are available for arbitrary SQL query responses and stored,
         }
 
 ``extras``
-    Available ?_extra= blocks
+    List of ?_extra= blocks that can be used on this page
+
+    Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
+
+    .. code-block:: json
+
+        [
+          {
+            "name": "count",
+            "description": "Total count of rows matching these filters",
+            "toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
+            "selected": false
+          },
+          {
+            "name": "extras",
+            "description": "List of ?_extra= blocks that can be used on this page",
+            "toggle_url": "http://localhost/fixtures/facetable.json",
+            "selected": true
+          }
+        ]
 
 ``database``
     Database name
@@ -1041,7 +1182,7 @@ The following extras are available for arbitrary SQL query responses and stored,
         "fixtures"
 
 ``database_color``
-    Color assigned to the database
+    Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
 
     ``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=database_color``
 
@@ -1050,7 +1191,7 @@ The following extras are available for arbitrary SQL query responses and stored,
         "9403e5"
 
 ``private``
-    Whether this resource is private to the current actor
+    Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
 
     ``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=private``
 
diff --git a/docs/json_api_doc.py b/docs/json_api_doc.py
index 44ef4a42..422e67f4 100644
--- a/docs/json_api_doc.py
+++ b/docs/json_api_doc.py
@@ -93,9 +93,26 @@ async def _fetch_live_examples(scoped_classes):
         datasette = Datasette(
             [str(db_path)],
             settings={"num_sql_threads": 1},
+            metadata={
+                "databases": {
+                    "fixtures": {
+                        "tables": {
+                            "facetable": {
+                                "description": "A demo table of places, used to demonstrate facets",
+                                "columns": {"state": "Two letter US state code"},
+                            }
+                        }
+                    }
+                }
+            },
             config={
                 "databases": {
                     "fixtures": {
+                        "tables": {
+                            "facetable": {
+                                "column_types": {"tags": "json"},
+                            }
+                        },
                         "queries": {
                             "neighborhood_search": {
                                 "sql": textwrap.dedent("""
@@ -108,7 +125,7 @@ async def _fetch_live_examples(scoped_classes):
                                 """),
                                 "title": "Search neighborhoods",
                             }
-                        }
+                        },
                     }
                 }
             },