@malloy-publisher/app 0.0.114 → 0.0.116

package/dist/api-doc.yaml

@@ -1,54 +1,112 @@
 openapi: 3.1.0
 info:
   title: Malloy Publisher - Semantic Model Serving API
-  description:
-    The Malloy Publisher - Semantic Model Serving API serves Malloy packages.  A Malloy package is a directory of Malloy models (.malloy files),
-    Malloy notebooks (.malloynb files), and embedded datbases (.parque files) with a malloy-publisher.json manifest at the package's root directory.
-    For example, see the Malloy samples packages (https://github.com/malloydata/malloy-samples) repo.
+  description: |
+    The Malloy Publisher - Semantic Model Serving API provides comprehensive access to Malloy packages and their associated resources. 
+    A Malloy package is a directory containing Malloy models (.malloy files), Malloy notebooks (.malloynb files), and embedded databases 
+    (.parquet files) with a malloy-publisher.json manifest at the package's root directory.
+
+    ## Key Features
+
+    - **Project Management**: Create and manage projects with their associated packages and connections
+    - **Package Lifecycle**: Full CRUD operations for Malloy packages and their versions
+    - **Model & Notebook Access**: Retrieve and execute Malloy models and notebooks
+    - **Connection Management**: Secure database connection configuration and testing
+    - **Query Execution**: Execute queries against models and retrieve results
+    - **Watch Mode**: Real-time file watching for development workflows
+
+    ## Resource Hierarchy
+
+    The API follows a hierarchical resource structure:
+    ```
+    Projects
+    ├── Connections
+    ├── Packages
+    │   ├── Models
+    │   ├── Notebooks
+    │   ├── Databases
+    │   └── Schedules
+    └── Watch Mode
+    ```
+
+    For examples, see the Malloy samples packages (https://github.com/malloydata/malloy-samples) repository.
   version: v0
+
 servers:
   - url: /api/v0/
+    description: PublisherAPI server
+
+tags:
+  - name: publisher
+    description: Publisher status and health check operations
+  - name: projects
+    description: Project lifecycle management including creation, configuration, and deletion of data modeling projects
+  - name: connections
+    description: Database connection management for secure data source configuration and access
+  - name: packages
+    description: Package management for Malloy data models, including versioning and distribution
+  - name: models
+    description: Malloy model access and compilation operations
+  - name: notebooks
+    description: Malloy notebook access and execution operations
+  - name: queryresults
+    description: Query execution and result retrieval operations
+  - name: databases
+    description: Embedded database management and access
+  - name: schedules
+    description: Scheduled task management and monitoring
+  - name: watch-mode
+    description: Real-time file watching for development workflows
 
 paths:
   /status:
     get:
       tags:
-      - publisher
+        - publisher
       operationId: get-status
-      summary: Server status
+      summary: Get server status and health information
+      description: |
+        Returns the current status of the Malloy Publisher server, including initialization state,
+        available projects, and server timestamp. This endpoint is useful for health checks and
+        monitoring server availability.
       responses:
-        '200':
+        "200":
           description: Returns server status
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ServerStatus'
+                $ref: "#/components/schemas/ServerStatus"
 
   /connections/test:
     post:
       tags:
         - connections
       operationId: test-connection-configuration
-      summary: Test a connection configuration before adding it to the project
+      summary: Test database connection configuration
+      description: |
+        Validates a database connection configuration without adding it to any project.
+        This endpoint allows you to test connection parameters, credentials, and network
+        connectivity before committing the connection to a project. Useful for troubleshooting
+        connection issues and validating configurations during setup.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/Connection'
+              $ref: "#/components/schemas/Connection"
       responses:
         "200":
           description: Connection test result
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ConnectionStatus'
+                $ref: "#/components/schemas/ConnectionStatus"
         "400":
-          $ref: "#/components/responses/BadRequestError"
+          $ref: "#/components/responses/BadRequest"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -57,10 +115,14 @@ paths:
       tags:
         - projects
       operationId: list-projects
-      summary: Returns a list of the Projects hosted on this server.
+      summary: List all available projects
+      description: |
+        Retrieves a list of all projects currently hosted on this Malloy Publisher server.
+        Each project contains metadata about its packages, connections, and configuration.
+        This endpoint is typically used to discover available projects and their basic information.
       responses:
         "200":
-          description: A list of the Projects names.
+          description: A list of all available projects
           content:
             application/json:
               schema:
@@ -68,22 +130,24 @@ paths:
                 items:
                   $ref: "#/components/schemas/Project"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
     post:
       tags:
         - projects
       operationId: create-project
-      summary: Creates a new project.
+      summary: Create a new project
+      description: |
+        Creates a new Malloy project with the specified configuration. A project serves as a
+        container for packages, connections, and other resources. The project will be initialized
+        with the provided metadata and can immediately accept packages and connections.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              items:
-                $ref: '#/components/schemas/Project'
+              $ref: "#/components/schemas/Project"
       responses:
         "200":
           description: Returns the project created
@@ -92,7 +156,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Project"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -101,14 +165,18 @@ paths:
       tags:
         - projects
       operationId: get-project
-      summary: Returns metadata about the project.
+      summary: Get project details and metadata
+      description: |
+        Retrieves detailed information about a specific project, including its packages,
+        connections, configuration, and metadata. The reload parameter can be used to
+        refresh the project state from disk before returning the information.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: reload
           in: query
           description: Load / reload the project before returning result
@@ -117,37 +185,39 @@ paths:
             type: boolean
       responses:
         "200":
-          description: Metadata about the project.
+          description: Project details and metadata
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Project"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
     patch:
       tags:
         - projects
       operationId: update-project
-      summary: Updates a project.
+      summary: Update project configuration
+      description: |
+        Updates the configuration and metadata of an existing project. This allows you to
+        modify project settings, update the README, change the location, or update other
+        project-level properties. The project must exist and be accessible.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              items:
-                $ref: '#/components/schemas/Project'
+              $ref: "#/components/schemas/Project"
       responses:
         "200":
           description: Returns the project updated
@@ -156,21 +226,25 @@ paths:
               schema:
                 $ref: "#/components/schemas/Project"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
     delete:
       tags:
         - projects
       operationId: delete-project
-      summary: Deletes a project.
+      summary: Delete a project
+      description: |
+        Permanently deletes a project and all its associated resources including packages,
+        connections, and metadata. This operation cannot be undone, so use with caution.
+        The project must exist and be accessible for deletion.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
           description: Returns the project deleted
@@ -179,9 +253,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/Project"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -190,17 +264,21 @@ paths:
       tags:
         - connections
       operationId: list-connections
-      summary: Returns a list of the connections in the project.
+      summary: List project database connections
+      description: |
+        Retrieves a list of all database connections configured for the specified project.
+        Each connection includes its configuration, type, and status information. This endpoint
+        is useful for discovering available data sources within a project.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: A list of the connections in the project.
+          description: A list of database connections in the project
           content:
             application/json:
               schema:
@@ -208,7 +286,7 @@ paths:
                 items:
                   $ref: "#/components/schemas/Connection"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -217,65 +295,72 @@ paths:
       tags:
         - connections
       operationId: get-connection
-      summary: Returns a connection.
+      summary: Get connection details
+      description: |
+        Retrieves detailed information about a specific database connection within a project.
+        This includes connection configuration, credentials (if accessible), and metadata.
+        Useful for inspecting connection settings and troubleshooting connectivity issues.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: A connection.
+          description: Connection details and configuration
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Connection"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
-
   /projects/{projectName}/connections/{connectionName}/test:
     get:
       tags:
         - connections
       operationId: test-connection
-      summary: Returns a test.
+      summary: Test existing project connection
+      description: |
+        Tests the connectivity and configuration of an existing database connection within a project.
+        This endpoint validates that the connection can be established, credentials are valid,
+        and the database is accessible. Useful for monitoring connection health and troubleshooting.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
           description: OK
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ConnectionStatus'
+                $ref: "#/components/schemas/ConnectionStatus"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -285,20 +370,26 @@ paths:
         - connections
       operationId: get-sqlsource
       deprecated: true
-      summary: Returns a SQL source.
+      summary: Get SQL source (deprecated)
+      description: |
+        **DEPRECATED**: This endpoint is deprecated and may be removed in future versions.
+        Use the POST version instead for better security and functionality.
+
+        Creates a Malloy source from a SQL statement using the specified connection.
+        The SQL statement is executed to generate a source definition that can be used in Malloy models.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: sqlStatement
           in: query
           description: SQL statement
@@ -307,35 +398,40 @@ paths:
             type: string
       responses:
         "200":
-          description: A SQL source.
+          description: SQL source information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/SqlSource"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
     post:
       tags:
         - connections
       operationId: post-sqlsource
-      summary: Returns a SQL source.
+      summary: Create SQL source from statement
+      description: |
+        Creates a Malloy source from a SQL statement using the specified database connection.
+        The SQL statement is executed to generate a source definition that can be used in Malloy models.
+        This is the preferred method over the deprecated GET version as it provides better security
+        and supports larger SQL statements.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       requestBody:
         description: SQL statement to fetch the SQL source
         required: true
@@ -348,15 +444,15 @@ paths:
                   type: string
       responses:
         "200":
-          description: A SQL source.
+          description: SQL source information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/SqlSource"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -365,20 +461,24 @@ paths:
       tags:
         - connections
       operationId: get-tablesource
-      summary: Returns a table source.
+      summary: Get table source information
+      description: |
+        Retrieves information about a specific table or view from the database connection.
+        This includes table schema, column definitions, and metadata. The table can be specified
+        by either tableKey or tablePath parameters, depending on the database type.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: tableKey
           in: query
           description: Table key
@@ -393,15 +493,15 @@ paths:
             type: string
       responses:
         "200":
-          description: A table source.
+          description: Table source information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/TableSource"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -410,29 +510,33 @@ paths:
       tags:
         - connections
       operationId: list-tables
-      summary: Returns a list of tables available in the specified schema.
+      summary: List tables in database schema
+      description: |
+        Retrieves a list of all tables and views available in the specified database schema.
+        This endpoint is useful for discovering available data sources and exploring the database
+        structure. The schema must exist in the connection for this operation to succeed.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: schemaName
           in: path
-          description: Name of schema
+          description: Name of the schema
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: A list of table names available in the specified schema.
+          description: A list of table names available in the specified schema
           content:
             application/json:
               schema:
@@ -440,9 +544,9 @@ paths:
                 items:
                   type: string
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -451,23 +555,27 @@ paths:
       tags:
         - connections
       operationId: list-schemas
-      summary: Returns a list of schemas available in the connection.
+      summary: List database schemas
+      description: |
+        Retrieves a list of all schemas (databases) available in the specified connection.
+        Each schema includes metadata such as name, description, and whether it's the default schema.
+        This endpoint is useful for exploring the database structure and discovering available data sources.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: A list of schemas available in the connection with metadata.
+          description: A list of schemas available in the connection with metadata
           content:
             application/json:
               schema:
@@ -475,9 +583,9 @@ paths:
                 items:
                   $ref: "#/components/schemas/SchemaName"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -487,20 +595,26 @@ paths:
         - connections
       operationId: get-querydata
       deprecated: true
-      summary: Returns a query and its results.
+      summary: Execute SQL query (deprecated)
+      description: |
+        **DEPRECATED**: This endpoint is deprecated and may be removed in future versions.
+        Use the POST version instead for better security and functionality.
+
+        Executes a SQL statement against the specified database connection and returns the results.
+        The query results include data, metadata, and execution information.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: sqlStatement
           in: query
           description: SQL statement
@@ -515,35 +629,39 @@ paths:
             type: string
       responses:
         "200":
-          description: A query and its results.
+          description: Query execution results
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/QueryData"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
-              $ref: "#/components/responses/InternalServerError"
+          $ref: "#/components/responses/InternalServerError"
     post:
       tags:
         - connections
       operationId: post-querydata
-      summary: Returns a query and its results.
+      summary: Execute SQL query
+      description: |
+        Executes a SQL statement against the specified database connection and returns the results.
+        This is the preferred method over the deprecated GET version as it provides better security
+        and supports larger SQL statements. The results include data, metadata, and execution information.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: options
           in: query
           description: Options
@@ -562,15 +680,15 @@ paths:
                   type: string
       responses:
         "200":
-          description: A query and its results.
+          description: Query execution results
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/QueryData"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -580,20 +698,26 @@ paths:
         - connections
       operationId: get-temporarytable
       deprecated: true
-      summary: Returns a temporary table.
+      summary: Create temporary table (deprecated)
+      description: |
+        **DEPRECATED**: This endpoint is deprecated and may be removed in future versions.
+        Use the POST version instead for better security and functionality.
+
+        Creates a temporary table from a SQL statement using the specified connection.
+        Temporary tables are useful for storing intermediate results during complex queries.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: sqlStatement
           in: query
           description: SQL statement
@@ -602,35 +726,40 @@ paths:
             type: string
       responses:
         "200":
-          description: A temporary table.
+          description: Temporary table information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/TemporaryTable"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
     post:
       tags:
         - connections
       operationId: post-temporarytable
-      summary: Returns a temporary table.
+      summary: Create temporary table
+      description: |
+        Creates a temporary table from a SQL statement using the specified database connection.
+        This is the preferred method over the deprecated GET version as it provides better security
+        and supports larger SQL statements. Temporary tables are useful for storing intermediate
+        results during complex queries and data processing workflows.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: connectionName
           in: path
-          description: Name of connection
+          description: Name of the connection
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       requestBody:
         description: SQL statement to create the temporary table
         required: true
@@ -643,35 +772,38 @@ paths:
                   type: string
       responses:
         "200":
-          description: A temporary table.
+          description: Temporary table information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/TemporaryTable"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
-
   /projects/{projectName}/packages:
     get:
       tags:
         - packages
       operationId: list-packages
-      summary: Returns a list of the Packages hosted on this server.
+      summary: List project packages
+      description: |
+        Retrieves a list of all Malloy packages within the specified project. Each package
+        contains models, notebooks, databases, and other resources. This endpoint is useful
+        for discovering available packages and their basic metadata.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: A list of the Packages names.
+          description: A list of all packages in the project
           content:
             application/json:
               schema:
@@ -679,31 +811,33 @@ paths:
                 items:
                   $ref: "#/components/schemas/Package"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
     post:
       tags:
         - packages
       operationId: create-package
-      summary: Creates a new package.
+      summary: Create a new package
+      description: |
+        Creates a new Malloy package within the specified project. A package serves as a
+        container for models, notebooks, embedded databases, and other resources. The package
+        will be initialized with the provided metadata and can immediately accept content.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              items:
-                $ref: '#/components/schemas/Package'
+              $ref: "#/components/schemas/Package"
       responses:
         "200":
           description: Returns the package created
@@ -712,25 +846,30 @@ paths:
               schema:
                 $ref: "#/components/schemas/Package"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}:
     get:
       tags:
         - packages
       operationId: get-package
-      summary: Returns the package metadata.
+      summary: Get package details and metadata
+      description: |
+        Retrieves detailed information about a specific package, including its models, notebooks,
+        databases, and metadata. The reload parameter can be used to refresh the package state
+        from disk before returning the information. The versionId parameter allows access to
+        specific package versions.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
           description: Package name
@@ -739,10 +878,10 @@ paths:
             type: string
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
         - name: reload
           in: query
           description: Load / reload the package before returning result
@@ -751,45 +890,47 @@ paths:
             type: boolean
       responses:
         "200":
-          description: Package metadata.
+          description: Package details and metadata
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Package"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
     patch:
       tags:
         - packages
       operationId: update-package
-      summary: Updates a package.
+      summary: Update package configuration
+      description: |
+        Updates the configuration and metadata of an existing package. This allows you to
+        modify package settings, update the description, change the location, or update other
+        package-level properties. The package must exist and be accessible.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              items:
-                $ref: '#/components/schemas/Package'
+              $ref: "#/components/schemas/Package"
       responses:
         "200":
           description: Returns the package updated
@@ -798,31 +939,35 @@ paths:
               schema:
                 $ref: "#/components/schemas/Package"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
     delete:
       tags:
         - packages
       operationId: delete-package
-      summary: Deletes a package.
+      summary: Delete a package
+      description: |
+        Permanently deletes a package and all its associated resources including models,
+        notebooks, databases, and metadata. This operation cannot be undone, so use with caution.
+        The package must exist and be accessible for deletion.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
           description: Returns the package deleted
@@ -831,42 +976,46 @@ paths:
               schema:
                 $ref: "#/components/schemas/Package"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/models:
     get:
       tags:
         - models
       operationId: list-models
-      summary: Returns a list of relative paths to the models in the package.
+      summary: List package models
+      description: |
+        Retrieves a list of all Malloy models within the specified package. Each model entry
+        includes the relative path, package name, and any compilation errors. This endpoint
+        is useful for discovering available models and checking their status.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of relative paths to the models in the package.
+          description: A list of models in the package
           content:
             application/json:
               schema:
@@ -874,91 +1023,99 @@ paths:
                 items:
                   $ref: "#/components/schemas/Model"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/models/{path}:
     get:
       tags:
         - models
       operationId: get-model
-      summary: Returns a Malloy model.
+      summary: Get compiled Malloy model
+      description: |
+        Retrieves a compiled Malloy model with its source information, queries, and metadata.
+        The model is compiled using the specified version of the Malloy compiler. This endpoint
+        provides access to the model's structure, sources, and named queries for use in applications.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package.
+          description: Name of the package
           required: true
           schema:
             type: string
         - name: path
           in: path
-          description: Path to model wihin the package.
+          description: Path to the model within the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/PathPattern"
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A Malloy model.
+          description: Compiled Malloy model
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/CompiledModel"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "424":
           $ref: "#/components/responses/ModelCompilationError"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/notebooks:
     get:
       tags:
         - notebooks
       operationId: list-notebooks
-      summary: Returns a list of relative paths to the notebooks in the package.
+      summary: List package notebooks
+      description: |
+        Retrieves a list of all Malloy notebooks within the specified package. Each notebook entry
+        includes the relative path, package name, and any compilation errors. This endpoint
+        is useful for discovering available notebooks and checking their status.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of relative paths to the models in the package.
+          description: A list of models in the package
           content:
             application/json:
               schema:
@@ -966,45 +1123,49 @@ paths:
                 items:
                   $ref: "#/components/schemas/Notebook"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/notebooks/{path}:
     get:
       tags:
         - notebooks
       operationId: get-notebook
-      summary: Returns a Malloy notebook.
+      summary: Get compiled Malloy notebook
+      description: |
+        Retrieves a compiled Malloy notebook with its cells, results, and metadata. The notebook
+        is compiled using the specified version of the Malloy compiler. This endpoint provides
+        access to the notebook's structure, cells, and execution results for use in applications.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package.
+          description: Name of the package
           required: true
           schema:
             type: string
         - name: path
           in: path
-          description: Path to notebook wihin the package.
+          description: Path to notebook within the package.
           required: true
           schema:
             type: string
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
           description: A Malloy notebook.
@@ -1013,42 +1174,47 @@ paths:
               schema:
                 $ref: "#/components/schemas/CompiledNotebook"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/queryResults/{path}:
     get:
       tags:
         - queryresults
       operationId: execute-query
-      summary: Returns a query and its results.
+      summary: Execute Malloy query
+      description: |
+        Executes a Malloy query against a model and returns the results. The query can be specified
+        as a raw Malloy query string or by referencing a named query within the model. This endpoint
+        supports both ad-hoc queries and predefined model queries, making it flexible for various
+        use cases including data exploration, reporting, and application integration.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: path
           in: path
-          description: Path to model within the package.
+          description: Path to the model within the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/PathPattern"
         - in: query
           name: query
-          description: Query string to execute on the model.  If the query is paramter is set, the queryName parameter must be empty.
+          description: Query string to execute on the model. If the query parameter is set, the queryName parameter must be empty.
           required: false
           schema:
             type: string
@@ -1060,7 +1226,7 @@ paths:
             type: string
         - in: query
           name: queryName
-          description: Name of a query to execute on a source in the model.  Requires the sourceName parameter is set.  If the queryName is paramter is set, the query parameter must be empty.
+          description: Name of a query to execute on a source in the model. Requires the sourceName parameter is set. If the queryName parameter is set, the query parameter must be empty.
           required: false
           schema:
             type: string
@@ -1072,50 +1238,54 @@ paths:
             type: string
       responses:
         "200":
-          description: A query and its results.
+          description: Query execution results
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/QueryResult"
         "400":
-          $ref: "#/components/responses/BadRequestError"
+          $ref: "#/components/responses/BadRequest"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/databases:
     get:
       tags:
         - databases
       operationId: list-databases
-      summary: Returns a list of relative paths to the databases embedded in the package.
+      summary: List embedded databases
+      description: |
+        Retrieves a list of all embedded databases within the specified package. These are typically
+        DuckDB databases stored as .parquet files that provide local data storage for the package.
+        Each database entry includes metadata about the database structure and content.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of relative paths to the databases embedded in the package.
+          description: A list of embedded databases in the package
           content:
             application/json:
               schema:
@@ -1123,42 +1293,46 @@ paths:
                 items:
                   $ref: "#/components/schemas/Database"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/schedules:
     get:
       tags:
         - schedules
       operationId: list-schedules
-      summary: Returns a list of running schedules.
+      summary: List package schedules
+      description: |
+        Retrieves a list of all scheduled tasks associated with the specified package. These
+        schedules define automated operations such as data refresh, report generation, or other
+        recurring tasks. Each schedule includes timing information and execution status.
       parameters:
         - name: projectName
           in: path
-          description: Name of project
+          description: Name of the project
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
-          description: Name of package
+          description: Name of the package
           required: true
           schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: versionId
           in: query
-          description: Version ID
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of running schedules.
+          description: A list of scheduled tasks
           content:
             application/json:
               schema:
@@ -1166,20 +1340,24 @@ paths:
                 items:
                   $ref: "#/components/schemas/Schedule"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "404":
-          $ref: "#/components/responses/NotFoundError"
+          $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "501":
-          $ref: "#/components/responses/NotImplementedError"
+          $ref: "#/components/responses/NotImplemented"
 
   /watch-mode/status:
     get:
       tags:
         - watch-mode
       operationId: get-watch-status
-      summary: Returns the current watch mode status.
+      summary: Get watch mode status
+      description: |
+        Retrieves the current status of the file watching system. This includes whether watch mode
+        is enabled, which project is being watched, and the path being monitored. Useful for
+        monitoring the development workflow and ensuring file changes are being detected.
       responses:
         "200":
           description: The current watch mode status.
@@ -1188,7 +1366,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/WatchStatus"
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -1197,7 +1375,11 @@ paths:
       tags:
         - watch-mode
       operationId: start-watching
-      summary: Starts watching a project for file changes.
+      summary: Start file watching
+      description: |
+        Initiates file watching for the specified project. This enables real-time monitoring of
+        file changes within the project directory, allowing for automatic reloading and updates
+        during development. Only one project can be watched at a time.
       requestBody:
         required: true
         content:
@@ -1208,7 +1390,7 @@ paths:
         "200":
           description: Watch mode started successfully.
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
@@ -1217,296 +1399,325 @@ paths:
       tags:
         - watch-mode
       operationId: stop-watching
-      summary: Stops watching for file changes.
+      summary: Stop file watching
+      description: |
+        Stops the current file watching session. This disables real-time monitoring of file changes
+        and releases system resources. Use this when development is complete or when switching
+        to a different project.
       responses:
         "200":
           description: Watch mode stopped successfully.
         "401":
-          $ref: "#/components/responses/UnauthorizedError"
+          $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
 
 components:
   responses:
-    InternalServerError:
-      description: The server encountered an internal error
+    BadRequest:
+      description: The request was malformed or cannot be performed given the current state of the system
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    NotFoundError:
-      description: The specified resource was not found
+    Unauthorized:
+      description: Unauthorized - authentication required
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    NotImplementedError:
-      description: Not implemented
+    Forbidden:
+      description: Forbidden - insufficient permissions to perform the operation
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    UnauthorizedError:
-      description: Unauthorized
+    NotFound:
+      description: The specified resource was not found
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    BadRequestError:
-      description: Bad request
+    InternalServerError:
+      description: The server encountered an internal error
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    NotImplemented:
+      description: The requested operation is not implemented
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
     ModelCompilationError:
-      description: Model compilation error
+      description: Model compilation failed due to syntax or semantic errors
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
 
   schemas:
+    IdentifierPattern:
+      type: string
+      pattern: "^[a-zA-Z0-9_-]+$"
+      description: Standard identifier pattern for resource names
+
+    VersionIdPattern:
+      type: string
+      pattern: "^[a-zA-Z0-9_.-]+$"
+      description: Version identifier pattern supporting dots and dashes
+
+    PathPattern:
+      type: string
+      pattern: "^[a-zA-Z0-9_/.-]+$"
+      description: Path pattern supporting slashes, dots, and dashes
+
     ServerStatus:
       type: object
+      description: Current server status and health information
       properties:
         timestamp:
           type: number
+          description: Unix timestamp of the status check
         projects:
           type: array
+          description: List of available projects
           items:
-            $ref: '#/components/schemas/Project'
+            $ref: "#/components/schemas/Project"
         initialized:
           type: boolean
-          description: Whether the server is initialized.
+          description: Whether the server is fully initialized and ready to serve requests
 
     Project:
       type: object
+      description: Represents a Malloy project containing packages, connections, and other resources
       properties:
         resource:
           type: string
-          description: Resource path to the project.
+          description: Resource path to the project
         name:
           type: string
-          description: Project name.
+          description: Project name
         readme:
           type: string
-          description: Project readme.
+          description: Project README content
         location:
           type: string
-          description: Project location, it can be an absolute path or an URI (e.g. github, s3, gcs, etc.).
+          description: Project location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)
         connections:
           type: array
