Skip to content

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

Added spec for library API response (#66623)

Nathan Voxland953f266b2402
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index f0548886387..4901af07327 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -351,7 +351,8 @@
{:team "UX West"
:api #{metabase.collections.core
metabase.collections.models.collection
- metabase.collections.models.collection.root}
+ metabase.collections.models.collection.root
+ metabase.collections.schema}
:uses #{api
api-keys
app-db
diff --git a/enterprise/backend/src/metabase_enterprise/library/api.clj b/enterprise/backend/src/metabase_enterprise/library/api.clj
index c547711ba24..991ec69fea9 100644
--- a/enterprise/backend/src/metabase_enterprise/library/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/library/api.clj
@@ -5,6 +5,7 @@
[metabase.api.routes.common :refer [+auth]]
[metabase.collections.core :as collections]
[metabase.collections.models.collection :as collection]
+ [metabase.collections.schema :as collections.schema]
[toucan2.core :as t2]))
(set! *warn-on-reflection* true)
@@ -30,19 +31,20 @@
below-tables? (t2/exists? :model/Table :is_published true :collection_id [:in descendent-ids])]
;; This function is only used on the root Library which cannot have items directly in it
;; So can assume :here is only collection, and all descendants are :below
- (assoc collection :here #{:collection}
+ (assoc collection :here #{"collection"}
:below (cond-> below-card-types
(contains? below-card-types :model)
(-> (disj :model) (conj :dataset))
below-tables? (conj :table)
- true sort))))
+ true sort
+ true ((partial map name))))))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/"
- "Get the Library. If no library exists, it doesn't fail but returns an empty response."
+(api.macros/defendpoint :get "/" :- [:or ::collections.schema/CollectionItem [:map [:data nil?]]]
+ "Get the Library. If no library exists, it doesn't fail but returns an empty response"
[_route
_query
_body]
diff --git a/resources/openapi/openapi.json b/resources/openapi/openapi.json
index c2d26bab76d..1bbd865dcd9 100644
--- a/resources/openapi/openapi.json
+++ b/resources/openapi/openapi.json
@@ -4745,6 +4745,344 @@
"required" : [ "moved" ],
"type" : "object"
},
+ "metabase.collections.schema.CardType" : {
+ "enum" : [ "model", "question", "metric" ],
+ "type" : "string"
+ },
+ "metabase.collections.schema.Collection" : {
+ "properties" : {
+ "archived" : {
+ "type" : "boolean"
+ },
+ "authority_level" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "below" : {
+ "items" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItemModel"
+ },
+ "type" : "array"
+ },
+ "can_delete" : {
+ "type" : "boolean"
+ },
+ "can_restore" : {
+ "type" : "boolean"
+ },
+ "can_write" : {
+ "type" : "boolean"
+ },
+ "children" : {
+ "items" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.Collection"
+ },
+ "type" : "array"
+ },
+ "description" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "effective_ancestors" : {
+ "properties" : { },
+ "type" : "object"
+ },
+ "effective_location" : {
+ "type" : "string"
+ },
+ "entity_id" : {
+ "type" : "string"
+ },
+ "git_sync_enabled" : {
+ "type" : "boolean"
+ },
+ "here" : {
+ "items" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItemModel"
+ },
+ "type" : "array",
+ "uniqueItems" : true
+ },
+ "id" : {
+ "anyOf" : [ {
+ "type" : "string"
+ }, {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ } ]
+ },
+ "is_personal" : {
+ "type" : "boolean"
+ },
+ "is_remote_synced" : {
+ "type" : "boolean"
+ },
+ "is_sample" : {
+ "type" : "boolean"
+ },
+ "location" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "name" : {
+ "type" : "string"
+ },
+ "parent_id" : {
+ "oneOf" : [ {
+ "anyOf" : [ {
+ "type" : "string"
+ }, {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ } ]
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "personal_owner_id" : {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ },
+ "slug" : {
+ "type" : "string"
+ },
+ "type" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionType"
+ }
+ },
+ "required" : [ "id", "name", "description", "can_write", "can_restore", "can_delete", "archived", "location" ],
+ "type" : "object"
+ },
+ "metabase.collections.schema.CollectionItem" : {
+ "properties" : {
+ "archived" : {
+ "type" : "boolean"
+ },
+ "authority_level" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "based_on_upload" : {
+ "oneOf" : [ {
+ "anyOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "string"
+ } ]
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "below" : {
+ "items" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItemModel"
+ },
+ "type" : "array"
+ },
+ "can_delete" : {
+ "type" : "boolean"
+ },
+ "can_restore" : {
+ "type" : "boolean"
+ },
+ "can_write" : {
+ "type" : "boolean"
+ },
+ "collection" : {
+ "oneOf" : [ {
+ "$ref" : "#/components/schemas/metabase.collections.schema.Collection"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "collection_id" : {
+ "oneOf" : [ {
+ "anyOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "string"
+ } ]
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "collection_position" : {
+ "oneOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "collection_preview" : {
+ "oneOf" : [ {
+ "type" : "boolean"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "copy" : {
+ "type" : "boolean"
+ },
+ "dashboard_count" : {
+ "oneOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "database_id" : {
+ "oneOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "description" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "display" : {
+ "type" : "string"
+ },
+ "effective_location" : {
+ "type" : "string"
+ },
+ "entity_id" : {
+ "type" : "string"
+ },
+ "fully_parameterized" : {
+ "oneOf" : [ {
+ "type" : "boolean"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "here" : {
+ "items" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItemModel"
+ },
+ "type" : "array",
+ "uniqueItems" : true
+ },
+ "id" : {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ },
+ "last-edit-info" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.LastEditInfo"
+ },
+ "location" : {
+ "type" : "string"
+ },
+ "model" : {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItemModel"
+ },
+ "moderated_status" : {
+ "type" : "string"
+ },
+ "name" : {
+ "type" : "string"
+ },
+ "personal_owner_id" : {
+ "oneOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "type" : {
+ "anyOf" : [ {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionType"
+ }, {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CardType"
+ } ]
+ }
+ },
+ "required" : [ "id", "name", "description", "archived" ],
+ "type" : "object"
+ },
+ "metabase.collections.schema.CollectionItemModel" : {
+ "enum" : [ "card", "dataset", "metric", "dashboard", "snippet", "collection", "indexed-entity", "indexed-entity", "document", "table" ],
+ "type" : "string"
+ },
+ "metabase.collections.schema.CollectionType" : {
+ "enum" : [ "instance-analytics", "trash", "remote-synced", "library", "library-models", "library-metrics" ],
+ "type" : "string"
+ },
+ "metabase.collections.schema.LastEditInfo" : {
+ "properties" : {
+ "email" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "first_name" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "id" : {
+ "oneOf" : [ {
+ "description" : "value must be an integer greater than zero.",
+ "minimum" : 1,
+ "type" : "integer"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "last_name" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ },
+ "timestamp" : {
+ "oneOf" : [ {
+ "type" : "string"
+ }, {
+ "type" : "null"
+ } ]
+ }
+ },
+ "required" : [ "id", "email", "first_name", "last_name", "timestamp" ],
+ "type" : "object"
+ },
"metabase.legacy-mbql.schema.!=" : {
"allOf" : [ ],
"description" : "schema for a valid MBQL 4 :!= clause"
@@ -21101,11 +21439,28 @@
},
"/api/ee/library/" : {
"get" : {
- "description" : "Get the Library. If no library exists, it doesn't fail but returns an empty response.",
+ "description" : "Get the Library. If no library exists, it doesn't fail but returns an empty response",
"parameters" : [ ],
"responses" : {
"2XX" : {
- "description" : "Successful response"
+ "content" : {
+ "application/json" : {
+ "schema" : {
+ "anyOf" : [ {
+ "$ref" : "#/components/schemas/metabase.collections.schema.CollectionItem"
+ }, {
+ "properties" : {
+ "data" : {
+ "type" : "null"
+ }
+ },
+ "required" : [ "data" ],
+ "type" : "object"
+ } ]
+ }
+ }
+ },
+ "description" : "map where {:id -> <value must be an integer greater than zero.>, :entity_id (optional) -> <string>, :model (optional) -> <enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :name -> <string>, :description -> <nullable string>, :archived -> <boolean>, :copy (optional) -> <boolean>, :collection_position (optional) -> <nullable value must be an integer greater than zero.>, :collection_preview (optional) -> <nullable boolean>, :fully_parameterized (optional) -> <nullable boolean>, :based_on_upload (optional) -> <nullable value must be an integer greater than zero., or string>, :collection (optional) -> <nullable map where {:id -> <string, or value must be an integer greater than zero.>, :name -> <string>, :slug (optional) -> <string>, :entity_id (optional) -> <string>, :description -> <nullable string>, :can_write -> <boolean>, :can_restore -> <boolean>, :can_delete -> <boolean>, :archived -> <boolean>, :children (optional) -> <sequence of map where {:id -> <string, or value must be an integer greater than zero.>, :name -> <string>, :slug (optional) -> <string>, :entity_id (optional) -> <string>, :description -> <nullable string>, :can_write -> <boolean>, :can_restore -> <boolean>, :can_delete -> <boolean>, :archived -> <boolean>, :children (optional) -> <sequence of recursive :metabase.collections.schema/Collection>, :authority_level (optional) -> <nullable string>, :type (optional) -> <enum of instance-analytics, trash, remote-synced, library, library-models, library-metrics>, :is_remote_synced (optional) -> <boolean>, :parent_id (optional) -> <nullable string, or value must be an integer greater than zero.>, :personal_owner_id (optional) -> <value must be an integer greater than zero.>, :is_personal (optional) -> <boolean>, :is_sample (optional) -> <boolean>, :location -> <nullable string>, :effective_location (optional) -> <string>, :effective_ancestors (optional) -> <map>, :here (optional) -> <set of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :below (optional) -> <sequence of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :git_sync_enabled (optional) -> <boolean>}>, :authority_level (optional) -> <nullable string>, :type (optional) -> <enum of instance-analytics, trash, remote-synced, library, library-models, library-metrics>, :is_remote_synced (optional) -> <boolean>, :parent_id (optional) -> <nullable string, or value must be an integer greater than zero.>, :personal_owner_id (optional) -> <value must be an integer greater than zero.>, :is_personal (optional) -> <boolean>, :is_sample (optional) -> <boolean>, :location -> <nullable string>, :effective_location (optional) -> <string>, :effective_ancestors (optional) -> <map>, :here (optional) -> <set of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :below (optional) -> <sequence of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :git_sync_enabled (optional) -> <boolean>}>, :collection_id (optional) -> <nullable value must be an integer greater than zero., or string>, :display (optional) -> <string>, :personal_owner_id (optional) -> <nullable value must be an integer greater than zero.>, :database_id (optional) -> <nullable value must be an integer greater than zero.>, :moderated_status (optional) -> <string>, :type (optional) -> <enum of instance-analytics, trash, remote-synced, library, library-models, library-metrics, or enum of model, question, metric>, :here (optional) -> <set of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :below (optional) -> <sequence of enum of card, dataset, metric, dashboard, snippet, collection, indexed-entity, indexed-entity, document, table>, :can_write (optional) -> <boolean>, :can_restore (optional) -> <boolean>, :can_delete (optional) -> <boolean>, :last-edit-info (optional) -> <map where {:id -> <nullable value must be an integer greater than zero.>, :email -> <nullable string>, :first_name -> <nullable string>, :last_name -> <nullable string>, :timestamp -> <nullable string>}>, :location (optional) -> <string>, :effective_location (optional) -> <string>, :authority_level (optional) -> <nullable string>, :dashboard_count (optional) -> <nullable value must be an integer greater than zero.>}, or map where {:data -> <null>}"
},
"4XX" : {
"description" : "Client error response"
diff --git a/src/metabase/collections/schema.clj b/src/metabase/collections/schema.clj
new file mode 100644
index 00000000000..639beeda545
--- /dev/null
+++ b/src/metabase/collections/schema.clj
@@ -0,0 +1,97 @@
+(ns metabase.collections.schema
+ (:require
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.malli.schema :as ms]))
+
+(mr/def ::CollectionContentModel [:enum "card" "dataset" "metric"])
+
+(mr/def ::CollectionType [:enum
+ "instance-analytics"
+ "trash"
+ "remote-synced"
+ "library"
+ "library-models"
+ "library-metrics"])
+
+(mr/def ::CardType [:enum "model" "question" "metric"])
+
+(mr/def ::CollectionItemModel [:enum
+ "card"
+ "dataset"
+ "metric"
+ "dashboard"
+ "snippet"
+ "collection"
+ "indexed-entity"
+ "indexed-entity"
+ "document"
+ "table"])
+
+(mr/def ::Collection
+ [:map
+ [:id [:or :string ms/PositiveInt]]
+ [:name :string]
+ [:slug {:optional true} :string]
+ [:entity_id {:optional true} :string]
+ [:description [:maybe :string]]
+ [:can_write :boolean]
+ [:can_restore :boolean]
+ [:can_delete :boolean]
+ [:archived :boolean]
+ [:children {:optional true} [:sequential [:ref ::Collection]]]
+ [:authority_level {:optional true} [:maybe :string]]
+ [:type {:optional true} ::CollectionType]
+ [:is_remote_synced {:optional true} :boolean]
+
+ [:parent_id {:optional true} [:maybe [:or :string ms/PositiveInt]]]
+ [:personal_owner_id {:optional true} ms/PositiveInt]
+ [:is_personal {:optional true} :boolean]
+ [:is_sample {:optional true} :boolean]
+
+ [:location [:maybe :string]]
+ [:effective_location {:optional true} :string]
+ [:effective_ancestors {:optional true} :map]
+
+ [:here {:optional true} [:set ::CollectionItemModel]]
+ [:below {:optional true} [:sequential ::CollectionItemModel]]
+
+ [:git_sync_enabled {:optional true} :boolean]])
+
+(mr/def ::LastEditInfo
+ [:map
+ [:id [:maybe ms/PositiveInt]]
+ [:email [:maybe :string]]
+ [:first_name [:maybe :string]]
+ [:last_name [:maybe :string]]
+ [:timestamp [:maybe :string]]])
+
+(mr/def ::CollectionItem
+ [:map
+ [:id ms/PositiveInt]
+ [:entity_id {:optional true} :string]
+ [:model {:optional true} ::CollectionItemModel]
+ [:name :string]
+ [:description [:maybe :string]]
+ [:archived :boolean]
+ [:copy {:optional true} :boolean]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_preview {:optional true} [:maybe :boolean]]
+ [:fully_parameterized {:optional true} [:maybe :boolean]]
+ [:based_on_upload {:optional true} [:maybe [:or ms/PositiveInt :string]]]
+ [:collection {:optional true} [:maybe ::Collection]]
+ [:collection_id {:optional true} [:maybe [:or ms/PositiveInt :string]]]
+ [:display {:optional true} :string]
+ [:personal_owner_id {:optional true} [:maybe ms/PositiveInt]]
+ [:database_id {:optional true} [:maybe ms/PositiveInt]]
+ [:moderated_status {:optional true} :string]
+ [:type {:optional true} [:or ::CollectionType ::CardType]]
+ [:here {:optional true} [:set ::CollectionItemModel]]
+ [:below {:optional true} [:sequential ::CollectionItemModel]]
+ [:can_write {:optional true} :boolean]
+ [:can_restore {:optional true} :boolean]
+ [:can_delete {:optional true} :boolean]
+ [:last-edit-info {:optional true} ::LastEditInfo]
+ [:location {:optional true} :string]
+ [:effective_location {:optional true} :string]
+ [:authority_level {:optional true} [:maybe :string]]
+ [:dashboard_count {:optional true} [:maybe ms/PositiveInt]]])