openapi.yaml

openapi: 3.1.0
info:
  title: JArchi Model API Server
  version: 1.1.0
  description: |
    REST API server for ArchiMate model operations running inside Archi via JArchi plugin.
    
    ## Architecture
    External clients communicate via HTTP to a Java HttpServer running inside Archi's JVM.
    All model operations execute on the SWT Display thread and are fully undoable (Ctrl+Z).
    
    ## Security Warning
    ⚠️ **NO AUTHENTICATION** - Binds to localhost only (127.0.0.1).
    Do NOT expose to network. For development and local automation only.
    
    ## Prerequisites
    - Open ArchiMate model in Archi
    - Open at least one view from the model (required for undo/redo support)
    - Port 8765 available (configurable)
  contact:
    name: JArchi Scripts
  license:
    name: MIT

servers:
  - url: http://127.0.0.1:8765
    description: Local development server (default)

tags:
  - name: Health
    description: Server health, diagnostics, and lifecycle management
  - name: Model
    description: Model query and mutation operations
  - name: Operations
    description: Async operation status tracking
  - name: Scripts
    description: Script execution and management
  - name: Views
    description: View management, export to PNG/JPEG

paths:
  /health:
    get:
      tags:
        - Health
      summary: Server health check
      description: |
        Returns detailed server health information including memory usage,
        operation queue statistics, and model information.
      operationId: getHealth
      responses:
        '200':
          description: Server health information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /test:
    get:
      tags:
        - Health
      summary: UI thread test
      description: |
        Tests that the handler is running on the SWT Display (UI) thread.
        Returns thread information and model reference status.
      operationId: getTest
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResponse'

  /shutdown:
    post:
      tags:
        - Health
      summary: Trigger server shutdown
      description: |
        Initiates graceful server shutdown. The server will wait for in-flight
        operations to complete (up to configured timeout) before stopping.
      operationId: postShutdown
      responses:
        '200':
          description: Shutdown initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShutdownResponse'

  /model/diagnostics:
    get:
      tags:
        - Health
      summary: Model diagnostics and orphan detection
      description: |
        Runs diagnostics on the loaded model, including detection of orphan/ghost
        objects. Ghost objects exist in the EMF model resource but are not contained
        in any folder — typically caused by silent GEF command stack rollbacks.

        Returns the current snapshot summary alongside any orphan elements and
        relationships found via EMF-level traversal.
      operationId: getModelDiagnostics
      responses:
        '200':
          description: Diagnostics result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticsResponse'
        '400':
          description: No model loaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/query:
    post:
      tags:
        - Model
      summary: Query model snapshot
      description: |
        Returns a summary of the model and a sample of elements.
        Optionally include relationship samples by passing `relationshipLimit`.
        The snapshot is captured when the server starts and refreshed after mutations.
      operationId: postModelQuery
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Model query result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '500':
          description: Query failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/plan:
    post:
      tags:
        - Model
      summary: Generate change plan
      description: |
        Generates a change plan without mutating the model.
        Use this to preview what changes would be made before applying them.
      operationId: postModelPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanRequest'
      responses:
        '200':
          description: Change plan generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/search:
    post:
      tags:
        - Model
      summary: Search elements with filters
      description: |
        Search for elements and relationships matching specified criteria.
        Supports filtering by type, name pattern (regex), and property key/value.
      operationId: postModelSearch
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '500':
          description: Search failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/element/{elementId}:
    get:
      tags:
        - Model
      summary: Get element details
      description: |
        Returns detailed information about a single element including:
        - Name, type, documentation
        - All properties
        - Related relationships (incoming and outgoing)
        - Views containing the element
      operationId: getElementById
      parameters:
        - name: elementId
          in: path
          required: true
          description: Element ID
          schema:
            type: string
      responses:
        '200':
          description: Element details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElementDetailResponse'
        '404':
          description: Element not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/save:
    post:
      tags:
        - Model
      summary: Save model to disk
      description: |
        Persists the current model state to its file on disk.
        Use this after making changes to ensure they are saved.

        **Auto-save behavior**: If the model has never been saved and no path is provided,
        the server will automatically generate a path based on the model name in
        `~/Documents/archi-models/`. The response will include `autoGeneratedPath: true`.

        To specify a custom location, provide the `path` parameter.
      operationId: postModelSave
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  description: |
                    Absolute file path to save the model to (e.g. "/path/to/model.archimate").
                    Optional - if omitted for unsaved models, path is auto-generated.
                    The .archimate extension is appended automatically if missing.
      responses:
        '200':
          description: Model saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveResponse'
        '500':
          description: Save failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/stats:
    get:
      tags:
        - Model
      summary: Get model statistics with type breakdowns
      description: |
        Returns detailed statistics about the model including counts of elements,
        relationships, and views grouped by ArchiMate type.

        This endpoint uses the model snapshot for fast response times without
        traversing the live model. The snapshot is refreshed after mutations.
      operationId: getModelStats
      responses:
        '200':
          description: Model statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /folders:
    get:
      tags:
        - Model
      summary: List all folders
      description: |
        Returns the complete folder hierarchy of the model.
        Includes folder type, element count, and subfolder count.
      operationId: getFolders
      responses:
        '200':
          description: Folder list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderListResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /model/apply:
    post:
      tags:
        - Model
      summary: Apply changes asynchronously
      description: |
        Queues model changes for asynchronous processing. Returns immediately
        with an operation ID that can be polled via `/ops/status`.

        All changes are executed on the SWT Display thread and are fully undoable.

        **Internal chunking**: Large batches are automatically split into smaller
        GEF CompoundCommands (default: 100 sub-commands per chunk, ~20 relationship
        creates). This prevents silent rollback by Eclipse's command stack on very
        large compound commands. Each chunk becomes a separate undo entry.

        **Post-execution verification**: After execution, created objects are verified
        to still exist in model folders. If a silent rollback is detected, the
        operation reports an error instead of falsely returning success.

        **Recommended**: Keep batches under 20 operations when creating relationships,
        or use `archicli batch apply` which handles chunking automatically and polls by default.
      operationId: postModelApply
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyRequest'
      responses:
        '200':
          description: Operation queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyResponse'
        '409':
          description: Idempotency conflict (same key with different payload)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyConflictErrorResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /ops/status:
    get:
      tags:
        - Operations
      summary: Poll operation status
      description: |
        Returns the current status of an async operation queued via `/model/apply`.
      operationId: getOpsStatus
      parameters:
        - name: opId
          in: query
          required: true
          description: Operation ID returned from `/model/apply`
          schema:
            type: string
        - name: summaryOnly
          in: query
          required: false
          description: Return compact status metadata without result payload rows
          schema:
            type: boolean
            default: false
        - name: cursor
          in: query
          required: false
          description: Zero-based cursor offset for paged result rows
          schema:
            type: string
        - name: pageSize
          in: query
          required: false
          description: Number of result rows per page (1-1000, default 200)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 200
      responses:
        '200':
          description: Operation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
        '400':
          description: Missing opId parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Operation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /ops/list:
    get:
      tags:
        - Operations
      summary: List recent operations
      description: |
        Returns recent async operations queued via `/model/apply`, sorted by newest first.
      operationId: getOpsList
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of operations to return (1-200, default 20)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - name: status
          in: query
          required: false
          description: Optional status filter
          schema:
            type: string
            enum: [queued, processing, complete, error]
        - name: cursor
          in: query
          required: false
          description: Zero-based cursor offset for paged operation summaries
          schema:
            type: string
        - name: summaryOnly
          in: query
          required: false
          description: Return compact operation summaries only
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Operation list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationListResponse'
        '400':
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /scripts/run:
    post:
      tags:
        - Scripts
      summary: Execute JArchi script code
      description: |
        Executes arbitrary JArchi script code synchronously on the UI thread.
        
        Scripts can communicate results by mutating the pre-initialized `__scriptResult` object:
        ```javascript
        // Correct - mutate the existing object properties
        __scriptResult.value = { name: "example", count: 42 };
        __scriptResult.files.push("path/to/file.png");
        
        // WRONG - reassignment loses the reference
        // __scriptResult = { value: "data" };  // This won't work!
        ```
        
        **Available helpers:**
        - `getModel()` - Returns the first loaded model, or null if none
        - `findElements(type)` - Query elements (wraps $() for API use)
        - `findViews(name)` - Query views by optional name pattern
        - `findRelationships(type)` - Query relationships
        - `__scriptsDir__` - Path to scripts directory for loading libs
        
        **Note:** The bare `$()` selector requires UI selection context and will fail via API.
        Use `getModel()` or `$.model.getLoadedModels().get(0)` instead.
        
        **⚠️ IMPORTANT: Property Modification Limitation**
        
        JArchi proxy property setters (`element.name = "..."`, `element.documentation = "..."`, 
        `element.prop("key", "value")`) will **fail with NullPointerException** when executed 
        via this endpoint. This is because the internal `CommandHandler.compoundcommands` field 
        is private and cannot be initialized from the API server context.
        
        **For element modifications, use `/model/apply` with `updateElement` operation instead:**
        ```json
        POST /model/apply
        {
          "changes": [{
            "op": "updateElement",
            "id": "element-id",
            "name": "New Name",
            "documentation": "New docs",
            "properties": { "key": "value" }
          }]
        }
        ```
        
        Scripts executed via this endpoint are best suited for:
        - **Read-only operations** (queries, exports, analysis)
        - **File generation** (PNG/JPG export, JSON export)
        - **Operations using `undoableCommands`** directly (advanced)
        
        **⚠️ BLOCKING RISK:** Scripts execute synchronously on the SWT UI thread. 
        An infinite loop or long-running computation will freeze the entire Archi application 
        and block all other API requests. There is no timeout or cancellation mechanism.
        Keep scripts short and well-tested. Maximum code size is limited by the server's 
        request body size limit (default 1MB).
      operationId: postScriptsRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptRunRequest'
      responses:
        '200':
          description: Script execution result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptRunResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Script execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ============================================================
  # View Management Endpoints
  # ============================================================

  /views:
    get:
      tags:
        - Views
      summary: List all views
      description: |
        Returns a list of all views in the model with metadata.
        Includes ArchiMate views, sketch views, and canvas views.
      operationId: getViews
      responses:
        '200':
          description: List of views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewListResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      tags:
        - Views
      summary: Create new view
      description: |
        Creates a new ArchiMate view in the model synchronously.
        The operation is undoable via Ctrl+Z in Archi.
        
        The view is created empty - use `/model/apply` to add elements.
      operationId: postViews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateViewRequest'
      responses:
        '200':
          description: View created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateViewResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: View name already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum: [ViewNameExists]
                      message:
                        type: string
                      existingViewId:
                        type: string
                        description: ID of the existing view with this name
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}:
    get:
      tags:
        - Views
      summary: Get view details
      description: |
        Returns detailed information about a specific view including
        all visual elements and connections with their positions.
      operationId: getViewById
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID
          schema:
            type: string
      responses:
        '200':
          description: View details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewDetailResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
        - Views
      summary: Delete view
      description: |
        Deletes a view from the model.
        This operation removes the view and all its visual objects.
      operationId: deleteView
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID to delete
          schema:
            type: string
      responses:
        '200':
          description: View deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  viewId:
                    type: string
                  viewName:
                    type: string
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Delete failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}/export:
    post:
      tags:
        - Views
      summary: Export view to file
      description: |
        Exports a view to an image file (PNG or JPEG).
        Returns the absolute file path for local filesystem access.
        
        If no `outputPath` is specified, a temporary file is created.
        
        **Format-specific options:**
        - `scale`: Image scale factor (0.5 to 4)
        - `margin`: Margin in pixels
      operationId: postViewExport
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID to export
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportViewRequest'
      responses:
        '200':
          description: Export successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportViewResponse'
        '400':
          description: Invalid format or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Export failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}/duplicate:
    post:
      tags:
        - Views
      summary: Duplicate view
      description: |
        Creates a deep copy of a view with all its visual objects.
        The new view is placed in the same folder as the original.
      operationId: postViewDuplicate
      parameters:
        - name: viewId
          in: path
          required: true
          description: Source view ID
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name for the duplicated view (default adds "(Copy)" suffix)
      responses:
        '200':
          description: View duplicated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  sourceViewId:
                    type: string
                  newViewId:
                    type: string
                  newViewName:
                    type: string
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Duplicate failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}/router:
    put:
      tags:
        - Views
      summary: Set connection router type
      description: |
        Sets the connection routing style for the view.
        - `bendpoint`: Manual routing with user-defined bendpoints
        - `manhattan`: Automatic orthogonal routing
      operationId: putViewRouter
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - routerType
              properties:
                routerType:
                  type: string
                  enum: [bendpoint, manhattan]
      responses:
        '200':
          description: Router set
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  viewId:
                    type: string
                  routerType:
                    type: string
        '400':
          description: Invalid router type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}/layout:
    post:
      tags:
        - Views
      summary: Apply automatic layout
      description: |
        Applies automatic graph layout algorithm to arrange elements in the view.
        Supports Dagre and Sugiyama-style layered algorithms with configurable options.
        Unknown algorithms fall back to dagre.
      operationId: postViewLayout
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutRequest'
      responses:
        '200':
          description: Layout applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutResponse'
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: Layout module not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Layout failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /views/{viewId}/validate:
    get:
      tags:
        - Views
      summary: Validate view connection integrity
      description: |
        Validates the integrity of connections in a view.
        
        Checks performed:
        - **Orphaned connections**: Visual connections without underlying relationship references
        - **Direction mismatches**: Visual connections where source/target don't match relationship direction
        
        Use this endpoint after populating views to verify connection integrity.
      operationId: getViewValidate
      parameters:
        - name: viewId
          in: path
          required: true
          description: View ID to validate
          schema:
            type: string
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateViewResponse'
        '404':
          description: View not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok, stopping]
          description: Server status
        version:
          type: string
          example: "1.1.0"
        server:
          type: object
          properties:
            port:
              type: integer
              example: 8765
            host:
              type: string
              example: "127.0.0.1"
            uptime:
              type: integer
              nullable: true
              description: Server uptime in milliseconds
        operations:
          $ref: '#/components/schemas/QueueStats'
        model:
          $ref: '#/components/schemas/ModelInfo'
        memory:
          $ref: '#/components/schemas/MemoryInfo'
        timestamp:
          type: string
          format: date-time

    QueueStats:
      type: object
      nullable: true
      properties:
        queueSize:
          type: integer
        queued:
          type: integer
        processing:
          type: integer
        completed:
          type: integer
        error:
          type: integer
        total:
          type: integer

    ModelInfo:
      type: object
      nullable: true
      properties:
        name:
          type: string
        id:
          type: string
        elements:
          type: integer
        relationships:
          type: integer
        views:
          type: integer
        error:
          type: string

    MemoryInfo:
      type: object
      properties:
        totalMB:
          type: integer
        freeMB:
          type: integer
        usedMB:
          type: integer
        maxMB:
          type: integer

    TestResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          description: Thread and model information

    ShutdownResponse:
      type: object
      properties:
        status:
          type: string
          enum: [stopping]
        message:
          type: string
        inFlightOperations:
          type: integer

    DiagnosticsResponse:
      type: object
      description: Model diagnostics including orphan/ghost object detection
      properties:
        timestamp:
          type: string
          format: date-time
        model:
          type: object
          properties:
            name:
              type: string
            id:
              type: string
        orphans:
          type: object
          description: Orphan objects found in EMF resource but missing from folder structure
          properties:
            orphanElements:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  type:
                    type: string
            orphanRelationships:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  type:
                    type: string
                  source:
                    type: string
                    nullable: true
                  target:
                    type: string
                    nullable: true
            totalOrphans:
              type: integer
            error:
              type: string
              description: Error message if orphan detection failed
        snapshot:
          type: object
          description: Current snapshot summary (folder-based counts)
          properties:
            elements:
              type: integer
            relationships:
              type: integer
            views:
              type: integer

  # --- Model Endpoints will be added below ---

    QueryRequest:
      type: object
      properties:
        limit:
          type: integer
          default: 10
          description: Maximum number of sample elements to return
        relationshipLimit:
          type: integer
          minimum: 1
          description: Optional maximum number of relationship samples to return

    QueryResponse:
      type: object
      properties:
        summary:
          type: object
          properties:
            elements:
              type: integer
            relationships:
              type: integer
            views:
              type: integer
        elements:
          type: array
          items:
            $ref: '#/components/schemas/ElementSummary'
        relationships:
          type: array
          description: Present only when relationshipLimit is specified in the request
          items:
            $ref: '#/components/schemas/RelationshipSummary'

    ElementSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        documentation:
          type: string

    PlanRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          description: Action to plan (e.g., "create-element")
        type:
          type: string
          description: Element type for create actions
        name:
          type: string
          description: Element name for create actions

    PlanResponse:
      type: object
      properties:
        planId:
          type: string
        changes:
          type: array
          items:
            $ref: '#/components/schemas/ChangeOperation'
        warnings:
          type: array
          items:
            type: string

    ApplyRequest:
      type: object
      required:
        - changes
      properties:
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[A-Za-z0-9:_-]+$'
          description: Caller-provided idempotency key for replay-safe /model/apply requests.
        duplicateStrategy:
          $ref: '#/components/schemas/DuplicateStrategy'
        changes:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/ChangeOperation'

    ChangeOperation:
      type: object
      required:
        - op
      discriminator:
        propertyName: op
        mapping:
          createElement: '#/components/schemas/CreateElementOp'
          createOrGetElement: '#/components/schemas/CreateOrGetElementOp'
          createRelationship: '#/components/schemas/CreateRelationshipOp'
          createOrGetRelationship: '#/components/schemas/CreateOrGetRelationshipOp'
          setProperty: '#/components/schemas/SetPropertyOp'
          updateElement: '#/components/schemas/UpdateElementOp'
          deleteElement: '#/components/schemas/DeleteElementOp'
          deleteRelationship: '#/components/schemas/DeleteRelationshipOp'
          updateRelationship: '#/components/schemas/UpdateRelationshipOp'
          moveToFolder: '#/components/schemas/MoveToFolderOp'
          createFolder: '#/components/schemas/CreateFolderOp'
          addToView: '#/components/schemas/AddToViewOp'
          addConnectionToView: '#/components/schemas/AddConnectionToViewOp'
          nestInView: '#/components/schemas/NestInViewOp'
          deleteConnectionFromView: '#/components/schemas/DeleteConnectionFromViewOp'
          styleViewObject: '#/components/schemas/StyleViewObjectOp'
          styleConnection: '#/components/schemas/StyleConnectionOp'
          moveViewObject: '#/components/schemas/MoveViewObjectOp'
          createNote: '#/components/schemas/CreateNoteOp'
          createGroup: '#/components/schemas/CreateGroupOp'
          createView: '#/components/schemas/CreateViewOp'
          deleteView: '#/components/schemas/DeleteViewOp'
      oneOf:
        - $ref: '#/components/schemas/CreateElementOp'
        - $ref: '#/components/schemas/CreateOrGetElementOp'
        - $ref: '#/components/schemas/CreateRelationshipOp'
        - $ref: '#/components/schemas/CreateOrGetRelationshipOp'
        - $ref: '#/components/schemas/SetPropertyOp'
        - $ref: '#/components/schemas/UpdateElementOp'
        - $ref: '#/components/schemas/DeleteElementOp'
        - $ref: '#/components/schemas/DeleteRelationshipOp'
        - $ref: '#/components/schemas/UpdateRelationshipOp'
        - $ref: '#/components/schemas/MoveToFolderOp'
        - $ref: '#/components/schemas/CreateFolderOp'
        - $ref: '#/components/schemas/AddToViewOp'
        - $ref: '#/components/schemas/AddConnectionToViewOp'
        - $ref: '#/components/schemas/NestInViewOp'
        - $ref: '#/components/schemas/DeleteConnectionFromViewOp'
        - $ref: '#/components/schemas/StyleViewObjectOp'
        - $ref: '#/components/schemas/StyleConnectionOp'
        - $ref: '#/components/schemas/MoveViewObjectOp'
        - $ref: '#/components/schemas/CreateNoteOp'
        - $ref: '#/components/schemas/CreateGroupOp'
        - $ref: '#/components/schemas/CreateViewOp'
        - $ref: '#/components/schemas/DeleteViewOp'

    DuplicateStrategy:
      type: string
      enum: [error, reuse, rename]
      default: error
      description: |
        Duplicate handling strategy precedence:
        `onDuplicate` (operation) > `duplicateStrategy` (request) > `error` (default).

    ElementCreateSpec:
      type: object
      required:
        - type
        - name
      properties:
        type:
          $ref: '#/components/schemas/ArchiMateElementType'
        name:
          type: string
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        documentation:
          type: string
        folder:
          type: string
          description: Target folder path or ID
        properties:
          type: object
          additionalProperties:
            type: string
      additionalProperties: false

    ElementMatchSpec:
      type: object
      required:
        - type
        - name
      properties:
        type:
          $ref: '#/components/schemas/ArchiMateElementType'
        name:
          type: string
      additionalProperties: false

    CreateOrGetElementOp:
      type: object
      required:
        - op
        - create
        - match
      properties:
        op:
          type: string
          enum: [createOrGetElement]
        create:
          $ref: '#/components/schemas/ElementCreateSpec'
        match:
          $ref: '#/components/schemas/ElementMatchSpec'
        onDuplicate:
          $ref: '#/components/schemas/DuplicateStrategy'
      additionalProperties: false

    RelationshipCreateSpec:
      type: object
      required:
        - type
        - sourceId
        - targetId
      properties:
        type:
          $ref: '#/components/schemas/ArchiMateRelationshipType'
        sourceId:
          type: string
          description: Source element ID or tempId
        targetId:
          type: string
          description: Target element ID or tempId
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        name:
          type: string
        documentation:
          type: string
        accessType:
          type: integer
          enum: [0, 1, 2, 3]
        strength:
          type: string
      additionalProperties: false

    RelationshipMatchSpec:
      type: object
      required:
        - type
        - sourceId
        - targetId
      properties:
        type:
          $ref: '#/components/schemas/ArchiMateRelationshipType'
        sourceId:
          type: string
          description: Source element ID or tempId
        targetId:
          type: string
          description: Target element ID or tempId
        accessType:
          type: integer
          enum: [0, 1, 2, 3]
        strength:
          type: string
      additionalProperties: false

    CreateOrGetRelationshipOp:
      type: object
      required:
        - op
        - create
        - match
      properties:
        op:
          type: string
          enum: [createOrGetRelationship]
        create:
          $ref: '#/components/schemas/RelationshipCreateSpec'
        match:
          $ref: '#/components/schemas/RelationshipMatchSpec'
        onDuplicate:
          type: string
          enum: [error, reuse]
          default: error
          description: Relationship upsert does not support `rename`.
      additionalProperties: false

    CreateElementOp:
      type: object
      required:
        - op
        - type
        - name
      properties:
        op:
          type: string
          enum: [createElement]
        type:
          $ref: '#/components/schemas/ArchiMateElementType'
        name:
          type: string
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        documentation:
          type: string
        folder:
          type: string
          description: Target folder path or ID

    CreateRelationshipOp:
      type: object
      required:
        - op
        - type
        - sourceId
        - targetId
      properties:
        op:
          type: string
          enum: [createRelationship]
        type:
          $ref: '#/components/schemas/ArchiMateRelationshipType'
        sourceId:
          type: string
          description: Source element ID or tempId
        targetId:
          type: string
          description: Target element ID or tempId
        name:
          type: string
        tempId:
          type: string

    SetPropertyOp:
      type: object
      required:
        - op
        - id
        - key
        - value
      properties:
        op:
          type: string
          enum: [setProperty]
        id:
          type: string
          description: Element or relationship ID
        key:
          type: string
          description: Property key
        value:
          type: string
          description: Property value

    UpdateElementOp:
      type: object
      required:
        - op
        - id
      description: |
        Update an existing element's name, documentation, and/or properties.
        At least one of `name`, `documentation`, or `properties` must be provided.
      properties:
        op:
          type: string
          enum: [updateElement]
        id:
          type: string
          description: Element ID (real ID or tempId from prior createElement)
        name:
          type: string
          description: New name for the element (optional)
        documentation:
          type: string
          description: New documentation text (optional)
        properties:
          type: object
          additionalProperties:
            type: string
          description: Properties to set/update as key-value pairs (optional)

    DeleteElementOp:
      type: object
      required:
        - op
        - id
      properties:
        op:
          type: string
          enum: [deleteElement]
        id:
          type: string
          description: Element or relationship ID to delete
        cascade:
          type: boolean
          default: true
          description: |
            If true (default), also removes all relationships where this element is
            source or target, and all visual references across all views.
            If false, only removes the element from its parent folder.

    AddToViewOp:
      type: object
      required:
        - op
        - viewId
        - elementId
      properties:
        op:
          type: string
          enum: [addToView]
        viewId:
          type: string
          description: Target view ID
        elementId:
          type: string
          description: Element or relationship ID to add to view (real ID or tempId)
        tempId:
          type: string
          description: Temporary ID for referencing the created visual object in subsequent operations
        parentVisualId:
          type: string
          description: |
            Visual object ID of the parent container to nest this element inside.
            Can be a visual object ID or tempId from a prior addToView/createGroup operation.
            Coordinates (x, y) become relative to the parent container's bounds.
            If omitted, the element is added to the view root.
        x:
          type: integer
          description: X coordinate (relative to parent container or view root, default 100)
        y:
          type: integer
          description: Y coordinate (relative to parent container or view root, default 100)
        width:
          type: integer
          description: Width in pixels (-1 for default)
        height:
          type: integer
          description: Height in pixels (-1 for default)
        autoNest:
          type: boolean
          description: If true, auto-nest inside surrounding visual objects

    AddConnectionToViewOp:
      type: object
      required:
        - op
        - viewId
        - relationshipId
      description: |
        Add a relationship as a visual connection in a view.
        Source and target visuals can be specified explicitly via sourceVisualId/targetVisualId,
        or resolved automatically when autoResolveVisuals is true. Auto-resolution finds visual
        objects by matching the relationship's source/target element IDs against visuals in the
        view (same-batch or already committed).
      properties:
        op:
          type: string
          enum: [addConnectionToView]
        viewId:
          type: string
          description: Target view ID
        relationshipId:
          type: string
          description: Relationship ID to visualize (real ID or tempId)
        sourceVisualId:
          type: string
          description: Source visual object ID (from addToView result or existing visual). Optional when autoResolveVisuals is true.
        targetVisualId:
          type: string
          description: Target visual object ID (from addToView result or existing visual). Optional when autoResolveVisuals is true.
        autoResolveVisuals:
          type: boolean
          default: false
          description: |
            When true, automatically resolve source and target visual objects by matching the
            relationship's source/target elements against visual objects in the view. This
            eliminates the need to provide sourceVisualId and targetVisualId. The server checks
            same-batch operations first (via tempId index), then falls back to committed view
            children. The result includes autoResolved: true when resolution succeeds.

    NestInViewOp:
      type: object
      required:
        - op
        - viewId
        - visualId
        - parentVisualId
      description: |
        Move an existing visual object to be a child of another visual object in the same view.
        This is the equivalent of jArchi's parent.add(object, x, y) method.
        The x, y position is relative to the target parent object's bounds.
        Use this to create proper visual nesting for compound elements (e.g., an Application Component
        containing child Application Components via composition relationships).
      properties:
        op:
          type: string
          enum: [nestInView]
        viewId:
          type: string
          description: View ID containing both visual objects
        visualId:
          type: string
          description: Visual object ID (or tempId) to move into the parent
        parentVisualId:
          type: string
          description: Visual object ID (or tempId) of the target parent container
        x:
          type: integer
          description: X position relative to parent container (default 10)
        y:
          type: integer
          description: Y position relative to parent container (default 10)

    DeleteConnectionFromViewOp:
      type: object
      required:
        - op
        - viewId
        - connectionId
      description: |
        Delete a visual connection from a view.
        Use this to remove orphaned or incorrectly-created connections.
        The underlying model relationship is NOT deleted.
      properties:
        op:
          type: string
          enum: [deleteConnectionFromView]
        viewId:
          type: string
          description: View ID containing the connection
        connectionId:
          type: string
          description: Connection ID to delete (from addConnectionToView result or view details)

    DeleteRelationshipOp:
      type: object
      required:
        - op
        - id
      properties:
        op:
          type: string
          enum: [deleteRelationship]
        id:
          type: string
          description: Relationship ID to delete

    UpdateRelationshipOp:
      type: object
      required:
        - op
        - id
      properties:
        op:
          type: string
          enum: [updateRelationship]
        id:
          type: string
          description: Relationship ID
        name:
          type: string
          description: New name for the relationship (optional)
        documentation:
          type: string
          description: New documentation text (optional)
        properties:
          type: object
          additionalProperties:
            type: string
          description: Properties to set/update as key-value pairs (optional)

    MoveToFolderOp:
      type: object
      required:
        - op
        - id
        - folderId
      properties:
        op:
          type: string
          enum: [moveToFolder]
        id:
          type: string
          description: Element, relationship, or view ID to move
        folderId:
          type: string
          description: Target folder ID, or a createFolder tempId from an earlier operation in the same batch

    CreateFolderOp:
      type: object
      required:
        - op
        - name
      anyOf:
        - required: [parentId]
        - required: [parentType]
        - required: [parentFolder]
      properties:
        op:
          type: string
          enum: [createFolder]
        name:
          type: string
          description: Folder name
        parentId:
          type: string
          description: Parent folder ID
        parentType:
          type: string
          description: Parent top-level folder type token (for example BUSINESS, APPLICATION, TECHNOLOGY, VIEWS)
        parentFolder:
          type: string
          description: Parent folder display name (for example Business, Application, Views)
        documentation:
          type: string
          description: Optional folder documentation
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations

    StyleViewObjectOp:
      type: object
      required:
        - op
        - viewObjectId
      description: Apply visual styling to a view object (element, note, or group)
      properties:
        op:
          type: string
          enum: [styleViewObject]
        viewObjectId:
          type: string
          description: Visual object ID in a view
        fillColor:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          description: Fill color in hex format (e.g., "#FF5733")
        lineColor:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          description: Line/border color in hex format
        fontColor:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          description: Font color in hex format
        opacity:
          type: integer
          minimum: 0
          maximum: 255
          description: Fill opacity (0=transparent, 255=opaque)
        lineWidth:
          type: integer
          minimum: 1
          maximum: 10
          description: Border line width in pixels
        textAlignment:
          type: integer
          enum: [0, 1, 2]
          description: Text alignment (0=left, 1=center, 2=right)
        textPosition:
          type: integer
          enum: [0, 1, 2]
          description: Text position (0=top, 1=middle, 2=bottom)

    StyleConnectionOp:
      type: object
      required:
        - op
        - connectionId
      description: Apply visual styling to a connection in a view
      properties:
        op:
          type: string
          enum: [styleConnection]
        connectionId:
          type: string
          description: Connection ID in a view
        lineColor:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          description: Line color in hex format
        fontColor:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          description: Font color in hex format
        lineWidth:
          type: integer
          minimum: 1
          maximum: 10
          description: Line width in pixels
        textPosition:
          type: integer
          enum: [0, 1, 2]
          description: Label position (0=source, 1=middle, 2=target)

    MoveViewObjectOp:
      type: object
      required:
        - op
        - viewObjectId
      description: Move or resize a visual object in a view
      properties:
        op:
          type: string
          enum: [moveViewObject]
        viewObjectId:
          type: string
          description: Visual object ID
        x:
          type: integer
          description: New X coordinate
        y:
          type: integer
          description: New Y coordinate
        width:
          type: integer
          description: New width
        height:
          type: integer
          description: New height

    CreateNoteOp:
      type: object
      required:
        - op
        - viewId
        - content
      description: Create a note (text annotation) in a view
      properties:
        op:
          type: string
          enum: [createNote]
        viewId:
          type: string
          description: Target view ID
        content:
          type: string
          description: Note text content
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        x:
          type: integer
          description: X coordinate (default 100)
        y:
          type: integer
          description: Y coordinate (default 100)
        width:
          type: integer
          description: Width (default 200)
        height:
          type: integer
          description: Height (default 100)

    CreateGroupOp:
      type: object
      required:
        - op
        - viewId
        - name
      description: Create a visual group in a view
      properties:
        op:
          type: string
          enum: [createGroup]
        viewId:
          type: string
          description: Target view ID
        name:
          type: string
          description: Group name/label
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        x:
          type: integer
          description: X coordinate (default 100)
        y:
          type: integer
          description: Y coordinate (default 100)
        width:
          type: integer
          description: Width (default 400)
        height:
          type: integer
          description: Height (default 300)

    CreateViewOp:
      type: object
      required:
        - op
        - name
      description: Create a new view in the model
      properties:
        op:
          type: string
          enum: [createView]
        name:
          type: string
          description: View name
        tempId:
          type: string
          description: Temporary ID for referencing in subsequent operations
        documentation:
          type: string
          description: View documentation
        viewpoint:
          type: string
          pattern: '^[a-z0-9_]+$'
          description: ArchiMate viewpoint ID (for example application_cooperation)

    DeleteViewOp:
      type: object
      required:
        - op
        - viewId
      description: Delete a view by ID
      properties:
        op:
          type: string
          enum: [deleteView]
        viewId:
          type: string
          description: View ID to delete

    ApplyResponse:
      type: object
      properties:
        operationId:
          type: string
        status:
          type: string
          enum: [queued, processing, complete, error]
        message:
          type: string
        digest:
          $ref: '#/components/schemas/OperationDigest'
        tempIdMap:
          type: object
          additionalProperties:
            type: string
        tempIdMappings:
          type: array
          items:
            $ref: '#/components/schemas/TempIdMapping'
        idempotency:
          type: object
          description: Present when idempotencyKey was provided on apply.
          properties:
            key:
              type: string
            replayed:
              type: boolean
            firstSeenAt:
              type: string
              format: date-time
            expiresAt:
              type: string
              format: date-time

    OperationStatusResponse:
      type: object
      properties:
        operationId:
          type: string
        status:
          type: string
          enum: [queued, processing, complete, error]
        result:
          type: array
          nullable: true
          items:
            type: object
          description: Array of operation results (when status is complete)
        totalResultCount:
          type: integer
          nullable: true
          description: Total number of result rows available before paging
        cursor:
          type: string
          nullable: true
          description: Current cursor offset for paged results
        pageSize:
          type: integer
          nullable: true
          description: Page size used for result paging
        hasMore:
          type: boolean
          nullable: true
          description: True when additional paged rows are available
        nextCursor:
          type: string
          nullable: true
          description: Cursor token for the next page
        summaryOnly:
          type: boolean
          nullable: true
          description: True when response is compact metadata without result rows
        error:
          type: string
          nullable: true
          description: Error message (when status is error)
        errorDetails:
          type: object
          nullable: true
          description: Structured context for failed operations (when status is error)
          properties:
            code:
              type: string
            message:
              type: string
            opIndex:
              type: integer
              description: Zero-based index in /changes array
            opNumber:
              type: integer
              description: One-based operation number for human-readable output
            path:
              type: string
              description: JSON pointer-like location (e.g. /changes/2)
            op:
              type: string
              description: Operation type (e.g. addToView)
            field:
              type: string
              description: Field involved in the failure context
            reference:
              type: string
              description: Unresolved id/tempId value when detected
            hint:
              type: string
              description: Short remediation hint
            change:
              type: object
              description: Original change payload for the failing operation (best effort)
        message:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        durationMs:
          type: integer
          nullable: true
          description: Duration in milliseconds (included for both complete and error status)
        digest:
          $ref: '#/components/schemas/OperationDigest'
        tempIdMap:
          type: object
          additionalProperties:
            type: string
        tempIdMappings:
          type: array
          items:
            $ref: '#/components/schemas/TempIdMapping'
        timeline:
          type: array
          items:
            $ref: '#/components/schemas/OperationTimelineEvent'
        retryHints:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true

    OperationSummary:
      type: object
      properties:
        operationId:
          type: string
        status:
          type: string
          enum: [queued, processing, complete, error]
        createdAt:
          type: string
          format: date-time
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        durationMs:
          type: integer
          nullable: true
        changeCount:
          type: integer
        error:
          type: string
          nullable: true
        digest:
          $ref: '#/components/schemas/OperationDigest'
        tempIdMap:
          type: object
          additionalProperties:
            type: string
        tempIdMappings:
          type: array
          items:
            $ref: '#/components/schemas/TempIdMapping'
        timeline:
          type: array
          items:
            $ref: '#/components/schemas/OperationTimelineEvent'
        retryHints:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true

    OperationListResponse:
      type: object
      properties:
        operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationSummary'
        total:
          type: integer
        limit:
          type: integer
        status:
          type: string
          nullable: true
        cursor:
          type: string
          nullable: true
        hasMore:
          type: boolean
          nullable: true
        nextCursor:
          type: string
          nullable: true
        summaryOnly:
          type: boolean
          nullable: true

    TempIdMapping:
      type: object
      properties:
        tempId:
          type: string
        resolvedId:
          type: string
        mappingType:
          type: string
          enum: [concept, visual, connection, view]
        op:
          type: string
          nullable: true
        resultIndex:
          type: integer

    OperationTimelineEvent:
      type: object
      properties:
        status:
          type: string
          enum: [queued, processing, complete, failed]
        timestamp:
          type: string
          format: date-time
        chunkIndex:
          type: integer
          nullable: true
        chunkCount:
          type: integer
          nullable: true
        operationCount:
          type: integer
          nullable: true
        resultCount:
          type: integer
          nullable: true
        error:
          type: string
          nullable: true
        opIndex:
          type: integer
          nullable: true
        op:
          type: string
          nullable: true

    OperationDigest:
      type: object
      properties:
        totals:
          type: object
          properties:
            requested:
              type: integer
            results:
              type: integer
            executed:
              type: integer
            skipped:
              type: integer
        requestedByType:
          type: object
          additionalProperties:
            type: integer
        executedByType:
          type: object
          additionalProperties:
            type: integer
        skipsByReason:
          type: object
          additionalProperties:
            type: integer
        integrityFlags:
          type: object
          additionalProperties:
            type: boolean

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

    IdempotencyConflictErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            operationId:
              type: string
              nullable: true
            idempotency:
              type: object
              properties:
                key:
                  type: string
                replayed:
                  type: boolean
                firstSeenAt:
                  type: string
                  format: date-time
                expiresAt:
                  type: string
                  format: date-time

    # --- Search & Element Schemas ---

    SearchRequest:
      type: object
      description: Search criteria for finding elements/relationships
      properties:
        type:
          type: string
          description: Filter by element/relationship type (e.g., "application-component")
        namePattern:
          type: string
          description: Regex pattern to match against names
        propertyKey:
          type: string
          description: Property key to filter by
        propertyValue:
          type: string
          description: Property value to match (used with propertyKey)
        includeRelationships:
          type: boolean
          default: true
          description: Include relationships in result set (default true)
        limit:
          type: integer
          default: 100
          description: Maximum number of results to return

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        total:
          type: integer
          description: Total number of matching items
        criteria:
          type: object
          properties:
            type:
              type: string
              nullable: true
            namePattern:
              type: string
              nullable: true
            propertyKey:
              type: string
              nullable: true
            propertyValue:
              type: string
              nullable: true
            includeRelationships:
              type: boolean
            limit:
              type: integer

    SearchResult:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        documentation:
          type: string

    RelationshipSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        source:
          type: string
          nullable: true
        target:
          type: string
          nullable: true
        sourceId:
          type: string
          nullable: true
        targetId:
          type: string
          nullable: true
        matchedPropertyKey:
          type: string
          nullable: true
          description: Property key that matched the search filter
        matchedPropertyValue:
          type: string
          nullable: true
          description: Property value that matched the search filter
        kind:
          type: string
          enum: [element, relationship]
          description: Whether this is an element or relationship

    ElementDetailResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        documentation:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          description: Custom properties as key-value pairs
        relationships:
          type: object
          properties:
            incoming:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipInfo'
            outgoing:
              type: array
              items:
                $ref: '#/components/schemas/RelationshipInfo'
        views:
          type: array
          items:
            $ref: '#/components/schemas/ViewReference'
          description: Views containing this element

    RelationshipInfo:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        otherEndId:
          type: string
          description: ID of the element at the other end
        otherEndName:
          type: string
        otherEndType:
          type: string

    ViewReference:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

    SaveResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        modelName:
          type: string
          description: Name of the saved model
        modelId:
          type: string
          description: ID of the saved model
        path:
          type: string
          description: File path where the model was saved
        durationMs:
          type: integer
          description: Time taken to save in milliseconds
        autoGeneratedPath:
          type: boolean
          description: |
            Present and true when the server auto-generated the save path
            because the model was never saved and no path was provided

    StatsResponse:
      type: object
      properties:
        summary:
          type: object
          properties:
            totalElements:
              type: integer
              example: 145
            totalRelationships:
              type: integer
              example: 89
            totalViews:
              type: integer
              example: 12
            elementTypes:
              type: integer
              description: Number of distinct element types in model
              example: 15
            relationshipTypes:
              type: integer
              description: Number of distinct relationship types in model
              example: 8
            viewTypes:
              type: integer
              description: Number of distinct view types in model
              example: 3
        elements:
          type: object
          description: Element counts grouped by ArchiMate type
          additionalProperties:
            type: integer
          example:
            business-actor: 23
            business-role: 12
            application-component: 45
            technology-node: 18
        relationships:
          type: object
          description: Relationship counts grouped by ArchiMate type
          additionalProperties:
            type: integer
          example:
            composition-relationship: 34
            serving-relationship: 28
            assignment-relationship: 15
        views:
          type: object
          description: View counts grouped by type
          additionalProperties:
            type: integer
          example:
            archimate-diagram-model: 10
            sketch-model: 2

    # --- Folder Schemas ---

    FolderListResponse:
      type: object
      properties:
        folders:
          type: array
          items:
            $ref: '#/components/schemas/FolderInfo'

    FolderInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [business, application, technology, motivation, strategy, implementation_migration, other, relations, diagrams]
          description: Folder type (root folder category or user-created)
        path:
          type: string
          description: Full path from root (e.g., "Business/Processes/Core")
        children:
          type: array
          items:
            $ref: '#/components/schemas/FolderInfo'
          description: Nested subfolders

    # --- Layout Schemas ---

    LayoutRequest:
      type: object
      properties:
        algorithm:
          type: string
          enum: [dagre, sugiyama]
          default: dagre
          description: Layout algorithm to apply
        rankdir:
          type: string
          enum: [TB, BT, LR, RL]
          default: TB
          description: Graph direction (TB=top-bottom, LR=left-right, etc.)
        ranksep:
          type: integer
          default: 80
          description: Vertical separation between ranks in pixels
        nodesep:
          type: integer
          default: 50
          description: Horizontal separation between nodes in pixels
        edgesep:
          type: integer
          default: 10
          description: Pixels between edges
        marginx:
          type: integer
          default: 20
          description: Left/right margin in pixels
        marginy:
          type: integer
          default: 20
          description: Top/bottom margin in pixels

    LayoutResponse:
      type: object
      properties:
        success:
          type: boolean
        viewId:
          type: string
        algorithm:
          type: string
        options:
          type: object
          description: Layout options that were applied
        nodesPositioned:
          type: integer
          description: Number of nodes repositioned
        durationMs:
          type: integer
          description: Layout duration in milliseconds

    # --- Additional View Schemas ---

    DuplicateViewResponse:
      type: object
      properties:
        success:
          type: boolean
        originalViewId:
          type: string
        newViewId:
          type: string
        newViewName:
          type: string
        durationMs:
          type: integer

    SetRouterResponse:
      type: object
      properties:
        success:
          type: boolean
        viewId:
          type: string
        viewName:
          type: string
        router:
          type: string
          enum: [bendpoint, manhattan]
        durationMs:
          type: integer

    ValidateViewResponse:
      type: object
      description: Result of view connection integrity validation
      properties:
        valid:
          type: boolean
          description: True if all checks passed
        viewId:
          type: string
        viewName:
          type: string
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ValidationCheck'

    ValidationCheck:
      type: object
      properties:
        name:
          type: string
          description: Check name (e.g., "orphaned_connections", "direction_mismatches")
        description:
          type: string
        passed:
          type: boolean
        violations:
          type: array
          items:
            $ref: '#/components/schemas/ValidationViolation'

    ValidationViolation:
      type: object
      properties:
        connectionId:
          type: string
        connectionName:
          type: string
        issue:
          type: string
          description: Description of the problem
        fix:
          type: string
          description: Suggested fix for the violation
        relationshipId:
          type: string
          nullable: true
        visualSourceElement:
          type: string
          nullable: true
        visualTargetElement:
          type: string
          nullable: true
        relationshipSourceElement:
          type: string
          nullable: true
        relationshipTargetElement:
          type: string
          nullable: true

    # --- Script Schemas ---
    
    ScriptRunRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: JavaScript code to execute

    ScriptRunResponse:
      type: object
      properties:
        success:
          type: boolean
        output:
          type: array
          items:
            $ref: '#/components/schemas/ConsoleOutput'
        files:
          type: array
          items:
            type: string
          description: File paths created/modified by the script
        result:
          description: Return value if script sets __scriptResult.value
        error:
          type: string
          nullable: true
        durationMs:
          type: integer

    ConsoleOutput:
      type: object
      properties:
        level:
          type: string
          enum: [log, print, println, error]
        message:
          type: string

    # --- ArchiMate Type Enumerations ---

    ArchiMateElementType:
      type: string
      description: Valid ArchiMate element types
      enum:
        # Strategy Layer
        - resource
        - capability
        - value-stream
        - course-of-action
        # Business Layer
        - business-actor
        - business-role
        - business-collaboration
        - business-interface
        - business-process
        - business-function
        - business-interaction
        - business-event
        - business-service
        - business-object
        - contract
        - representation
        - product
        # Application Layer
        - application-component
        - application-collaboration
        - application-interface
        - application-function
        - application-interaction
        - application-process
        - application-event
        - application-service
        - data-object
        # Technology Layer
        - node
        - device
        - system-software
        - technology-collaboration
        - technology-interface
        - path
        - communication-network
        - technology-function
        - technology-process
        - technology-interaction
        - technology-event
        - technology-service
        - artifact
        # Physical Layer
        - equipment
        - facility
        - distribution-network
        - material
        # Motivation Layer
        - stakeholder
        - driver
        - assessment
        - goal
        - outcome
        - principle
        - requirement
        - constraint
        - meaning
        - value
        # Implementation & Migration Layer
        - work-package
        - deliverable
        - implementation-event
        - plateau
        - gap
        # Other
        - location
        - grouping
        - junction

    ArchiMateRelationshipType:
      type: string
      description: Valid ArchiMate relationship types
      enum:
        - composition-relationship
        - aggregation-relationship
        - assignment-relationship
        - realization-relationship
        - serving-relationship
        - access-relationship
        - influence-relationship
        - triggering-relationship
        - flow-relationship
        - specialization-relationship
        - association-relationship

    # ============================================================
    # View Schemas
    # ============================================================

    ViewListResponse:
      type: object
      properties:
        views:
          type: array
          items:
            $ref: '#/components/schemas/ViewSummary'
        total:
          type: integer

    ViewSummary:
      type: object
      properties:
        id:
          type: string
          description: Unique view ID
        name:
          type: string
          description: View name
        type:
          type: string
          enum: [archimate-diagram-model, sketch-model, canvas-model]
          description: View type
        viewpoint:
          type: string
          nullable: true
          description: ArchiMate viewpoint (e.g., "application_cooperation")
        objectCount:
          type: integer
          nullable: true
          description: Number of visual objects in view
        connectionCount:
          type: integer
          nullable: true
          description: Number of connections in view

    CreateViewRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name for the new view
        viewpoint:
          type: string
          nullable: true
          description: ArchiMate viewpoint ID or label (optional, e.g., "application_cooperation" or "Application Cooperation")
        folder:
          type: string
          nullable: true
          description: Target folder path or ID
        documentation:
          type: string
          nullable: true
          description: View documentation
        allowDuplicate:
          type: boolean
          default: false
          description: |
            Allow creating a view even if one with this name already exists.
            When false (default), returns 409 Conflict if name exists.

    CreateViewResponse:
      type: object
      properties:
        success:
          type: boolean
        viewId:
          type: string
          description: ID of the created view
        viewName:
          type: string
          description: Name of the created view
        viewType:
          type: string
          description: Type of the created view
        viewpoint:
          type: string
          nullable: true
          description: Viewpoint ID if specified
        documentation:
          type: string
          nullable: true
          description: Documentation if specified
        durationMs:
          type: integer
          description: Creation duration in milliseconds

    ViewDetailResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [archimate-diagram-model, sketch-model, canvas-model]
        documentation:
          type: string
        viewpoint:
          type: string
          nullable: true
        connectionRouter:
          type: string
          nullable: true
          enum: [bendpoint, manhattan]
          description: Connection routing style
        elements:
          type: array
          items:
            $ref: '#/components/schemas/ViewElement'
        connections:
          type: array
          items:
            $ref: '#/components/schemas/ViewConnection'

    ViewElement:
      type: object
      properties:
        id:
          type: string
          description: Visual object ID (diagram object)
        type:
          type: string
          description: Visual element type
        name:
          type: string
        x:
          type: integer
        y:
          type: integer
        width:
          type: integer
        height:
          type: integer
        parentId:
          type: string
          nullable: true
          description: |
            Visual object ID of the parent container, if this element is nested inside
            another visual object (e.g., a group or compound element). Null/absent for
            top-level elements. Coordinates (x, y) are relative to the parent when present.
        conceptId:
          type: string
          nullable: true
          description: Underlying ArchiMate concept ID
        conceptType:
          type: string
          nullable: true
          description: Underlying ArchiMate concept type

    ViewConnection:
      type: object
      properties:
        id:
          type: string
          description: Visual connection ID
        type:
          type: string
          description: Connection type
        name:
          type: string
        sourceId:
          type: string
          description: Source visual object ID
        targetId:
          type: string
          description: Target visual object ID
        conceptId:
          type: string
          nullable: true
          description: Underlying ArchiMate relationship ID
        conceptType:
          type: string
          nullable: true
          description: Underlying ArchiMate relationship type

    ExportViewRequest:
      type: object
      properties:
        format:
          type: string
          enum: [PNG, JPG, JPEG]
          default: PNG
          description: Export format (PNG or JPEG)
        outputPath:
          type: string
          nullable: true
          description: |
            Absolute or relative file path for output. Relative paths resolve from server process working directory.
            If omitted, a temporary file is created.
            Parent directories are created automatically.
        scale:
          type: number
          minimum: 0.5
          maximum: 4
          description: Image scale factor
        margin:
          type: integer
          minimum: 0
          description: Margin in pixels

    ExportViewResponse:
      type: object
      properties:
        success:
          type: boolean
        viewId:
          type: string
        viewName:
          type: string
        format:
          type: string
          enum: [PNG, JPG]
        filePath:
          type: string
          description: Absolute path to exported file
        fileSizeBytes:
          type: integer
          description: File size in bytes
        durationMs:
          type: integer
          description: Export duration in milliseconds