+          description: List of database connections configured for this project
           items:
-            $ref: '#/components/schemas/Connection'
+            $ref: "#/components/schemas/Connection"
         packages:
           type: array
+          description: List of Malloy packages in this project
           items:
-            $ref: '#/components/schemas/Package'
+            $ref: "#/components/schemas/Package"
 
     Package:
       type: object
+      description: Represents a Malloy package containing models, notebooks, and embedded databases
       properties:
         resource:
           type: string
-          description: Resource path to the package.
+          description: Resource path to the package
         name:
           type: string
-          description: Package name.
+          description: Package name
         description:
           type: string
-          description: Package description.
+          description: Package description
         location:
           type: string
-          description: Package location, it can be an absolute path or an URI (e.g. github, s3, gcs, etc.).
+          description: Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)
 
     Model:
       type: object
-      description: Malloy Model metadata
+      description: Malloy model metadata and status information
       properties:
         resource:
           type: string
-          description: Resource path to the model.
+          description: Resource path to the model
         packageName:
           type: string
-          description: Model's package Name
+          description: Name of the package containing this model
         path:
           type: string
-          description: Model's relative path in its package directory.
+          description: Relative path to the model file within its package directory
         error:
           type: string
-          description: Error message for this model object.
+          description: Error message if the model failed to compile or load
 
     Notebook:
       type: object
