openapi: 3.0.3
info:
  title: Nixstasis Builder Schema API
  version: 1.0.0
  description: Bespoke Phoenix controller API for schema-derived alert and report builder options.
paths:
  /api/v1/builder-schemas:
    get:
      summary: List schema references visible to the current user
      responses:
        "200":
          description: Available schemas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SchemaReference"
        "403":
          description: User has no schema visibility
  /api/v1/builder-schemas/{schema_id}/versions/{schema_version}/options:
    get:
      summary: Get normalized dropdown options for a builder and schema version
      parameters:
        - in: path
          name: schema_id
          required: true
          schema:
            type: string
        - in: path
          name: schema_version
          required: true
          schema:
            type: string
        - in: query
          name: builder
          required: true
          schema:
            type: string
            enum: [alert, report]
      responses:
        "200":
          description: Dropdown options
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SchemaOptionsResponse"
        "403":
          description: Access lost or denied for this schema
        "404":
          description: Schema reference not found
  /api/v1/builder-configurations/validate:
    post:
      summary: Validate builder selections against an active schema version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidationRequest"
      responses:
        "200":
          description: Validation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationResponse"
        "403":
          description: Access denied for schema reference
        "422":
          description: Invalid validation payload
components:
  schemas:
    SchemaReference:
      type: object
      required: [schema_id, schema_version]
      properties:
        schema_id:
          type: string
        schema_version:
          type: string
        product_name:
          type: string
        readable:
          type: boolean
    SchemaOption:
      type: object
      required: [key, label, selectable]
      properties:
        key:
          type: string
        label:
          type: string
        value_type:
          type: string
        order_index:
          type: integer
          minimum: 0
        selectable:
          type: boolean
    SchemaOptionsResponse:
      type: object
      required: [schema_id, schema_version, builder, options]
      properties:
        schema_id:
          type: string
        schema_version:
          type: string
        builder:
          type: string
          enum: [alert, report]
        options:
          type: array
          items:
            $ref: "#/components/schemas/SchemaOption"
        load_time_ms:
          type: integer
          minimum: 0
    ValidationRequest:
      type: object
      required: [builder, schema_id, schema_version, selections]
      properties:
        builder:
          type: string
          enum: [alert, report]
        schema_id:
          type: string
        schema_version:
          type: string
        selections:
          type: array
          items:
            type: object
            required: [slot_id, selected_key]
            properties:
              slot_id:
                type: string
              selected_key:
                type: string
    ValidationResponse:
      type: object
      required: [valid, issues, cleared_slot_ids]
      properties:
        valid:
          type: boolean
        issues:
          type: array
          items:
            $ref: "#/components/schemas/ValidationIssue"
        cleared_slot_ids:
          type: array
          items:
            type: string
    ValidationIssue:
      type: object
      required: [issue_code, message, blocking]
      properties:
        issue_code:
          type: string
          enum: [invalid_schema_field, schema_unavailable, schema_access_lost]
        message:
          type: string
        slot_id:
          type: string
          nullable: true
        blocking:
          type: boolean