openapi: 3.0.0
info:
  contact:
    email: mark.wilkinson@upm.es
    name: Mark Wilkinson
    x-id: https://orcid.org/0000-0001-6960-357X
    x-role: responsible developer
  description: The FAIR Evaluator - automated testing of Web resources for their compliance
    with the FAIR Metrics
  license:
    name: CC0
    url: https://w3id.org/FAIR_Evaluator/license
  termsOfService: https://w3id.org/FAIR_Evaluator/terms
  title: FAIR Evaluator API
  version: 0.3.1
servers:
- description: The primary endpoint for the demonstration server
  url: https://w3id.org/FAIR_Evaluator
tags:
- name: FAIR Maturity Level Evaluation
paths:
  /collections:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collections_array'
          description: the requested Metric Collection
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
      summary: Retrieve all Metric Collections
      tags:
      - Retrieve Collections of Maturity Level Tests
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/collections'
        description: register a new collection of FAIR Metrics
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collections_result'
          description: A LDP-Container, in JSON-LD, describing the Metric Collection
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
          description: A response indicating an improperly formatted query
      summary: Create a new collection of Metrics to be used for Evaluations
      tags:
      - Create a Collection of Maturity Level Tests
  /collections/{collectionid}:
    get:
      parameters:
      - description: collection id (the Evaluator's internal id for this Metric Collection)
        example: '5'
        in: path
        name: collectionid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collections_result'
          description: the requested FAIR Metric Collection as an LDP Container
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '404':
          description: A response indicating an unknown collection id
      summary: Retrieve FAIR Metrics Collections by their Evaluator-id.
      tags:
      - Retrieve a Specific Maturity Test Collection
  /collections/{collectionid}/evaluate:
    post:
      parameters:
      - description: the collection being used for the evaluation
        example: '5'
        in: path
        name: collectionid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evaluate'
        description: The information pertaining to this evaluation
      responses:
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
          description: A response indicating an improperly formatted query
      summary: to register a new metric, send the smartURL to this endpiint
      tags:
      - Execute a Maturity Level Evaluation
  /evaluations/{evaluationid}/result:
    get:
      parameters:
      - description: evaluation id (the Evaluator's internal id for this evaluation)
        example: '5'
        in: path
        name: evaluationid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluation_result'
          description: the requested FAIR Metric
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '404':
          description: A response indicating an unknown evaluation id
      summary: Retrieve the result of an existing FAIR Evaluation
      tags:
      - Retrieve an Existing Maturity Level Evaluation
  /metrics:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metrics_array'
          description: the requested FAIR Metric
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
      summary: Retrieve all FAIR Maturity Level Tests
      tags:
      - Retrieve all Known Maturity Level Tests
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/metrics'
        description: The URL to the smartAPI descriptor of the Metric
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metrics_result'
          description: A description of the registered metric
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
          description: A response indicating an improperly formatted query
      summary: To register a new test, send the smartURL to this endpiint
      tags:
      - Register a New Maturity Level Test
  /metrics/{metricid}:
    get:
      parameters:
      - description: metric id (the Evaluator's internal id for this Metric)
        example: '5'
        in: path
        name: metricid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metrics_result'
          description: the requested FAIR Metric
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '404':
          description: A response indicating an unknown metric id
      summary: Retrieve FAIR Tests by their Evaluator-id.
      tags:
      - Retrieve a Specific Maturity Test Description
  /searches:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_schema'
          description: a JSON Schema document for how to post a search query, and the URL in the Location header
          headers:
            Location:
              schema:
                type: string
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
      summary: Create a new search URI to POST your search terms
      tags:
      - Search Maturity Tests and Collections by Keyword
 
  /searches/{myid}:
    parameters:
    - in: path
      required: true
      name: myid
      schema:
        type: string
      description: This URL is given to you in the Location header when you call POST on /searches
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchinput'
        description: submit keywords for a search
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchresult'
          description: a block of JSON containing two lists - a list of Maturity Tests,
            and a list of Collections - that match the search keywords
        '307':
          description: 307 redirect
          headers:
            Location:
              schema:
                type: string
        '302':
          description: 302 redirect
          headers:
            Location:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
          description: A response indicating an improperly formatted query
      summary: Execute a search over Maturity Indicator Test descriptions and Collection
        descriptions
      tags:
      - Search Maturity Tests and Collections by Keyword
      
      
      
components:
  schemas:
    ErrorResult:
      properties:
        errors:
          $ref: '#/components/schemas/errorblock'
        status:
          type: string
      type: object
    collections:
      properties:
        contact:
          type: string
          description: your ORCID (this is validated)
        description:
          type: string
        include_metrics:
          $ref: '#/components/schemas/metrics_list'
        name:
          type: string
        organization:
          type: string
      required:
      - name
      - contact
      - organization
      - include_metrics
      type: object
    collections_array:
      items:
        $ref: '#/components/schemas/collections_result'
      type: array
    collections_result:
      properties:
        '@id':
          type: string
        '@context':
          type: string
        '@type':
          type: array
          items:
            type: string
        http://purl.org/dc/elements/1.1/authoredBy:
          type: string
        http://purl.org/dc/elements/1.1/creator:
          type: string
        http://purl.org/dc/elements/1.1/license:
          type: string
        http://purl.org/dc/elements/1.1/title:
          type: string
        http://purl.org/pav/version:
          type: string
        http://rdfs.org/ns/void#description:
          type: string
        http://www.w3.org/ns/dcat#contactPoint:
          type: string
        http://www.w3.org/ns/dcat#entities:
          type: string
        http://www.w3.org/ns/dcat#identifier:
          type: string
        http://www.w3.org/ns/dcat#publisher:
          type: string
        http://www.w3.org/ns/ldp#contains:
          $ref: '#/components/schemas/metrics_list'
    errorblock:
      items:
        type: string
      type: array
    evaluate:
      properties:
        executor:
          type: string
        resource:
          type: string
        title:
          type: string
      required:
      - resource
      - executor
      - title
      type: object
    evaluation_result:
      type: string
    ids:
      properties:
        '@id':
          type: string
    metrics:
      properties:
        smarturl:
          type: string
      required:
      - smarturl
      type: object
    metrics_array:
      items:
        $ref: '#/components/schemas/metrics_result'
      type: array
    metrics_list:
      type: array
      items:
        type: string
    metrics_result:
      properties:
        '@id':
          type: string
        '@type':
          type: array
          items:
            type: string
        '@context':
          type: string
        created_at:
          type: string
        creator:
          type: string
        email:
          type: string
        name:
          type: string
        principle:
          type: string
        smarturl:
          type: string
        updated_at:
          type: string

    search_schema:
      properties:
        properties:
          type: string
    searchinput:
      properties:
        keywords:
          type: string
    searchresult:
      properties:
        collections:
          items:
            $ref: '#/components/schemas/collections_result'
          type: array
        metrics:
          items:
            $ref: '#/components/schemas/metrics_result'
          type: array