-      description: Malloy Notebook metadata
+      description: Malloy notebook metadata and status information
       properties:
         resource:
           type: string
-          description: Resource path to the notebook.
+          description: Resource path to the notebook
         packageName:
           type: string
-          description: Notebook's package Name
+          description: Name of the package containing this notebook
         path:
           type: string
-          description: Notebook's relative path in its package directory.
+          description: Relative path to the notebook file within its package directory
         error:
           type: string
-          description: Error message for this notebook object.
+          description: Error message if the notebook failed to compile or load
 
     CompiledNotebook:
       type: object
-      description: Malloy notebook def and result data.  Malloy notebook def and result data is Malloy version depdendent.
+      description: Compiled Malloy notebook with cells, results, and execution data
       properties:
         resource:
           type: string
-          description: Resource path to the notebook.
+          description: Resource path to the notebook
         packageName:
           type: string
-          description: Notebook's package Name
+          description: Name of the package containing this notebook
         path:
           type: string
-          description: Notebook's relative path in its package directory.
+          description: Relative path to the notebook file within its package directory
         malloyVersion:
           type: string
-          description: Version of the Malloy compiler that generated the notebook def and results fields.
+          description: Version of the Malloy compiler used to generate the notebook data
         notebookCells:
           type: array
-          description: Array of notebook cells.
+          description: Array of notebook cells containing code, markdown, and execution results
           items:
             $ref: "#/components/schemas/NotebookCell"
 
     CompiledModel:
       type: object
