rpc-schema.yaml

---
$schema: http://json-schema.org/draft-07/schema#
title: Search2 Method Schemas
definitions:

  # JSON Schema definitions for every RPC method in this service
  methods:
    # Display public configuration details for the services
    show_config:
      params: {}
      result: {}

    # Get a list of index and alias names in elasticsearch
    show_indexes:
      params: {}
      result:
        type: array
        items:
          type: object
          required: [name, count]
          additionalProperties: false
          properties:
            name:
              title: Index name
              type: string
            count:
              title: Document count
              type: integer

    search_workspace:
      params:
        type: object
        required: []
        additionalProperties: false
        properties:
          types:
            title: Types
            description: |
              Unversioned workspace type names to search against. Defaults to
              search against all available types.
            type: array
            items: {type: string}
          include_fields:
            title: Include Fields
            description: |
              What fields to include in the results. Supports wildcards. If
              empty, null, or absent, then all fields are returned.
            examples:
              - ["field1", "field2", "field3"]
            type: array
            items: {type: string}
          search:
            title: Search Query
            description: Generic search query string
            examples:
              - "foo | bar + baz*"
            type: object
            required: [query]
            additionalProperties: false
            properties:
              query:
                type: string
                description: Uses Elasticsearch's Simple Query String syntax
              fields:
                type: array
                items: {type: string}
                default: ["agg_fields"]
          sorts:
            title: Sorts
            description: Fields to use for sorting results
            examples:
              - [[field1, asc], [field2, desc]]
            type: array
            default: [["_score", "desc"]]
            items:
              type: array
              minLength: 2
              maxLength: 2
              items:
                - {type: string, title: "Field Name"}
                - type: string
                  title: Sort direction
                  enum: ["asc", "desc"]
          filters:
            "$ref": "#/definitions/filter_clause"
          paging:
            type: object
            additionalProperties: false
            default: {length: 10, offset: 0}
            properties:
              length:
                type: integer
                default: 10
              offset:
                type: integer
                default: 0
          access:
            type: object
            additionalProperties: false
            default: {only_public: false, only_private: false}
            properties:
              only_public:
                type: boolean
                description: Only return public documents. No auth needed.
              only_private:
                type: boolean
                description: Only return private documents and no public. Auth required.
          track_total_hits:
            type: boolean
            title: Track total hits
            description: Track the true total of hits. Bypasses the 10k count limit.
      # End of search_workspace.params
      result:
        type: object
        required: [count, hits, search_time]
        additionalProperties: false
        properties:
          count:
            description: Total count of results
            type: integer
            minimum: 0
          search_time:
            description: |
              Time in milliseconds that the request took for processing on
              Elasticsearch
            type: integer
            minimum: 0
          hits:
            type: array
            items: {type: object}
    # End of search_workspace

    # Generic search of all objects under an index or alias
    search_objects:
      params:
        type: object
        required: []
        additionalProperties: false
        properties:
          query:
            # Reference: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html
            type: object
            description: Query options
          source:
            type: array
            description: Which fields to return in the results
          indexes:
            type: array
            items:
              type: string
            description: An array of index/alias names you want to search
          only_public:
            type: boolean
            description: Only return public documents. No auth needed.
          only_private:
            type: boolean
            description: Only return private documents and no public. Auth required.
          size:
            type: integer
            title: Page Size
            description: Number of results to return
            default: 10
          from:
            type: integer
            title: Offset
            description: How many records to skip in the results for pagination.
            default: 0
          count:
            type: integer
            description: Just count the results without returning the documents.
          aggs:
            type: object
            title: Aggregations
          highlight:
            # Reference:
            # https://www.elastic.co/guide/en/elasticsearch/reference/7.5/search-request-body.html#request-body-search-highlighting
            type: object
            additionalProperties: false
            description: Result highlight options
            properties:
              fields:
                type: object
              require_field_match:
                type: boolean
              highlight_query:
                type: object
          track_total_hits:
            type: boolean
            title: Track total hits
            description: Track the true total of hits. Gets past 10000 document limit if True
          sort:
            # Reference: https://www.elastic.co/guide/en/elasticsearch/reference/7.5/search-request-body.html#request-body-search-sort
            type: array
            description: Sorting options for result. An array of property names.
            items:
              anyOf:
                - type: string
                - type: object
                  patternProperties:
                    ".*":
                      type: object
                      additionalProperties: false
                      properties:
                        order:
                          type: string
                          enum: [desc, asc]
      # search_objects result schema
      result:
        type: object
        required: [count, hits, search_time, aggregations]
        additionalProperties: false
        properties:
          count:
            description: Total count of results
            type: integer
          search_time:
            type: integer
            description: Time in milliseconds that the request took for processing on Elasticsearch
          aggregations:
            type: object
            patternProperties:
              # The key will be the aggregator name
              ".*":
                type: object
                additionalProperties: false
                properties:
                  count_err_upper_bound:
                    type: integer
                    description: Upper bound on the count inaccuracy for each aggregation
                  count_other_docs:
                    type: integer
                    description: Count of docs that were not aggregated
                  counts:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        count: {type: integer}
                        key:
                          type: string
                          description: Aggregation group identifier (eg. field name)
          hits:
            type: array
            items:
              type: object
              required: [id, index, doc]
              additionalProperties: false
              properties:
                id:
                  description: "Elasticsearch document id (stored as '_id')"
                  type: string
                index:
                  title: Index name
                  type: string
                doc:
                  description: Content of the document -- the actual fields and values.
                  type: object
                highlight:
                  description: Field values with search match highlighting using <em> tags.
                  type: object
                  patternProperties:
                    ".*":
                      type: array
                      items: {type: string}
  # End of search_objects

  # Non-method definitions

  filter_clause:
    title: Filter Clause
    description: Filters applied to one or more fields with boolean operators
    examples:
      - {field: "field1", term: "xyz"}
      - {operator: AND, fields: [{field: field1, term: xyz}, {field: field2, term: abc}]}
    anyOf:
      - {"$ref": "#/definitions/filter_bool"}
      - {"$ref": "#/definitions/filter_field"}

  filter_bool:
    title: Filter Boolean
    description: Filter multiple fields joined by a boolean operator
    examples:
      - {operator: AND, fields: [{field: field1, term: xyz}, {field: field2, term: abc}]}
    type: object
    additionalProperties: false
    required: [fields, operator]
    properties:
      operator:
        type: string
        enum: ["AND", "OR"]
      fields:
        type: array
        items:
          anyOf:
            - {"$ref": "#/definitions/filter_bool"}
            - {"$ref": "#/definitions/filter_field"}

  filter_field:
    title: Filter Single Field
    description: A filter on a specific field
    examples:
      - {field: "field1", term: "xyzvalue"}
      - {field: "field1", range: {min: 10, max: 100}}
    type: object
    additionalProperties: false
    required: [field]
    properties:
      field: {type: string}
      range:
        type: object
        additionalProperties: false
        properties:
          max:
            anyOf: [{type: integer}, {type: number}]
          min:
            anyOf: [{type: integer}, {type: number}]
      term: {"$ref": "#/definitions/scalar_type"}
      not_term: {"$ref": "#/definitions/scalar_type"}

  scalar_type:
    anyOf:
      - type: number
      - type: integer
      - type: string
      - type: boolean
      - type: "null"