Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add description field for data apps (#79544)

Timofey Kachalov4c5abeb77e83
diff --git a/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml b/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
index 800e24a54e0..820f73d5fb5 100644
--- a/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
+++ b/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
@@ -1,2 +1,3 @@
name: Good App
+description: A well-formed app that syncs cleanly
path: ./index.js
diff --git a/e2e/support/helpers/e2e-data-app-helpers.ts b/e2e/support/helpers/e2e-data-app-helpers.ts
index 4a62f47edf5..29fe63578b5 100644
--- a/e2e/support/helpers/e2e-data-app-helpers.ts
+++ b/e2e/support/helpers/e2e-data-app-helpers.ts
@@ -48,6 +48,7 @@ export const fakeDataApp = (overrides: Partial<DataApp> = {}): DataApp => ({
id: 1,
name: DATA_APP_NAME,
display_name: DATA_APP_DISPLAY_NAME,
+ description: null,
bundle_path: `data_apps/${DATA_APP_NAME}/dist/index.js`,
enabled: true,
allowed_hosts: [],
diff --git a/e2e/test/scenarios/data-apps/sync.cy.spec.ts b/e2e/test/scenarios/data-apps/sync.cy.spec.ts
index f7f028123d0..bed4ffb67ee 100644
--- a/e2e/test/scenarios/data-apps/sync.cy.spec.ts
+++ b/e2e/test/scenarios/data-apps/sync.cy.spec.ts
@@ -37,6 +37,9 @@ describe("scenarios > data apps > repo sync", () => {
.scrollIntoView()
.within(() => {
cy.findByRole("link", { name: "Good App" }).should("be.visible");
+ cy.findByText("A well-formed app that syncs cleanly").should(
+ "be.visible",
+ );
cy.findByText(/^Synced/).should("be.visible");
});
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/README.md b/enterprise/backend/src/metabase_enterprise/data_apps/README.md
index ff81d9d2316..e6653b7a8a9 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/README.md
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/README.md
@@ -21,9 +21,9 @@ data_apps/
dist/app.js
```
-`data_app.yaml` declares the display name, the bundle path relative to the app's own directory, and
-optionally the origins the sandboxed bundle may `fetch`/XHR. See `config.clj` for the format and its
-validation.
+`data_app.yaml` declares the display name and the bundle path relative to the app's own directory,
+plus two optional fields: a one-line `description` shown beside the name in the admin UI, and the
+origins the sandboxed bundle may `fetch`/XHR. See `config.clj` for the format and its validation.
**The directory name is the slug.** Nothing in the config declares it. This is what makes slug
collisions structurally impossible — a repo can't hold two `data_apps/sales` directories, and
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/api.clj b/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
index 3b2f9d6b45d..df3018d5360 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
@@ -57,6 +57,7 @@
[:id ms/PositiveInt]
[:name ms/NonBlankString]
[:display_name ms/NonBlankString]
+ [:description [:maybe :string]]
[:bundle_path ms/NonBlankString]
[:enabled :boolean]
[:allowed_hosts [:sequential :string]]
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/config.clj b/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
index 8cd086b111a..9644b81f24c 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
@@ -3,6 +3,7 @@
directory under `data_apps/` (see `README.md` in this directory for the layout):
name: Sales dashboard # display name
+ description: Pipeline … # optional — one line on what the app does
path: dist/index.js # bundle path, relative to this app's directory
allowed_hosts: # optional — origins the sandboxed bundle may fetch/XHR
- https://api.example.com
@@ -44,6 +45,32 @@
[p]
(-> (str p) str/trim (str/replace #"^\./" "")))
+(defn- normalize-description
+ "Trim and fold whitespace runs, so a YAML block scalar still stores as one line."
+ [d]
+ (-> (str d) str/trim (str/replace #"\s+" " ")))
+
+(def ^:private max-description-chars
+ "Cap on `description`. Checked here, not by the column type, so an over-long one fails just its own app."
+ 255)
+
+(defn- parse-description
+ "Validate + normalize the optional one-line `description`. Returns nil when it's
+ absent or blank; throws a 400 when it's present but not a string — a YAML list or
+ mapping would otherwise `str`-ify into Clojure collection syntax and sync as-is —
+ or when it exceeds [[max-description-chars]]."
+ [raw ^String dir]
+ (when (some? raw)
+ (when-not (string? raw)
+ (throw (ex-info (tru "{0}/{1}: \"description\" must be a one-line string." dir config-file-name)
+ {:status-code 400})))
+ (let [d (not-empty (normalize-description raw))]
+ (when (and d (> (count d) max-description-chars))
+ (throw (ex-info (tru "{0}/{1}: \"description\" is a one-line summary — it must be {2} characters or fewer."
+ dir config-file-name max-description-chars)
+ {:status-code 400})))
+ d)))
+
(def ^:private allowed-host-re
"A single `allowed_hosts` entry: an origin the app's sandboxed bundle may
`fetch`/XHR — scheme + host, an optional `*.` subdomain wildcard, and an
@@ -106,16 +133,19 @@
(defn parse-app-config
"Parse the bytes of one `data_app.yaml` from the app directory `dir` (e.g.
- `data_apps/sales`) into `{:slug ..., :display_name ..., :path ...,
- :allowed_hosts [...]}`. The slug is the directory's name; `path` is relative to
- the directory; `:allowed_hosts` is a (possibly empty) vector of origins the
- sandboxed bundle may reach. Throws an `ex-info` with `:status-code` 400 on
+ `data_apps/sales`) into `{:slug ..., :display_name ..., :description ...,
+ :path ..., :allowed_hosts [...]}`. The slug is the directory's name; `path` is
+ relative to the directory; `:description` is an optional one-liner (nil when
+ absent or blank, capped at [[max-description-chars]]); `:allowed_hosts` is a
+ (possibly empty) vector of origins the sandboxed bundle may reach. Throws an
+ `ex-info` with `:status-code` 400 on
malformed or incomplete content — including a directory whose name isn't a
usable slug, since that app has no URL to be served at."
[^bytes bytes ^String dir]
(let [parsed (parse-yaml bytes dir)
slug (dir-slug dir)
name (some-> (:name parsed) str str/trim not-empty)
+ description (parse-description (:description parsed) dir)
path (some-> (:path parsed) normalize-path not-empty)
allowed-hosts (parse-allowed-hosts parsed dir)]
(when-not (re-matches slug-pattern slug)
@@ -133,4 +163,4 @@
(when (path-traversal? path)
(throw (ex-info (tru "{0}/{1}: \"path\" must not contain \"..\"." dir config-file-name)
{:status-code 400})))
- {:slug slug, :display_name name, :path path, :allowed_hosts allowed-hosts}))
+ {:slug slug, :display_name name, :description description, :path path, :allowed_hosts allowed-hosts}))
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/models/data_app.clj b/enterprise/backend/src/metabase_enterprise/data_apps/models/data_app.clj
index 904acb0a6d5..2c24cfe7ba2 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/models/data_app.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/models/data_app.clj
@@ -42,7 +42,7 @@
(def non-blob-columns
"Columns to select for normal data-app metadata reads, excluding the raw bundle blob."
- [:id :name :display_name :bundle_path :enabled :allowed_hosts
+ [:id :name :display_name :description :bundle_path :enabled :allowed_hosts
:bundle_hash :last_synced_sha :last_synced_at :sync_error
:created_at :updated_at])
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj b/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
index 2a77ff383bb..c7f24b325f7 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
@@ -52,8 +52,8 @@
directory's immediate children as repo-root relative paths, and `read-file`
returns file text or nil), iterate the folders under `data_apps/` and return one
entry per folder that is an app — it holds a `data_app.yaml`; a folder without
- one is skipped. Each entry is a parsed app `{:slug :display_name :bundle
- :allowed_hosts}` (with `:bundle` the repo-root relative bundle path) or
+ one is skipped. Each entry is a parsed app `{:slug :display_name :description
+ :bundle :allowed_hosts}` (with `:bundle` the repo-root relative bundle path) or
`{:config-error <message>}`. Parse/read failures are isolated per app so one bad
config can't abort the sync.
@@ -70,8 +70,12 @@
:when (some #{config-path} (list-dir dir))]
(try
(if-let [content (read-file config-path)]
- (let [{:keys [slug display_name path allowed_hosts]} (data-app.config/parse-app-config (->bytes content) dir)]
- {:slug slug, :display_name display_name, :bundle (str dir "/" path), :allowed_hosts allowed_hosts})
+ (let [{:keys [slug display_name description path allowed_hosts]} (data-app.config/parse-app-config (->bytes content) dir)]
+ {:slug slug
+ :display_name display_name
+ :description description
+ :bundle (str dir "/" path)
+ :allowed_hosts allowed_hosts})
{:slug (data-app.config/dir-slug dir), :config-error (tru "Could not read {0}." config-path)})
(catch Throwable e
{:slug (data-app.config/dir-slug dir), :config-error (ex-message e)}))))
@@ -86,19 +90,27 @@
(t2/update! :model/DataApp :name slug row)
(t2/insert! :model/DataApp (assoc row :name slug))))
+(defn- app-metadata-changed?
+ "Whether the metadata a sync stores whether or not the bundle loaded differs from
+ the `existing` row. The failure path stores exactly these, so it asks this
+ directly; the success path adds the bundle to the question."
+ [existing {:keys [display_name description bundle_path allowed_hosts]}]
+ (or (not= (:display_name existing) display_name)
+ (not= (:description existing) description)
+ (not= (:bundle_path existing) bundle_path)
+ (not= (vec (or (:allowed_hosts existing) []))
+ (vec (or allowed_hosts [])))))
+
(defn- app-content-changed?
"Whether the just-synced content differs from the `existing` row (nil = a new
app). Compares only content-bearing fields — a `last_synced_sha` /
`last_synced_at` bump on an otherwise-identical app is NOT a change, so callers
can count real changes (e.g. for the remote-sync pull summary)."
- [existing {:keys [display_name bundle_path bundle_hash allowed_hosts]}]
+ [existing {:keys [bundle_hash] :as fields}]
(or (nil? existing)
(some? (:sync_error existing))
- (not= (:display_name existing) display_name)
- (not= (:bundle_path existing) bundle_path)
(not= (:bundle_hash existing) bundle_hash)
- (not= (vec (or (:allowed_hosts existing) []))
- (vec (or allowed_hosts [])))))
+ (app-metadata-changed? existing fields)))
(defn- mark-config-error!
"Record a `data_app.yaml` parse failure on an app that already has a row, keeping the
@@ -117,7 +129,7 @@
previously cached bundle (if any) is kept. `existing` is the app's pre-sync row
(or nil); returns true when this sync actually changed the app's content (a new
app, differing bundle/metadata, or a new failure) so callers can count changes."
- [existing {:keys [slug display_name bundle sha read-file allowed_hosts]}]
+ [existing {:keys [slug display_name description bundle sha read-file allowed_hosts]}]
(try
(let [content (read-file bundle)
_ (when-not content
@@ -129,6 +141,7 @@
slug (quot max-bundle-bytes (* 1024 1024)))
{:status-code 413})))
(let [fields {:display_name display_name
+ :description description
:allowed_hosts allowed_hosts
:bundle_path bundle
:bundle_hash (bytes-hash bytes)}]
@@ -139,13 +152,18 @@
:sync_error nil))
(app-content-changed? existing fields)))
(catch Throwable e
- (upsert-by-name! slug {:display_name display_name
- :allowed_hosts allowed_hosts
- :bundle_path bundle
- :sync_error (ex-message e)})
- (log/warnf "[data-app] failed to sync app %s: %s" slug (ex-message e))
- ;; a failing app counts as a change unless it was already failing identically
- (or (nil? existing) (not= (:sync_error existing) (ex-message e))))))
+ (let [fields {:display_name display_name
+ :description description
+ :allowed_hosts allowed_hosts
+ :bundle_path bundle}]
+ (upsert-by-name! slug (assoc fields :sync_error (ex-message e)))
+ (log/warnf "[data-app] failed to sync app %s: %s" slug (ex-message e))
+ ;; A failing app counts as a change when the failure is new, and also when
+ ;; the metadata above moved: the upsert stores an edited description even
+ ;; though the bundle still fails, so the pull summary has to admit it.
+ (or (nil? existing)
+ (not= (:sync_error existing) (ex-message e))
+ (app-metadata-changed? existing fields))))))
(defn import-from-snapshot!
"Materialize data apps from a synced repo `snapshot`:
@@ -175,7 +193,7 @@
present-slugs (into #{} (map :slug) results)
;; pre-sync rows, so we can tell a real change from a sha/timestamp bump
existing (into {} (map (juxt :name identity))
- (t2/select [:model/DataApp :name :display_name :allowed_hosts
+ (t2/select [:model/DataApp :name :display_name :description :allowed_hosts
:bundle_path :bundle_hash :sync_error]))
{:keys [changed removed]}
(t2/with-transaction [_conn]
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
index 9d3c4769db1..37878e5e884 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
@@ -15,10 +15,42 @@
([s dir] (data-app.config/parse-app-config (->bytes s) dir)))
(deftest parse-valid-config-test
- (is (= {:slug "sales" :display_name "Sales dashboard" :path "dist/index.js" :allowed_hosts []}
+ (is (= {:slug "sales" :display_name "Sales dashboard" :description nil :path "dist/index.js" :allowed_hosts []}
(parse "name: Sales dashboard
path: ./dist/index.js"))))
+(deftest parse-description-test
+ (testing "an optional one-liner is trimmed and carried through"
+ (is (= "Pipeline health by region"
+ (:description (parse "name: X\ndescription: ' Pipeline health by region '\npath: dist/index.js")))))
+ (testing "absent → nil (the field is optional)"
+ (is (nil? (:description (parse "name: X\npath: dist/index.js")))))
+ (testing "blank → nil, so an unfilled placeholder doesn't become an empty description"
+ (doseq [blank ["" "' '"]]
+ (is (nil? (:description (parse (str "name: X\ndescription: " blank "\npath: dist/index.js"))))
+ (str "should be nil for: " (pr-str blank)))))
+ (testing "a YAML block scalar spanning several lines is folded onto one"
+ (is (= "First line second line"
+ (:description (parse "name: X\ndescription: |\n First line\n second line\npath: dist/index.js")))))
+ (testing "a description at the length cap is accepted"
+ (is (= 255
+ (count (:description (parse (str "name: X\ndescription: " (apply str (repeat 255 "x"))
+ "\npath: dist/index.js")))))))
+ (testing "one over the cap is rejected — a paragraph here would be stored in full and returned on every list request"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"description.*255 characters or fewer"
+ (parse (str "name: X\ndescription: " (apply str (repeat 256 "x"))
+ "\npath: dist/index.js")))))
+ (testing "the cap applies to the folded value, not the raw YAML"
+ (is (= 255
+ (count (:description (parse (str "name: X\ndescription: >\n " (apply str (repeat 255 "x"))
+ "\npath: dist/index.js")))))))
+ (testing "a non-string description (a YAML list or mapping) is rejected, not str-ified into the row"
+ (doseq [bad ["description: [foo, bar]"
+ "description:\n key: value"]]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"description.*must be a one-line string"
+ (parse (str "name: X\n" bad "\npath: dist/index.js")))
+ (str "should reject: " (pr-str bad))))))
+
(deftest slug-comes-from-the-directory-test
(testing "the app's slug is the name of the directory it lives in"
(is (= "inventory" (:slug (parse "name: X\npath: dist/index.js" "data_apps/inventory")))))
@@ -50,7 +82,7 @@ path: ./dist/index.js"))))
(deftest unknown-fields-are-ignored-test
(testing "unknown keys don't fail the parse — including a stray `slug`, which the directory name overrides"
- (is (= {:slug "sales" :display_name "X" :path "dist/index.js" :allowed_hosts []}
+ (is (= {:slug "sales" :display_name "X" :description nil :path "dist/index.js" :allowed_hosts []}
(parse "name: X\nslug: elsewhere\nfuture_option: 1\npath: dist/index.js")))))
(deftest parse-errors-test
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
index 3a6b426b8f8..b188da28bf9 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
@@ -24,9 +24,10 @@
(defn- app-files
"The repo files for one app in `data_apps/<dir>`. `dir` is the app's slug — the
config declares no slug, it is the directory's name."
- [dir {:keys [name path bundle]}]
+ [dir {:keys [name path bundle description]}]
{(format "data_apps/%s/data_app.yaml" dir)
- (format "name: %s\npath: %s\n" name path)
+ (str (format "name: %s\npath: %s\n" name path)
+ (when description (format "description: %s\n" description)))
(format "data_apps/%s/%s" dir path) bundle})
(deftest changed-count-tracks-content-not-sha-bumps-test
@@ -48,6 +49,41 @@
(data-app.sync/import-from-snapshot!
(snapshot (app-files "a" {:name "A renamed" :path "index.js" :bundle "V2"})))))))))
+(deftest description-is-optional-and-tracked-like-other-metadata-test
+ (mt/with-model-cleanup [:model/DataApp]
+ (let [sync-app (fn [& {:as app}]
+ (data-app.sync/import-from-snapshot!
+ (snapshot (app-files "a" (merge {:name "A" :path "index.js" :bundle "V1"} app)))))]
+ (testing "an app that declares no description syncs with a nil one"
+ (sync-app)
+ (is (nil? (t2/select-one-fn :description :model/DataApp :name "a"))))
+ (testing "adding one counts as a change and is materialized"
+ (is (=? {:changed 1} (sync-app :description "What this app does")))
+ (is (= "What this app does" (t2/select-one-fn :description :model/DataApp :name "a"))))
+ (testing "re-syncing the same description is not a change"
+ (is (=? {:changed 0} (sync-app :description "What this app does"))))
+ (testing "dropping it from the config clears the column"
+ (is (=? {:changed 1} (sync-app)))
+ (is (nil? (t2/select-one-fn :description :model/DataApp :name "a")))))))
+
+(deftest metadata-edits-count-while-an-app-keeps-failing-test
+ (testing "an app whose bundle is missing still stores metadata edits, so they count as changes"
+ (mt/with-model-cleanup [:model/DataApp]
+ (let [sync-app (fn [& {:as app}]
+ (data-app.sync/import-from-snapshot!
+ (snapshot {"data_apps/a/data_app.yaml"
+ (str "name: A\npath: index.js\n"
+ (when-let [d (:description app)]
+ (format "description: %s\n" d)))})))]
+ (is (=? {:changed 1} (sync-app :description "First")) "the first failure is a change")
+ (is (some? (t2/select-one-fn :sync_error :model/DataApp :name "a")))
+ (testing "re-syncing the same failing app unchanged is not a change"
+ (is (=? {:changed 0} (sync-app :description "First"))))
+ (testing "editing the description is a change even though the bundle still fails"
+ (is (=? {:changed 1} (sync-app :description "Second")))
+ (is (= "Second" (t2/select-one-fn :description :model/DataApp :name "a"))
+ "the edit is stored, which is why the pull cannot report it as a no-op"))))))
+
(deftest switching-repos-prunes-old-apps-overrides-shared-adds-new-test
(testing "syncing a different repo: drop apps only the old repo had, override shared slugs, add new ones"
(mt/with-model-cleanup [:model/DataApp]
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
index 6b19033c7f4..6f15108662a 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
@@ -74,6 +74,12 @@ export const DataAppSummary = ({ app }: Props) => {
</Text>
)}
+ {app.description && (
+ <Text size="sm" c="text-secondary" lh="1.4" my="xs">
+ {app.description}
+ </Text>
+ )}
+
<Group gap="xs" align="center" wrap="wrap">
<Text
size="sm"
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
index 672c319dee7..b353859abcc 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
@@ -48,6 +48,34 @@ describe("DataAppSummary", () => {
).not.toBeInTheDocument();
});
+ describe("description", () => {
+ it("renders the description when the app declares one", () => {
+ renderWithProviders(
+ <DataAppSummary
+ app={createMockDataApp({
+ display_name: "Sales",
+ description: "Pipeline health by region",
+ })}
+ />,
+ );
+
+ expect(screen.getByText("Pipeline health by region")).toBeInTheDocument();
+ });
+
+ it("renders nothing extra when the app has no description", () => {
+ renderWithProviders(
+ <DataAppSummary
+ app={createMockDataApp({ display_name: "Sales", description: null })}
+ />,
+ );
+
+ expect(screen.getByText("Sales")).toBeInTheDocument();
+ expect(
+ screen.queryByText("Pipeline health by region"),
+ ).not.toBeInTheDocument();
+ });
+ });
+
describe("sync status", () => {
it("shows the short synced SHA when the app has synced", () => {
renderWithProviders(
diff --git a/frontend/src/metabase-types/api/data-app.ts b/frontend/src/metabase-types/api/data-app.ts
index 852c40a73fd..8b253dab6f3 100644
--- a/frontend/src/metabase-types/api/data-app.ts
+++ b/frontend/src/metabase-types/api/data-app.ts
@@ -11,6 +11,8 @@ export interface DataApp {
/** The app's slug. */
name: string;
display_name: string;
+ /** Optional one-line summary of what the app does. */
+ description: string | null;
/** Path within the repo to the built bundle. */
bundle_path: string;
/** Admin toggle. When false the app is not served. */
diff --git a/frontend/src/metabase-types/api/mocks/data-app.ts b/frontend/src/metabase-types/api/mocks/data-app.ts
index 25020192c6c..e4d78d3450b 100644
--- a/frontend/src/metabase-types/api/mocks/data-app.ts
+++ b/frontend/src/metabase-types/api/mocks/data-app.ts
@@ -4,6 +4,7 @@ export const createMockDataApp = (opts?: Partial<DataApp>): DataApp => ({
id: 1,
name: "sales",
display_name: "Sales",
+ description: null,
bundle_path: "data_apps/sales/dist/index.js",
enabled: true,
allowed_hosts: [],
diff --git a/resources/migrations/064/20260806_data_app_description.yaml b/resources/migrations/064/20260806_data_app_description.yaml
new file mode 100644
index 00000000000..fda1659d234
--- /dev/null
+++ b/resources/migrations/064/20260806_data_app_description.yaml
@@ -0,0 +1,21 @@
+## Add an optional one-line description to data apps.
+##
+## Authored as `description:` in the app's `data_app.yaml` and surfaced in the
+## admin UI so it's clear what each app does. The field is optional, so this
+## column is nullable and stays NULL for an app that declares none.
+
+databaseChangeLog:
+ - changeSet:
+ id: v64.2026-08-06T00:00:00
+ author: timofei
+ comment: Add optional description column to data_app
+ changes:
+ - addColumn:
+ tableName: data_app
+ columns:
+ - column:
+ name: description
+ type: ${text.type}
+ remarks: Optional one-line description from the manifest, shown in the admin UI. NULL when the app declares none.
+ constraints:
+ nullable: true
diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.md
index 979c8ae2c79..51f125e78e5 100644
--- a/skills/metabase-data-app-setup/SKILL.md
+++ b/skills/metabase-data-app-setup/SKILL.md
@@ -131,6 +131,7 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th
```yaml
name: Sales App # display name shown in the admin UI
+ description: Pipeline health and quota attainment by region # optional — see below
path: ./dist/index.js # bundle path, relative to this app's directory — leave as-is unless you change the build output
# allowed_hosts: # optional — external origins the app may fetch/XHR (see below)
# - https://api.example.com
@@ -139,6 +140,14 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th
Commit it alongside the built bundle (the file `path` points at).
+ **`description`** — optional: a single short sentence saying what the app
+ does, shown under its name in the admin UI so admins can tell apps apart at a
+ glance. Sync folds any whitespace into single spaces and rejects anything over
+ 255 characters; the admin list wraps what is left rather than cutting it off,
+ so a sentence reads well there and a paragraph crowds out the rows around it.
+ Replace the template's placeholder with a real sentence about *this* app, or
+ delete the line entirely if it adds nothing beyond the name.
+
**`allowed_hosts`** — only needed if the app calls an **external** API directly
with `fetch`/`XHR`. The sandbox blocks all network egress by default; listing an
origin here (exact or a `*.` subdomain wildcard) opens it in both `npm run dev`
diff --git a/skills/metabase-data-app-setup/template/data_app.yaml b/skills/metabase-data-app-setup/template/data_app.yaml
index 29be0051fd0..cef4d227c62 100644
--- a/skills/metabase-data-app-setup/template/data_app.yaml
+++ b/skills/metabase-data-app-setup/template/data_app.yaml
@@ -1,4 +1,7 @@
name: Data App Template
+
+description: A summary of what this app does
+
path: ./dist/index.js
# Origins this app may call with fetch/XHR. Everything else is blocked — both in