-      description: Malloy model def and result data.  Malloy model def and result data is Malloy version depdendent.
+      description: Compiled Malloy model with sources, queries, and metadata
       properties:
         resource:
           type: string
-          description: Resource path to the model.
+          description: Resource path to the model
         packageName:
           type: string
-          description: Model's package Name
+          description: Name of the package containing this model
         path:
           type: string
-          description: Model's relative path in its package directory.
+          description: Relative path to the model file within its package directory
         malloyVersion:
           type: string
-          description: Version of the Malloy compiler that generated the model def and results fields.
+          description: Version of the Malloy compiler used to generate the model data
         modelInfo:
           type: string
-          description: JSON string of ModelInfo. See malloy/packages/malloy-interfaces/src/types.ts
+          description: JSON string containing model metadata and structure information
         sourceInfos:
           type: array
-          description: Array of JSON string of SourceInfo. See malloy/packages/malloy-interfaces/src/types.ts
+          description: Array of JSON strings containing source information for each data source
           items:
             type: string
         queries:
           type: array
-          descript: Array of named queries.
+          description: Array of named queries defined in the model
           items:
             $ref: "#/components/schemas/Query"
 
     View:
       type: object
-      description: Named model view.
+      description: Named model view definition
       properties:
         name:
           type: string
-          description: View's name.
+          description: Name of the view
         annotations:
           type: array
