openapi: 3.1.0
info:
  title: Biomedical Evidence Metrics Ontology API
  version: 0.1.0
  description: >
    Draft API contract for browsing BEMO and executing only computation profiles
    whose formula or external protocol has been validated and approved.
servers:
  - url: https://api.example.org/bemo
    description: Placeholder; replace before deployment.
paths:
  /v1/metrics:
    get:
      summary: List metrics
      parameters:
        - in: query
          name: category_id
          schema: {type: string}
        - in: query
          name: computation_readiness
          schema: {type: string}
      responses:
        '200':
          description: Metric collection
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://w3id.org/bemo/schemas/bemo-metric-record.schema.json'
  /v1/metrics/{metric_id}:
    get:
      summary: Retrieve a metric and its computation profile
      parameters:
        - in: path
          name: metric_id
          required: true
          schema:
            type: string
            pattern: '^BEMO:[0-9]{7}$'
      responses:
        '200':
          description: Metric record
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/bemo/schemas/bemo-metric-record.schema.json'
        '404':
          description: Metric not found
  /v1/metrics/{metric_id}/compute:
    post:
      summary: Compute a metric using its approved computation profile
      description: >
        Generic template computation is supported only where formula_status is
        GenericTemplateDefined. Other profiles require a registered, validated
        external protocol and must return 422 until such a protocol is supplied.
      parameters:
        - in: path
          name: metric_id
          required: true
          schema:
            type: string
            pattern: '^BEMO:[0-9]{7}$'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [inputs, evidence_snapshot_id]
              properties:
                inputs: {type: object}
                evidence_snapshot_id: {type: string}
                assessed_object: {type: object}
      responses:
        '200':
          description: Computed metric assessment
          content:
            application/ld+json:
              schema:
                $ref: 'https://w3id.org/bemo/schemas/bemo-assessment.schema.json'
        '422':
          description: Metric requires a curated external protocol or missing inputs
  /v1/validate/assessment:
    post:
      summary: Validate a BEMO assessment
      requestBody:
        required: true
        content:
          application/ld+json:
            schema:
              $ref: 'https://w3id.org/bemo/schemas/bemo-assessment.schema.json'
      responses:
        '200':
          description: Validation report
components: {}