world-modeler-search.yaml

openapi: 3.0.0
info:
  title: "World Modelers Search API"
  description: "This API specification is for the World Modelers search."
  version: "1.0.0"

paths:
  /search:
    post:
      tags: 
      - "exploration"
      summary: "Search for a model, dataset, or variable"
      description: "Search for a model, dataset, or variable based on name or standard name"
      requestBody:
        description: "Search parameters"
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/GeoQuery"
                - $ref: "#/components/schemas/TimeQuery"
                - $ref: "#/components/schemas/TextQuery"
              discriminator:
                propertyName: query_type
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        400:
          description: "ERROR"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    SearchResult:
      type: "array"
      description: "The result of a search"
      items:
        type: "object"
    Query:
      type: "object"
      required:
        - "query_type"
        - "result_type"
      discriminator: 
        propertyName: query_type
      properties:
        query_type:
          type: "string"
          description: "Is this a geo, time or text query?"
          enum: ["geo", "time", "text"]
        result_type:
          type: "string"
          description: "Should the query return models, datasets, or variables?"
          enum: ["models", "datasets", "variables"]  
    GeoQuery:
      allOf: 
        - $ref: "#/components/schemas/Query"
        - type: "object"
          description: "A geospatial bounding box search parameter is 4-elements in the WGS84 coordinate system: [xmin, ymin, xmax, ymax]. x is longitude, y is latitude"
          required:
            - "xmin"
            - "xmax"
            - "ymin"
            - "ymax"
            - "result_type"
          properties:
            xmin:
              description: "Minimum longitude"
              type: "number"
            xmax:
              description: "Maximum longitude"
              type: "number"
            ymin:
              description: "Minimum latitude"
              type: "number"
            ymax:
              description: "Maximum latitude"
              type: "number"
    TimeQuery:
      allOf:
        - $ref: "#/components/schemas/Query"
        - type: "object"      
          description: "A query defined by a start and end time."
          required:
            - "start_time"
            - "end_time"
          properties:
            start_time:
              description: "Minimum time for search query."
              type: "string"
            end_time:
              description: "Maximum time for search query"
              type: "string"
    TextQuery:
      allOf:
        - $ref: "#/components/schemas/Query"
        - type: "object"      
          description: "A text string based query."
          required:
            - "type"
            - "term"
          properties:
            type: 
              description: "The type of query (either keyword or standard name)"
              type: "string"
              enum:
                - "keyword"
                - "standard name"
            term:
              description: "The search term of interest."
              type: "string"
    Error:
      type: "object"
      description: "Arbitrary error object."
    ConceptName:
      type: "string"
      description: "A concept's name"
      example: "precipitation"