-          description: Annotations attached to view.
+          description: Annotations attached to the view
           items:
             type: string
 
     Query:
       type: object
-      description: Named model query.
+      description: Named model query definition
       properties:
         name:
           type: string
-          description: Query's name.
+          description: Name of the query
         sourceName:
           type: string
-          description: Source name.
+          description: Name of the source this query operates on
         annotations:
           type: array
-          description: Annotations attached to query.
+          description: Annotations attached to the query
           items:
             type: string
 
     NotebookCell:
       type: object
-      description: Notebook cell.
+      description: Individual cell within a Malloy notebook
       properties:
         type:
           type: string
           enum: ["markdown", "code"]
-          description: Type of notebook cell.
+          description: Type of notebook cell
         text:
           type: string
-          description: Text contents of the notebook cell.
+          description: Text contents of the notebook cell
         result:
           type: string
-          description: JSON string of Malloy.Result. See malloy/packages/malloy-interfaces/src/types.ts
+          description: JSON string containing the execution result for this cell
         newSources:
           type: array
-          description:
-            Array of JSON string of SourceInfo made available in the notebook cell. Only *new*
-            SourceInfos are returned. The complete list of SourceInfos is available be concatenating the prior
-            notebook cells.  The SourceInfos are in the order they are made available in the notebook cell.
+          description: Array of JSON strings containing SourceInfo objects made available in this cell
           items:
             type: string
 
     QueryResult:
       type: object
