@malloydata/db-publisher 0.0.314 → 0.0.316

package/publisher-api-doc.yaml

@@ -1,179 +1,454 @@
 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
+    ```
+
+    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: databases
+    description: Embedded database management and access
+  - name: watch-mode
+    description: Real-time file watching for development workflows
 
 paths:
+  /status:
+    get:
+      tags:
+        - publisher
+      operationId: get-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":
+          description: Returns server status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ServerStatus"
+
   /projects:
     get:
       tags:
-      - projects
+        - 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.
+        "200":
+          description: A list of all available projects
           content:
             application/json:
               schema:
                 type: array
                 items:
                   $ref: "#/components/schemas/Project"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    post:
+      tags:
+        - projects
+      operationId: create-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:
+              $ref: "#/components/schemas/Project"
+      responses:
+        "200":
+          description: Returns the project created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
-  /projects/{projectName}/about:
+  /projects/{projectName}:
     get:
       tags:
-      - about:
-      operationId: about
-      summary:
-        Returns metadata about the publisher service.
+        - projects
+      operationId: get-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
+          required: false
+          schema:
+            type: boolean
       responses:
-        200:
-          description:
-            Metadata about the publisher service.
+        "200":
+          description: Project details and metadata
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/About"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        500:
+                $ref: "#/components/schemas/Project"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    patch:
+      tags:
+        - projects
+      operationId: update-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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Project"
+      responses:
+        "200":
+          description: Returns the project updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    delete:
+      tags:
+        - projects
+      operationId: delete-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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: Returns the project deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
   /projects/{projectName}/connections:
     get:
       tags:
-      - connections
+        - 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.
+        "200":
+          description: A list of database connections in the project
           content:
             application/json:
               schema:
                 type: array
                 items:
                   $ref: "#/components/schemas/Connection"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-  
+
   /projects/{projectName}/connections/{connectionName}:
     get:
       tags:
-      - connections
+        - 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.
+        "200":
+          description: Connection details and configuration
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Connection"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
-  /projects/{projectName}/connections/{connectionName}/test:
+  /projects/{projectName}/connections/{connectionName}/schemas:
     get:
       tags:
-      - connections
-      operationId: get-test
-      summary:
-        Returns a test.
+        - connections
+      operationId: list-schemas
+      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
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Schema"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  /projects/{projectName}/connections/{connectionName}/schemas/{schemaName}/tables:
+    get:
+      tags:
+        - connections
+      operationId: list-tables
+      summary: List tables in database
+      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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: schemaName
+          in: path
+          description: Name of the schema
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: A list of table names available in the specified schema
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Table"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  /projects/{projectName}/connections/{connectionName}/schemas/{schemaName}/tables/{tablePath}:
+    get:
+      tags:
+        - connections
+      operationId: get-table
+      summary: Get table details from database
+      description: |
+        Retrieves a table from 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.
+        The tablePath is the full path to the table, including the schema name.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: schemaName
+          in: path
+          description: Name of the schema
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: tablePath
+          in: path
+          description: Full path to the table
+          required: true
+          schema:
+            $ref: "#/components/schemas/PathPattern"
       responses:
-        200:
-          description:
-            Test passed.
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "200":
+          description: Table information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Table"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
+  # TODO: Remove this endpoint.
   /projects/{projectName}/connections/{connectionName}/sqlSource:
     get:
       tags:
-      - connections
+        - connections
       operationId: get-sqlsource
-      summary:
-        Returns a SQL source.
+      deprecated: true
+      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
@@ -181,201 +456,398 @@ paths:
           schema:
             type: string
       responses:
-        200:
-          description:
-            A SQL source.
+        "200":
+          description: SQL source information
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/SqlSource"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-  
-  /projects/{projectName}/connections/{connectionName}/tableSource:
-    get:
+
+    post:
       tags:
-      - connections
-      operationId: get-tablesource
-      summary:
-        Returns a table source.
+        - connections
+      operationId: post-sqlsource
+      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.
       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
-        - name: tableKey
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        description: SQL statement to fetch the SQL source
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sqlStatement:
+                  type: string
+      responses:
+        "200":
+          description: SQL source information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SqlSource"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  /projects/{projectName}/connections/{connectionName}/sqlQuery:
+    post:
+      tags:
+        - connections
+      operationId: post-querydata
+      summary: Execute SQL query
+      description: |
+        Executes a SQL statement against the specified database connection and returns the results.
+        The results include data, metadata, and execution information.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: options
           in: query
-          description: Table key
+          description: Options
           required: false
           schema:
             type: string
-        - name: tablePath
+      requestBody:
+        description: SQL statement to execute
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sqlStatement:
+                  type: string
+      responses:
+        "200":
+          description: Query execution results
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QueryData"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /projects/{projectName}/connections/{connectionName}/sqlTemporaryTable:
+    post:
+      tags:
+        - connections
+      operationId: post-temporarytable
+      summary: Create temporary table
+      description: |
+        Creates a temporary table from a SQL statement using the specified database connection.
+        Temporary tables are useful for storing intermediate results during complex queries and data processing workflows.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        description: SQL statement to create the temporary table
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sqlStatement:
+                  type: string
+      responses:
+        "200":
+          description: Temporary table information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TemporaryTable"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  # TODO: Remove this endpoint.
+  /projects/{projectName}/connections/{connectionName}/temporaryTable:
+    get:
+      tags:
+        - connections
+      operationId: get-temporarytable
+      deprecated: true
+      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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: sqlStatement
           in: query
-          description: Table path
+          description: SQL statement
           required: false
           schema:
             type: string
       responses:
-        200:
-          description:
-            A table source.
+        "200":
+          description: Temporary table information
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/TableSource"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                $ref: "#/components/schemas/TemporaryTable"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
-  /projects/{projectName}/connections/{connectionName}/queryData:
+  # TODO: Remove this endpoint. This is deprecated and replaced by /projects/{projectName}/connections/{connectionName}/table resource.
+  /projects/{projectName}/connections/{connectionName}/tableSource:
     get:
       tags:
-      - connections
-      operationId: get-querydata
-      summary:
-        Returns a query and its results.
+        - connections
+      operationId: get-tablesource
+      summary: Get table source information
+      deprecated: true
+      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
-        - name: sqlStatement
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: tableKey
           in: query
-          description: SQL statement
+          description: Table key
           required: false
           schema:
             type: string
-        - name: options
+        - name: tablePath
           in: query
-          description: Options
+          description: Table path
           required: false
           schema:
             type: string
       responses:
-        200:
-          description:
-            A query and its results.
+        "200":
+          description: Table source information
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/QueryData"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                $ref: "#/components/schemas/TableSource"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
 
-  /projects/{projectName}/connections/{connectionName}/temporaryTable:
+  # TODO: Remove this endpoint.
+  /projects/{projectName}/connections/{connectionName}/queryData:
     get:
       tags:
-      - connections
-      operationId: get-temporarytable
-      summary:
-        Returns a temporary table.
+        - connections
+      operationId: get-querydata
+      deprecated: true
+      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
           required: false
           schema:
             type: string
+        - name: options
+          in: query
+          description: Options
+          required: false
+          schema:
+            type: string
       responses:
-        200:
-          description:
-            A temporary table.
+        "200":
+          description: Query execution results
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/TemporaryTable"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                $ref: "#/components/schemas/QueryData"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-          
 
   /projects/{projectName}/packages:
     get:
       tags:
-      - packages
+        - 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.
+        "200":
+          description: A list of all packages in the project
           content:
             application/json:
               schema:
                 type: array
                 items:
                   $ref: "#/components/schemas/Package"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    post:
+      tags:
+        - packages
+      operationId: create-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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Package"
+      responses:
+        "200":
+          description: Returns the package created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Package"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}:
     get:
       tags:
-      - packages
+        - 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
@@ -384,521 +856,843 @@ 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
+          required: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Package details and metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Package"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    patch:
+      tags:
+        - packages
+      operationId: update-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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Package"
       responses:
-        200:
-          description:
-            Package metadata.
+        "200":
+          description: Returns the package updated
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Package"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    delete:
+      tags:
+        - packages
+      operationId: delete-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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: Returns the package deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Package"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/models:
     get:
       tags:
-      - models
+        - 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.
+        "200":
+          description: A list of models in the package
           content:
             application/json:
               schema:
                 type: array
-                items: 
+                items:
                   $ref: "#/components/schemas/Model"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
 
   /projects/{projectName}/packages/{packageName}/models/{path}:
     get:
       tags:
-      - models
+        - 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 identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: Compiled Malloy model
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/CompiledModel"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "424":
+          $ref: "#/components/responses/ModelCompilationError"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
+  /projects/{projectName}/packages/{packageName}/models/{path}/query:
+    post:
+      tags:
+        - models
+      operationId: execute-query-model
+      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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: path
+          in: path
+          description: Path to the model within the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/PathPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryRequest"
+      responses:
+        "200":
+          description: Query execution results
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/QueryResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
+  /projects/{projectName}/packages/{packageName}/notebooks:
+    get:
+      tags:
+        - notebooks
+      operationId: list-notebooks
+      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 the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $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 Malloy model.
+        "200":
+          description: A list of models in the package
           content:
-            "application/json":
+            application/json:
               schema:
-                $ref: "#/components/schemas/CompiledModel"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Notebook"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
 
-  /projects/{projectName}/packages/{packageName}/queryResults/{path}:
+  # TODO: Notebooks should return the notebook file content, not the compiled notebook.  The front end shoould
+  # run the individual notebook cells against the backend.
+  /projects/{projectName}/packages/{packageName}/notebooks/{path}:
     get:
       tags:
-      - queryresults
-      operationId: execute-query
-      summary: 
-        Returns a query and its results.
+        - notebooks
+      operationId: get-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 model within the package.
+          description: Path to notebook within the package.
           required: true
           schema:
             type: string
-        - 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.
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: sourceName
-          description: Name of the source in the model to use for queryName, search, and topValue requests.
-          required: false
-          schema:
-            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.
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: versionId
-          description: Version ID
+        - name: versionId
+          in: query
+          description: Version identifier for the package
           required: false
           schema:
-            type: string
+            $ref: "#/components/schemas/VersionIdPattern"
       responses:
-        200:
-          description:
-            A query and its results.
+        "200":
+          description: A Malloy notebook.
           content:
             "application/json":
               schema:
-                $ref: "#/components/schemas/QueryResult"
-        400:
-          $ref: "#/components/responses/BadRequestError"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                $ref: "#/components/schemas/CompiledNotebook"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
 
   /projects/{projectName}/packages/{packageName}/databases:
     get:
       tags:
-      - databases
+        - 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.
+        "200":
+          description: A list of embedded databases in the package
           content:
             application/json:
               schema:
                 type: array
-                items: 
+                items:
                   $ref: "#/components/schemas/Database"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
+  /connections/test:
+    post:
+      tags:
+        - connectionsTest
+      operationId: test-connection-configuration
+      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'
+      responses:
+        "200":
+          description: Connection test result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ConnectionStatus'
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
-  
-  /projects/{projectName}/packages/{packageName}/schedules:
+
+  /watch-mode/status:
     get:
       tags:
-      - schedules
-      operationId: list-schedules
-      summary: 
-        Returns a list of running schedules.
-      parameters:
-        - name: projectName
-          in: path
-          description: Name of project
-          required: true
-          schema:
-            type: string
-        - name: packageName
-          in: path
-          description: Name of package
-          required: true
-          schema:
-            type: string
-        - name: versionId
-          in: query
-          description: Version ID
-          required: false
-          schema:
-            type: string
+        - watch-mode
+      operationId: get-watch-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:
-            A list of running schedules.
+        "200":
+          description: The current watch mode status.
           content:
             application/json:
               schema:
-                type: array
-                items: 
-                  $ref: "#/components/schemas/Schedule"
-        401:
-          $ref: "#/components/responses/UnauthorizedError"
-        404:
-          $ref: "#/components/responses/NotFoundError"
-        500:
+                $ref: "#/components/schemas/WatchStatus"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  /watch-mode/start:
+    post:
+      tags:
+        - watch-mode
+      operationId: start-watching
+      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:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StartWatchRequest"
+      responses:
+        "200":
+          description: Watch mode started successfully.
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
+  /watch-mode/stop:
+    post:
+      tags:
+        - watch-mode
+      operationId: stop-watching
+      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/Unauthorized"
+        "500":
           $ref: "#/components/responses/InternalServerError"
-        501:
-          $ref: "#/components/responses/NotImplementedError"
 
 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"
+    Unauthorized:
+      description: Unauthorized - authentication required
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    Forbidden:
+      description: Forbidden - insufficient permissions to perform the operation
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    NotFoundError:
+    NotFound:
       description: The specified resource was not found
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    NotImplementedError:
-      description:  Not implemented
+    InternalServerError:
+      description: The server encountered an internal error
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    UnauthorizedError:
-      description: Unauthorized
+    NotImplemented:
+      description: The requested operation is not implemented
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    BadRequestError:
-      description: Bad request
+    ModelCompilationError:
+      description: Model compilation failed due to syntax or semantic errors
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
 
   schemas:
-    About:
+    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:
-        readme:
-          type: string
-          description: Readme markdown.
-  
+        timestamp:
+          type: number
+          description: Unix timestamp of the status check
+        projects:
+          type: array
+          description: List of available projects
+          items:
+            $ref: "#/components/schemas/Project"
+        initialized:
+          type: boolean
+          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
         name:
           type: string
-          description: Project name.
-    
+          description: Project name
+        readme:
+          type: string
+          description: Project README content
+        location:
+          type: string
+          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"
+        packages:
+          type: array
+          description: List of Malloy packages in this project
+          items:
+            $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
         name:
           type: string
-          description: Package name.
+          description: Package name
         description:
           type: string
-          description: Package description.
+          description: Package description
+        location:
+          type: string
+          description: Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)
 
     Model:
       type: object
-      description: Malloy model def and result data.  Malloy model def and result data is Malloy version depdendent.
+      description: Malloy model metadata and status information
       properties:
+        resource:
+          type: string
+          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.
-        type:
+          description: Relative path to the model file within its package directory
+        error:
           type: string
-          enum: ["source", "notebook"]
-          description: Type of malloy model file -- source file or notebook file.
-  
-    CompiledModel:
+          description: Error message if the model failed to compile or load
+
+    Notebook:
       type: object
-      description: Malloy model def and result data.  Malloy model def and result data is Malloy version depdendent.
+      description: Malloy notebook metadata and status information
       properties:
+        resource:
+          type: string
+          description: Resource path to the notebook
         packageName:
           type: string
-          description: Model's package Name
+          description: Name of the package containing this notebook
         path:
           type: string
-          description: Model's relative path in its package directory.
-        type:
+          description: Relative path to the notebook file within its package directory
+        error:
           type: string
-          enum: ["source", "notebook"]
-          description: Type of malloy model file -- source file or notebook file.
-        malloyVersion:
+          description: Error message if the notebook failed to compile or load
+
+    CompiledNotebook:
+      type: object
+      description: Compiled Malloy notebook with cells, results, and execution data
+      properties:
+        resource:
           type: string
-          description: Version of the Malloy compiler that generated the model def and results fields.
-        # Pass data styles as an opaque JSON string that is malloyVersion depdendent.
-        dataStyles:
+          description: Resource path to the notebook
+        packageName:
           type: string
-          description: Data style for rendering query results.
-        # Pass model def as an opaque JSON string that is malloyVersion depdendent.
-        modelDef:
+          description: Name of the package containing this notebook
+        path:
           type: string
-          description: Malloy model def.
-        sources:
-          type: array
-          description: Array of model sources.
-          items:
-            $ref: "#/components/schemas/Source"
-        queries:
-          type: array
-          descript: Array of named queries.
-          items:
-            $ref: "#/components/schemas/Query"
+          description: Relative path to the notebook file within its package directory
+        malloyVersion:
+          type: string
+          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"
-  
-    Source:
+
+    CompiledModel:
       type: object
-      description: Model source.
+      description: Compiled Malloy model with sources, queries, and metadata
       properties:
-        name:
+        resource:
           type: string
-          description: Source's name.
-        annotations:
+          description: Resource path to the model
+        packageName:
+          type: string
+          description: Name of the package containing this model
+        path:
+          type: string
+          description: Relative path to the model file within its package directory
+        malloyVersion:
+          type: string
+          description: Version of the Malloy compiler used to generate the model data
+        modelInfo:
+          type: string
+          description: JSON string containing model metadata and structure information
+        sourceInfos:
           type: array
-          description: Annotations attached to source.
+          description: Array of JSON strings containing source information for each data source
           items:
             type: string
-        views:
+        queries:
           type: array
-          description: List of views in the source.\
+          description: Array of named queries defined in the model
           items:
-            $ref: "#/components/schemas/View"
+            $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: 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
 
+    QueryRequest:
+      type: object
+      description: Request body for executing a Malloy query
+      properties:
+        query:
+          type: string
+          description: Query string to execute on the model. If the query parameter is set, the queryName parameter must be empty.
+        sourceName:
+          type: string
+          description: Name of the source in the model to use for queryName, search, and topValue requests.
+        queryName:
+          type: string
+          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.
+        versionId:
+          type: string
+          description: Version ID
+
     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.
-        queryName:
-          type: string
-          description: Name of query, if this is a named query.  Otherwise, empty.
-        # Pass data styles as an opaque JSON string that is malloyVersion depdendent.
-        queryResult:
+          description: Text contents of the notebook cell
+        result:
           type: string
-          description: Malloy query results. Populated only if a code cell.
-  
+          description: JSON string containing the execution result for this cell
+        newSources:
+          type: array
+          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, its model def, and its data styles.
+      description: Results from executing a Malloy query
       properties:
-        # Pass data styles as an opaque JSON string that is malloyVersion depdendent.
-        dataStyles:
-          type: string
-          description: Data style for rendering query results.
-        # Pass model def as an opaque JSON string that is malloyVersion depdendent.
-        modelDef:
+        result:
           type: string
-          description: Malloy model def.
-        # Pass data styles as an opaque JSON string that is malloyVersion depdendent.
-        queryResult:
+          description: JSON string containing the query results, metadata, and execution information
+        resource:
           type: string
-          description: Malloy query results. Populated only if a code cell.
+          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
         path:
           type: string
-          description: Database's relative path in its package directory.
-        size:
-          type: integer
-          description: Size of the embedded database in bytes.
+          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:
+    Schema:
+      description: A schema name in a Connection.
       type: object
-      description: A scheduled task.
       properties:
-        resource:
-          type: string
-          description: Resource in the package that the schedule is attached to.
-        schedule:
-          type: string
-          description: Schedule (cron format) for executing task.
-        action:
-          type: string
-          description: Action to execute.
-        connection:
+        name:
           type: string
-          description: Connection to perform action on.
-        lastRunTime:
-          type: number
-          description: Timestamp in milliseconds of the last run.
-        lastRunStatus:
+          description: Name of the schema
+        description:
           type: string
-          description: Status of the last run.
+          description: Description of the schema
+        isDefault:
+          type: boolean
+          description: Whether this schema is the default schema
+        isHidden:
+          type: boolean
+          description: Whether this schema is hidden
 
     Connection:
       type: object
+      description: Database connection configuration and metadata
       properties:
+        resource:
+          type: string
+          description: Resource path to the connection
         name:
           type: string
+          description: Name of the connection
         type:
           type: string
-          enum: [postgres, bigquery, snowflake, trino]
+          description: Type of database connection
+          enum: [postgres, bigquery, snowflake, trino, mysql, duckdb]
         attributes:
           $ref: "#/components/schemas/ConnectionAttributes"
         postgresConnection:
@@ -909,118 +1703,309 @@ components:
           $ref: "#/components/schemas/SnowflakeConnection"
         trinoConnection:
           $ref: "#/components/schemas/TrinoConnection"
+        mysqlConnection:
+          $ref: "#/components/schemas/MysqlConnection"
+        duckdbConnection:
+          $ref: "#/components/schemas/DuckdbConnection"
 
     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   
+          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
+
+    DuckdbConnection:
+      type: object
+      description: DuckDB database connection configuration
+      properties:
+        attachedDatabases:
+          array:
+            $ref: "#/components/schemas/AttachedDatabase"
+
+    AttachedDatabase:
+      type: object
+      description: Attached DuckDB database
+      properties:
+        name:
+          type: string
+          description: Name of the connection
+        type:
+          type: string
+          description: Type of database connection
+          enum: [bigquery, snowflake, postgres]
+        attributes:
+          $ref: "#/components/schemas/ConnectionAttributes"
+        bigqueryConnection:
+          $ref: "#/components/schemas/BigqueryConnection"
+        snowflakeConnection:
+          $ref: "#/components/schemas/SnowflakeConnection"
+        postgresConnection:
+          $ref: "#/components/schemas/PostgresConnection"
+
 
+    # TODO: What is this?  Can we remove it?
     SqlSource:
       type: object
       properties:
-        # Pass source as an opaque JSON string that is malloyVersion depdendent.
+        resource:
+          type: string
+          description: Resource path to the sql source.
+        # Pass source as an opaque JSON string that is malloyVersion dependent.
         source:
           type: string
-    
+
+    Table:
+      type: object
+      properties:
+        resource:
+          type: string
+          description: Resource path to the table.
+        columns:
+          description: Table fields
+          type: array
+          items:
+            $ref: "#/components/schemas/Column"
+
+    # TODO: Remove this. Replaced by Table
     TableSource:
       type: object
+      deprecated: true
       properties:
-        # Pass source as an opaque JSON string that is malloyVersion depdendent.
+        resource:
+          type: string
+          description: Resource path to the table source.
+        # Pass source as an opaque JSON string that is malloyVersion dependent.
+        # TODO: Remove this once we update the Malloy Publisher connection.
         source:
           type: string
+        columns:
+          description: Table fields
+          type: array
+          items:
+            $ref: "#/components/schemas/Column"
 
     TemporaryTable:
       type: object
       properties:
-        # Pass table as an opaque JSON string that is malloyVersion depdendent.
+        resource:
+          type: string
+          description: Resource path to the temporary table.
+        # Pass table as an opaque JSON string that is malloyVersion dependent.
         table:
           type: string
 
     QueryData:
       type: object
       properties:
-        # Pass result as an opaque JSON string that is malloyVersion depdendent.
+        resource:
+          type: string
+          description: Resource path to the query data.
+        # 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: string
         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 file watching status and configuration
+      properties:
+        enabled:
+          type: boolean
+          description: Whether file watching is currently active
+        projectName:
+          type: string
+          description: Name of the project being watched for file changes
+        watchingPath:
+          type: string
+          nullable: true
+          description: The file system path being monitored for changes, null if not watching
+
+    StartWatchRequest:
+      type: object
+      description: Request to start file watching for a project
+      properties:
+        projectName:
+          type: string
+          description: Name of the project to start watching for file changes
+      required:
+        - projectName
+
+    ConnectionStatus:
+      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