openapi: 3.1.0
info:
  title: Compile API
  description: API for partially evaluating Rego queries in OPA (Open Policy Agent).
  version: 1.0.0
paths:
  /v1/compile:
    post:
      summary: Partially Evaluate a Query
      description: >-
        Partially evaluate a Rego query and obtain a simplified version of the
        policy.
      requestBody:
        description: Request to partially evaluate a query.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Query to partially evaluate and compile.
                  example: data.example.allow == true
                input:
                  type: object
                  description: Input document to use during partial evaluation.
                  example:
                    subject:
                      clearance_level: 4
                options:
                  type: object
                  description: Additional options for partial evaluation.
                  properties:
                    disableInlining:
                      type: array
                      items:
                        type: string
                  example:
                    disableInlining: []
                unknowns:
                  type: array
                  description: Terms to treat as unknown during partial evaluation.
                  items:
                    type: string
                  example:
                    - data.reports
      parameters:
        - name: pretty
          in: query
          required: false
          description: Format response for human readability.
          schema:
            type: boolean
        - name: explain
          in: query
          required: false
          description: Return query explanation.
          schema:
            type: string
            enum:
              - notes
              - fails
              - full
              - debug
        - name: metrics
          in: query
          required: false
          description: Return performance metrics.
          schema:
            type: boolean
        - name: instrument
          in: query
          required: false
          description: Instrument query evaluation and return additional metrics.
          schema:
            type: boolean
      responses:
        '200':
          description: Query partially evaluated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    description: Result of the partial evaluation.
                    properties:
                      queries:
                        type: array
                        description: Simplified queries.
                        items:
                          type: array
                          items:
                            type: object
                            properties:
                              index:
                                type: integer
                              terms:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                    value:
                                      type: object
          examples:
            always_true:
              summary: Query always true
              value:
                result:
                  queries:
                    - []
            partially_evaluated:
              summary: Partially evaluated query
              value:
                result:
                  queries:
                    - - index: 0
                        terms:
                          - type: ref
                            value:
                              - type: var
                                value: gte
                          - type: number
                            value: 4
                          - type: ref
                            value:
                              - type: var
                                value: data
                              - type: string
                                value: reports
                              - type: var
                                value: i1
                              - type: string
                                value: clearance_level
        '400':
          description: Bad request due to malformed input or query.
        '500':
          description: Internal server error.
components:
  schemas:
    PartialEvaluationResult:
      type: object
      properties:
        queries:
          type: array
          description: Partially evaluated queries.
          items:
            type: array
            items:
              type: object
              properties:
                index:
                  type: integer
                terms:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      value:
                        type: object