-      description: A Malloy query's results.
+      description: Results from executing a Malloy query
       properties:
         result:
           type: string
-          description: JSON string of Malloy.Result. See malloy/packages/malloy-interfaces/src/types.ts
+          description: JSON string containing the query results, metadata, and execution information
         resource:
           type: string
-          description: Resource path to the query result.
+          description: Resource path to the query result
 
     Database:
       type: object
-      description: An in-memory DuckDB database embedded in the package.
+      description: Embedded database within a Malloy package
       properties:
         resource:
           type: string
-          description: Resource path to the database.
+          description: Resource path to the database
         path:
           type: string
-          description: Database's relative path in its package directory.
+          description: Relative path to the database file within its package directory
         info:
           $ref: "#/components/schemas/TableDescription"
         type:
           type: string
+          description: Type of embedded database
           enum: ["embedded", "materialized"]
-          description: Type of database.
 
     Schedule:
       type: object
-      description: A scheduled task.
+      description: Scheduled task configuration and status
       properties:
         resource:
           type: string
-          description: Resource in the package that the schedule is attached to.
+          description: Resource path in the package that the schedule is attached to
         schedule:
           type: string
-          description: Schedule (cron format) for executing task.
+          description: Schedule expression in cron format for executing the task
         action:
           type: string
