model_service_api.yaml

openapi: 3.0.0
info:
  title: "ModelService API"
  description: "This API specification is for the World Modelers Modeling Service System. The goal of this API is to provide a controller for model discovery and exploration, as well as for initializing and managing model runs."
  version: "1.0.0"
  
servers:
  - url: https://model-service.worldmodelers.com
    description: Future (production) server
  - url: http://localhost:8080
    description: Local server for testing
  
paths:
  /list_models:
    post:
      tags:
      - "exploration"
      summary: "Obtain a list of current models"
      description: "Request a list of currently available models."
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableModels'
  /model_info/{ModelName}:
    get:
      tags:
      - "exploration"
      summary: "Get basic metadata information for a specified model."
      description: "Submit a model name and receive metadata information about the model, such as its purpose, who maintains it, and how it can be run."
      parameters:
      - in: path
        name: ModelName
        description: "The name of a model."
        required: true
        schema:
          $ref: "#/components/schemas/ModelName"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
  /model_outputs/{ModelName}:
    get:
      tags:
      - "exploration"
      summary: "Obtain information on a given model's outputs."
      description: "Submit a model name and receive information about the output variables produced by this model."
      parameters:
      - in: path
        name: ModelName
        description: "The name of a model."
        required: true
        schema:
          $ref: "#/components/schemas/ModelName"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/Variable'
  /model_parameters/{ModelName}:
    get:
      tags:
      - "exploration"
      summary: "Obtain information about a model's parameters."
      description: "Submit a model name and receive information about the parameters used by this model. Specific parameters are used on a per-configuration basis."
      parameters:
      - in: path
        name: ModelName
        description: "The name of a model."
        required: true
        schema:
          $ref: "#/components/schemas/ModelName"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/Parameter'
  /model_config/{ModelName}:
    get:
      tags:
      - "exploration"
      summary: "Obtain configurations for a given model."
      description: "Submit a model name and receive all configurations for the given model."
      parameters:
      - in: path
        name: ModelName
        description: "The name of a model."
        required: true
        schema:
          $ref: "#/components/schemas/ModelName"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelConfig'
  /list_concepts:
    get:
      tags:
      - "concepts"
      summary: "Obtain a list of available concepts"
      description: >
        Request a list of currently available concepts. These are derived from the list of 
        [UN indicators](https://github.com/WorldModelers/Ontologies/blob/master/performer_ontologies/un_to_indicators.tsv) and are tied to model output variables.
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableConcepts'
  /concept_mapping:
    get:
      tags:
      - "concepts"
      summary: "Obtain an array of models related to a concept."
      description: >
        Submit a concept name and optional type and receive an array of concepts
        related to that concept.      
      parameters:
      - in: query
        name: concept
        description: "A concept name"
        required: false
        schema:
          $ref: "#/components/schemas/ConceptName"      
      - in: query
        name: concept_type
        description: The type of concept objects to return
        schema:
          type: string
          enum:
            - "model"
            - "output"
            - "parameter"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConceptMapping'   
  /run_model:
    post:
      tags:
      - "execution"
      summary: "Run a model for a given a configuration"
      description: "Submit a configuration to run a specific model. Model is run asynchronously. Results are available through `/run_results` endpoint. Note that the `requestBody` must include a `config` object which should have as its `keys` the appropriate model `parameter` `labels`. Each `key` should have a corresponding `parameter` `value`. If a `parameter` is missing it will be defaulted."
      requestBody:
        description: "Model and configuration parameters"
        required: true
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/ModelConfig"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunID"
  /run_status/{RunID}:
    get:
      tags:
      - "execution"
      summary: "Obtain status for a given model run"
      description: "Submit a `RunID` and receive the model run status"
      parameters:
      - in: path
        name: RunID
        description: "The `ID` for a given model run."
        required: true
        schema:
          $ref: "#/components/schemas/RunID"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStatus'
  /run_results/{RunID}:
    get:
      tags:
      - "execution"
      summary: "Obtain metadata about the results of a given model run"
      description: "Submit a `RunID` and receive model run results metadata, including whether it succeeded or failed and where to access the result data."
      parameters:
      - in: path
        name: RunID
        description: "The ID for a given model run."
        required: true
        schema:
          $ref: "#/components/schemas/RunID"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResults'
  /list_runs/{ModelName}:
    get:
      tags:
      - "execution"
      summary: "Obtain a list of runs for a given model"
      description: "Submit a `ModelName` and receive an array of `RunID`s associated with the given model."
      parameters:
      - in: path
        name: ModelName
        description: "A model name"
        required: true
        schema:
          $ref: "#/components/schemas/ModelName"
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/RunID'
  /available_results:
    get:
      tags:
      - "execution"
      summary: "Obtain a list of run results"
      description: "Return a list of all available run results."
      parameters:
      - in: query
        name: ModelName
        description: "A model name"
        required: false
        schema:
          $ref: "#/components/schemas/ModelName"      
      - in: query
        name: size
        description: The maximum number of results to return.
        schema:
          type: integer
      responses:
        200:
          description: "SUCCESS"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/RunResults'                   
  /result_file/{ResultFileName}:
    get:
      tags:
      - "execution"
      summary: "Obtain the result file for a given model run."
      description: "Submit a `ResultFileName` and receive model run result file."
      parameters:
      - in: path
        name: ResultFileName
        description: "A file name of a result file."
        required: true
        schema:
          $ref: "#/components/schemas/ResultFileName"
      responses:
        '200':
          description: A result file

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    ModelName:
      type: "string"
      description: "A model's name"
      example: "FSC" 
    StandardName:
      type: "object"
      description: "A standard name representation"
      required:
        - "standard_variable_id"
        - "standard_variable_name"
        - "standard_variable_uri"
      properties:
        standard_variable_id:
          type: "string"
          description: "The MINT UUID associated with the standard name"
          example: "df1daca4-d727-5dc8-bfa4-fb20c717a32b"
        standard_variable_name:
          type: "string"
          description: "The natural language name for a standard name"
          example: "year"
        standard_variable_uri:
          type: "string"
          description: "The URI associated with the standard name"
          example: "http://www.geoscienceontology.org/svo/svl/property#year"
    Model:
      type: "object"
      required:
      - "name"
      - "description"
      - "maintainer"
      - "label"
      description: "An object defining high-level metadata about a model"
      properties:
        name:
          $ref: '#/components/schemas/ModelName'
        label: 
          type: "string"
          description: "The human readable name of the model"
        versions:
          type: "array"
          items:
            type: "string"
          example: ["1.1", "1.2", "LATEST"]
          description: "Latest model version"
        maintainer:
          type: "string"
          description: "Maintainer information for this model. Should include institution name and point of contact."
          example: "Michael Puma, Columbia University"
        description:
          type: "string"
          description: "A basic overview of the model's purpose."
          example: "FSC single country shock configuration."
        category: 
          # this may ultimately be an enumerated (fixed) string 
          # e.g. select from one of the following (from ontology)
          type: "array"
          description: "The category for the given model."
          items:
            type: "string"
          example: ["Agriculture", "Economic"]
    AvailableModels:
      type: "array"
      items:
        $ref: '#/components/schemas/Model'
      uniqueItems: true
      description: "An array of available models"
    ModelConfig:
      # this can be an example config, or a config submitted to execute
      # a job. This is loosely defined for the time being.
      # note that the `valid` and `error` fields should only be 
      # completed when associated with the `validate_config` endpoint
      type: "object"
      description: "A model configuration file (JSON)."
      required:
        - "name"
        - "config"
      properties:
        name: 
          $ref: '#/components/schemas/ModelName'
        config:
          type: "object"
    Variable:
    # the variable can have arbitrary information stored in its metadata field
      type: "object"
      description: "A variable used in a model input or output file."
      required:
        - "name"
        - "description"
      properties:
        name: 
          type: "string"
        description:
          type: "string"
        units:
          type: "string"
        metadata:
          type: "object"
    Parameter:
      type: "object"
      description: "A user configurable model parameter"
      required:
        - "name"
        - "description"
      properties:
        name:
          type: "string"
          description: "The name of the parameter"
          example: "crop"
        description: 
          type: "string"
          description: "Natural language description of parameter"
          example: "Choose the crop of interest from one of [millet, maize, wheat]."
        type:
          type: "string"
          description: "The parameter's type"
          example: "StringParameter"
          enum: 
            - NumberParameter
            - ChoiceParameter
            - TimeParameter
            - GeoParameter
            - StringParameter
        default_value:
          description: "The parameter's default value. Type depends on the parameter's type."
          example: "maize"
        minimum:
          description: "The parameter's minimum allowed value. Type depends on the parameter's type."
        maximum:
          description: "The parameter's maximum allowed value. Type depends on the parameter's type."
        choices:
          type: "array"
          items:
            oneOf:
              - type: string
              - type: integer
          description: An array of choices available for a parameter of type ChoiceParameter
          example: ["millet", "maize", "wheat"]
    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"
    RunID:
      type: "string"
      description: "ID associated with a model run. This is the SHA256 hash of the ModelConfig sent to the /run_model endpoint"
      example: "3A3B3E0AE57AD4A7EF658C1F7832774F55E403F01FDF44B68B355EC4587D7A04"
    ResultFileName:
      type: "string"
      description: "The name of a model run result file."
      example: "3A3B3E0AE57AD4A7EF658C1F7832774F55E403F01FDF44B68B355EC4587D7A04.csv"      
    RunStatus:
      type: "string"
      description: "Status information about a model run."
      enum:
        - "PENDING"
        - "FAIL"
        - "SUCCESS"
    RunResults:
      type: "object"
      description: "Metadata about the results of a given model run."
      required:
        - "config"
        - "status"
        - "output"
      properties:
        config:
          $ref: "#/components/schemas/ModelConfig"
        status:
          type: "string"
          enum: ["SUCCESS", "FAIL", "PENDING"]
        output:
          type: "string"
          description: "URI for accessing output (for example, on S3)"
        auth_required:
          description: "Does accessing this model output require authentification? True if requires auth."
          type: boolean
        timestamp:
          description: "Epoch timestamp when the model run was initiated (epoch millis)"
          type: integer
    Error:
      type: "object"
      description: "Arbitrary error object."
    ConceptName:
      type: "string"
      description: "A concept's name"
      example: "precipitation"
    Concept:
      type: "object"
      description: "A model, parameter, or output variable related to a concept"
      required:
        - "name"
        - "score"
        - "type"
      properties:
        name:
          type: "string"
          description: "The object name"
        score:
          type: "number"
          description: "The score for the object in relation to the concept (higher is closer match)"
        type:
          type: "string"
          description: "Whether the object is related to a model, parameter, or output"
          enum: 
            - "model"
            - "output"
            - "parameter"
    AvailableConcepts:
      type: "array"
      items:
        $ref: "#/components/schemas/ConceptName"
      uniqueItems: true
      description: "An array of available concept names"
    ConceptMapping:
      type: "array"
      description: >
        An array of objects (models, output variables, or parameters) that relate to a concept
      items:
        $ref: "#/components/schemas/Concept"