-          description: Action to execute.
+          description: Action to execute when the schedule triggers
         connection:
           type: string
-          description: Connection to perform action on.
+          description: Name of the connection to perform the action on
         lastRunTime:
           type: number
-          description: Timestamp in milliseconds of the last run.
+          description: Unix timestamp in milliseconds of the last execution
         lastRunStatus:
           type: string
-          description: Status of the last run.
+          description: Status of the last execution
 
     SchemaName:
       description: A schema name in a Connection.
@@ -1527,14 +1738,17 @@ components:
 
     Connection:
       type: object
+      description: Database connection configuration and metadata
       properties:
         resource:
           type: string
-          description: Resource path to the connection.
+          description: Resource path to the connection
         name:
           type: string
+          description: Name of the connection
         type:
           type: string
+          description: Type of database connection
           enum: [postgres, bigquery, snowflake, trino, mysql]
         attributes:
           $ref: "#/components/schemas/ConnectionAttributes"
@@ -1551,95 +1765,138 @@ components:
 
     ConnectionAttributes:
       type: object
+      description: Connection capabilities and configuration attributes
       properties:
         dialectName:
           type: string
+          description: SQL dialect name for the connection
         isPool:
           type: boolean
+          description: Whether the connection uses connection pooling
         canPersist:
           type: boolean
+          description: Whether the connection supports persistent storage operations
         canStream:
           type: boolean
+          description: Whether the connection supports streaming query results
 
     PostgresConnection:
       type: object
+      description: PostgreSQL database connection configuration
       properties:
         host:
           type: string
+          description: PostgreSQL server hostname or IP address
         port:
           type: integer
+          description: PostgreSQL server port number
         databaseName:
           type: string
+          description: Name of the PostgreSQL database
         userName:
           type: string
+          description: PostgreSQL username for authentication
         password:
           type: string
+          description: PostgreSQL password for authentication
         connectionString:
           type: string
+          description: Complete PostgreSQL connection string (alternative to individual parameters)
 
     MysqlConnection:
       type: object
+      description: MySQL database connection configuration
       properties:
         host:
           type: string
+          description: MySQL server hostname or IP address
         port:
           type: integer
+          description: MySQL server port number
         database:
           type: string
+          description: Name of the MySQL database
         user:
           type: string
+          description: MySQL username for authentication
         password:
           type: string
+          description: MySQL password for authentication
 
     BigqueryConnection:
       type: object
+      description: Google BigQuery database connection configuration
       properties:
         defaultProjectId:
           type: string
+          description: Default BigQuery project ID for queries
         billingProjectId:
           type: string
+          description: BigQuery project ID for billing purposes
         location:
           type: string
+          description: BigQuery dataset location/region
         serviceAccountKeyJson:
           type: string
+          description: JSON string containing Google Cloud service account credentials
         maximumBytesBilled:
           type: string
+          description: Maximum bytes to bill for query execution (prevents runaway costs)
         queryTimeoutMilliseconds:
           type: string
+          description: Query timeout in milliseconds
 
     SnowflakeConnection:
       type: object
+      description: Snowflake database connection configuration
       properties:
         account:
           type: string
+          description: Snowflake account identifier
         username:
           type: string
+          description: Snowflake username for authentication
         password:
           type: string
+          description: Snowflake password for authentication
         warehouse:
           type: string
+          description: Snowflake warehouse name
         database:
           type: string
+          description: Snowflake database name
         schema:
           type: string
+          description: Snowflake schema name
+        role:
+          type: string
+          description: Snowflake role name
         responseTimeoutMilliseconds:
           type: integer
+          description: Query response timeout in milliseconds
 
     TrinoConnection:
       type: object
+      description: Trino database connection configuration
       properties:
         server:
           type: string
+          description: Trino server hostname or IP address
         port:
           type: number
+          description: Trino server port number
         catalog:
           type: string
+          description: Trino catalog name
         schema:
           type: string
+          description: Trino schema name
         user:
           type: string
+          description: Trino username for authentication
         password:
           type: string
+          description: Trino password for authentication
 
     SqlSource:
       type: object
@@ -1647,7 +1904,7 @@ components:
         resource:
           type: string
           description: Resource path to the sql source.
-        # Pass source as an opaque JSON string that is malloyVersion depdendent.
+        # Pass source as an opaque JSON string that is malloyVersion dependent.
         source:
           type: string
 
@@ -1657,7 +1914,7 @@ components:
         resource:
           type: string
           description: Resource path to the table source.
-        # Pass source as an opaque JSON string that is malloyVersion depdendent.
+        # Pass source as an opaque JSON string that is malloyVersion dependent.
         # TODO: Remove this once we update the Malloy Publisher connection.
         source:
           type: string
@@ -1673,7 +1930,7 @@ components:
         resource:
           type: string
           description: Resource path to the temporary table.
-        # Pass table as an opaque JSON string that is malloyVersion depdendent.
+        # Pass table as an opaque JSON string that is malloyVersion dependent.
         table:
           type: string
 
@@ -1683,68 +1940,83 @@ components:
         resource:
           type: string
           description: Resource path to the query data.
-        # Pass result as an opaque JSON string that is malloyVersion depdendent.
+        # Pass result as an opaque JSON string that is malloyVersion dependent.
         data:
           type: string
 
     Error:
       type: object
+      description: Standard error response format
       properties:
-        code:
-          type: integer
         message:
           type: string
+          description: Human-readable error message describing what went wrong
+        details:
+          type: string
+          description: Additional error details or context
+      required:
+        - message
 
     Column:
       type: object
+      description: Database column definition
       properties:
         name:
           type: string
+          description: Name of the column
         type:
           type: string
+          description: Data type of the column
 
     TableDescription:
       type: object
+      description: Database table structure and metadata
       properties:
         name:
           type: string
+          description: Name of the table
         rowCount:
           type: integer
+          description: Number of rows in the table
         columns:
           type: array
+          description: List of columns in the table
           items:
             $ref: "#/components/schemas/Column"
 
     WatchStatus:
       type: object
-      description: Current watch mode status
+      description: Current file watching status and configuration
       properties:
         enabled:
           type: boolean
-          description: Whether watch mode is currently enabled
+          description: Whether file watching is currently active
         projectName:
           type: string
-          description: Name of the project being watched
+          description: Name of the project being watched for file changes
         watchingPath:
           type: string
           nullable: true
-          description: The path being watched, null if not watching
+          description: The file system path being monitored for changes, null if not watching
 
     StartWatchRequest:
       type: object
-      description: Request to start watching a project
+      description: Request to start file watching for a project
       properties:
         projectName:
           type: string
-          description: Name of the project to watch
+          description: Name of the project to start watching for file changes
       required:
         - projectName
 
     ConnectionStatus:
-        type: object
-        properties:
-          status:
-            type: string
-            enum: ["ok", "failed"]
-          errorMessage:
-            type: string
+      type: object
+      description: Result of testing a database connection
+      properties:
+        status:
+          type: string
+          description: Connection test result status
+          enum: ["ok", "failed"]
+        errorMessage:
+          type: string
+          description: Error message if the connection test failed, null if successful