{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-unified-search-schema.json",
  "title": "UnifiedSearch",
  "description": "One query across peptides, checked findings, stored papers and trials. Each list shows the top results only.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-openapi.json#/components/schemas/UnifiedSearch",
  "type": "object",
  "properties": {
    "credit": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "enum": [
            "Data from PepBank"
          ]
        },
        "line": {
          "type": "string",
          "description": "Credit sentence. Copy it as written."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "PepBank page for this result. The home page applies when no single page fits."
        },
        "license_url": {
          "type": "string",
          "enum": [
            "https://creativecommons.org/licenses/by/4.0/"
          ]
        }
      },
      "required": [
        "text",
        "url",
        "license_url"
      ]
    },
    "record_type": {
      "type": "string",
      "enum": [
        "unified_search"
      ]
    },
    "query": {
      "type": "string"
    },
    "data_seq": {
      "type": "integer"
    },
    "peptides": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "featured": {
            "type": "boolean"
          },
          "one_liner": {
            "type": [
              "string",
              "null"
            ]
          },
          "sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "length": {
            "type": [
              "integer",
              "null"
            ]
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "regulatory_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "A sort key, never an answer: it does not say where. Quote approval instead."
          },
          "approval": {
            "type": "string",
            "description": "Approval status in words, with the places: for example \"Approved in the US and EU (Ozempic, 2017)\". Quote it as written; never write only the word approved."
          },
          "highest_phase": {
            "type": [
              "string",
              "null"
            ]
          },
          "stats": {
            "type": "object",
            "properties": {
              "publications": {
                "type": "integer"
              },
              "publications_checked": {
                "type": "integer",
                "description": "In-scope linked papers with extraction_status extracted, with or without findings."
              },
              "findings": {
                "type": "integer"
              },
              "by_class": {
                "type": "object",
                "properties": {
                  "human": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "animal": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "laboratory": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "predicted": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  }
                },
                "required": [
                  "human",
                  "animal",
                  "laboratory",
                  "predicted"
                ]
              },
              "trials": {
                "type": "integer",
                "description": "Registered trials that test the peptide (role tests: it is among the interventions). Registry entries that only measure or mention it are in trials_other."
              },
              "trials_active": {
                "type": "integer",
                "description": "Trials that test the peptide and are recruiting, not yet recruiting, active or enrolling by invitation."
              },
              "trials_other": {
                "type": "integer",
                "description": "Registry entries that name the peptide but do not test it: it is only a measured level or an eligibility term (measures), or named in the text (mentions). They are not trials of the peptide. Say \"<n> more trial records measure or name it but do not test it\"."
              },
              "latest_publication": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "retracted_publications": {
                "type": "integer"
              },
              "out_of_scope": {
                "type": "integer",
                "description": "Stored papers that are out of scope for this peptide by a scope policy (for example oxytocin_childbirth_v1). PepBank does not check them, and they are not part of any \"not checked yet\" count. publications still counts every stored paper."
              },
              "evidence_level": {
                "type": "string",
                "enum": [
                  "human_rct",
                  "human_other",
                  "animal",
                  "laboratory",
                  "predicted",
                  "none"
                ],
                "description": "From checked findings of studies that gave the peptide only: human_rct, human_other, animal, laboratory, predicted or none. A registered trial, a trial phase or an approval never raises it."
              },
              "registry_level": {
                "type": "string",
                "enum": [
                  "approved",
                  "phase_4",
                  "phase_3",
                  "phase_2",
                  "phase_1",
                  "registered",
                  "none"
                ],
                "description": "From the registered trials that test the peptide and the curated development phase: approved (somewhere, for some use), phase_4, phase_3, phase_2, phase_1, registered or none. It says nothing about results. Never show approved as a bare Approved: use the regulatory block."
              },
              "human_rct_findings": {
                "type": "integer",
                "description": "Checked findings from randomized controlled trials in people, from studies that gave the peptide. Basis of the evidence level human_rct."
              },
              "trials_top_phase": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "phase_4",
                  "phase_3",
                  "phase_2",
                  "phase_1",
                  null
                ],
                "description": "Highest phase among the registered trials that test the peptide. Null when none has a phase. Early phase 1 counts as phase_1."
              },
              "endogenous_findings": {
                "type": "integer",
                "description": "Checked findings that measure the body's own peptide. They are not counted in findings or by_class."
              }
            },
            "required": [
              "publications",
              "findings",
              "by_class",
              "trials",
              "trials_active",
              "latest_publication",
              "retracted_publications",
              "evidence_level"
            ],
            "additionalProperties": {}
          },
          "match": {
            "type": "string"
          },
          "typed_as": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Words of the query that are near names of this peptide (typing errors found by edit distance). A guess: show the matched name."
          }
        },
        "required": [
          "id",
          "slug",
          "name",
          "kind",
          "category",
          "featured",
          "one_liner",
          "sequence",
          "length",
          "aliases",
          "regulatory_status",
          "highest_phase",
          "stats",
          "match"
        ],
        "additionalProperties": {}
      }
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "finding": {
            "type": "object",
            "properties": {
              "record_type": {
                "type": "string",
                "enum": [
                  "finding"
                ]
              },
              "finding_id": {
                "type": "string"
              },
              "publication_id": {
                "type": "string"
              },
              "peptide": {
                "type": "object",
                "properties": {
                  "peptide_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "peptide_id"
                ],
                "additionalProperties": {}
              },
              "evidence_class": {
                "type": "string",
                "enum": [
                  "human",
                  "animal",
                  "laboratory",
                  "predicted"
                ],
                "description": "Evidence class: human, animal, laboratory or predicted."
              },
              "evidence_detail": {
                "type": "object",
                "properties": {
                  "design": {
                    "type": "string"
                  }
                },
                "required": [
                  "design"
                ],
                "additionalProperties": {}
              },
              "claim": {
                "type": "object",
                "properties": {
                  "claim_type": {
                    "type": "string"
                  },
                  "outcome": {
                    "type": "string"
                  },
                  "direction": {
                    "type": "string"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "statement_plain": {
                    "type": "string",
                    "description": "Plain-language restatement for non-specialists (v0.3). It adds no facts."
                  },
                  "outcome_group": {
                    "type": "string",
                    "description": "Normalized outcome group, for example Wound healing (v0.3)."
                  },
                  "body_system": {
                    "type": "string",
                    "description": "Body system, for example Musculoskeletal (v0.3)."
                  },
                  "peptide_role": {
                    "type": "string",
                    "enum": [
                      "administered",
                      "endogenous_level",
                      "other"
                    ],
                    "description": "Role of the peptide in the study (extraction prompt v0.4). Only administered findings are evidence about taking the peptide. endogenous_level findings measure the body's own peptide."
                  }
                },
                "additionalProperties": {}
              },
              "measurements": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "intervention": {
                "type": "object",
                "properties": {},
                "additionalProperties": {}
              },
              "source_passages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "passage_id": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "passage_id",
                    "role"
                  ],
                  "additionalProperties": {}
                }
              },
              "validation": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "additionalProperties": {}
              },
              "source_status": {
                "type": "string"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "integer"
                  },
                  "valid_from_seq": {
                    "type": "integer"
                  },
                  "valid_to_seq": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "record_hash": {
                    "type": "string"
                  }
                },
                "required": [
                  "version",
                  "valid_from_seq",
                  "valid_to_seq",
                  "created_at",
                  "record_hash"
                ],
                "additionalProperties": {}
              }
            },
            "required": [
              "record_type",
              "finding_id",
              "publication_id",
              "evidence_class"
            ],
            "additionalProperties": {},
            "description": "One claim from one source, with the source sentences that support it."
          },
          "publication": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "pmid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "pmcid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "doi": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "journal": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "pub_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "design_hint": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "PubMed publication-type tag of the paper (for example rct or review), not checked. It is the label of the journal record, not a finding. For the design, species and peptide role of the checked findings, read profile."
              },
              "status": {
                "type": "string"
              },
              "is_open_access": {
                "type": "boolean"
              },
              "license": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oa_pdf_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oa_landing_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cited_by_count": {
                "type": "integer"
              },
              "first_author": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "extraction_status": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "pmid",
              "pmcid",
              "doi",
              "title",
              "journal",
              "year",
              "pub_date",
              "design_hint",
              "status",
              "is_open_access",
              "license",
              "oa_pdf_url",
              "oa_landing_url",
              "cited_by_count",
              "first_author",
              "extraction_status"
            ],
            "additionalProperties": {}
          },
          "passages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "passage_id": {
                  "type": "string"
                },
                "role": {
                  "type": "string"
                },
                "section": {
                  "type": "string"
                },
                "text": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Source sentence. Null when the license does not allow the text (see withheld)."
                },
                "withheld": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "passage_id",
                "role",
                "section",
                "text",
                "withheld"
              ]
            }
          },
          "peptide": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "slug",
              "name"
            ]
          }
        },
        "required": [
          "finding",
          "publication",
          "passages",
          "peptide"
        ],
        "additionalProperties": {}
      }
    },
    "publications": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "pmid": {
            "type": [
              "string",
              "null"
            ]
          },
          "pmcid": {
            "type": [
              "string",
              "null"
            ]
          },
          "doi": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "journal": {
            "type": [
              "string",
              "null"
            ]
          },
          "year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "pub_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "design_hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "PubMed publication-type tag of the paper (for example rct or review), not checked. It is the label of the journal record, not a finding. For the design, species and peptide role of the checked findings, read profile."
          },
          "status": {
            "type": "string"
          },
          "is_open_access": {
            "type": "boolean"
          },
          "license": {
            "type": [
              "string",
              "null"
            ]
          },
          "oa_pdf_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "oa_landing_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "cited_by_count": {
            "type": "integer"
          },
          "first_author": {
            "type": [
              "string",
              "null"
            ]
          },
          "extraction_status": {
            "type": "string"
          },
          "finding_count": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "pmid",
          "pmcid",
          "doi",
          "title",
          "journal",
          "year",
          "pub_date",
          "design_hint",
          "status",
          "is_open_access",
          "license",
          "oa_pdf_url",
          "oa_landing_url",
          "cited_by_count",
          "first_author",
          "extraction_status",
          "finding_count"
        ],
        "additionalProperties": {}
      }
    },
    "trials": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "nct": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "acronym": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "phases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "study_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "enrollment": {
            "type": [
              "integer",
              "null"
            ]
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "primary_completion_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "completion_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "start_date_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "actual",
              "estimated",
              null
            ],
            "description": "The registry's type for this date. \"estimated\" is a plan, not a fact: a completion date of type estimated has not happened. Null when the registry gives no type."
          },
          "primary_completion_date_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "actual",
              "estimated",
              null
            ],
            "description": "The registry's type for this date. \"estimated\" is a plan, not a fact: a completion date of type estimated has not happened. Null when the registry gives no type."
          },
          "completion_date_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "actual",
              "estimated",
              null
            ],
            "description": "The registry's type for this date. \"estimated\" is a plan, not a fact: a completion date of type estimated has not happened. Null when the registry gives no type."
          },
          "sponsor": {
            "type": [
              "string",
              "null"
            ]
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "has_results": {
            "type": "boolean"
          },
          "last_update": {
            "type": [
              "string",
              "null"
            ]
          },
          "peptides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "tests",
                    "measures",
                    "mentions"
                  ],
                  "description": "How the trial relates to this peptide: tests, measures or mentions. Only tests is a trial of the peptide."
                }
              },
              "required": [
                "id",
                "slug",
                "name"
              ]
            },
            "description": "Peptides that the trial tests (role tests). Empty when the trial only measures or mentions a tracked peptide."
          },
          "related_peptides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "tests",
                    "measures",
                    "mentions"
                  ],
                  "description": "How the trial relates to this peptide: tests, measures or mentions. Only tests is a trial of the peptide."
                }
              },
              "required": [
                "id",
                "slug",
                "name"
              ]
            },
            "description": "Peptides that the trial only measures or mentions (role measures or mentions). The trial is not a trial of these peptides: do not present it as one."
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "nct",
          "title",
          "acronym",
          "status",
          "phases",
          "study_type",
          "enrollment",
          "start_date",
          "primary_completion_date",
          "completion_date",
          "sponsor",
          "conditions",
          "has_results",
          "last_update",
          "peptides",
          "url"
        ],
        "additionalProperties": {}
      }
    },
    "counts": {
      "type": "object",
      "properties": {
        "findings": {
          "type": "integer"
        },
        "publications": {
          "type": "integer"
        },
        "trials": {
          "type": "integer"
        }
      },
      "required": [
        "findings",
        "publications",
        "trials"
      ],
      "description": "Exact numbers of checked findings, stored papers and trials that contain the search words, under the same filters as the lists. trials counts trials that test a peptide (role tests); other registry entries are in registry_other."
    },
    "registry_other": {
      "type": "object",
      "properties": {
        "measures": {
          "type": "integer",
          "minimum": 0,
          "description": "Trials where the peptide is only a measured level or an eligibility term."
        },
        "mentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Trials that name the peptide in the title, the summary or a free-text description only."
        },
        "total": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "measures",
        "mentions",
        "total"
      ],
      "description": "Registry entries that match the search and name a peptide without testing it (it is only a measured level, an eligibility term or a mention in the text). Not trials of the peptide. Counted apart from counts.trials."
    },
    "lists": {
      "type": "object",
      "properties": {
        "findings": {
          "type": "object",
          "properties": {
            "order": {
              "type": "string",
              "enum": [
                "ranked",
                "evidence"
              ]
            },
            "ranked_pool": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "order",
            "ranked_pool"
          ]
        },
        "publications": {
          "type": "object",
          "properties": {
            "order": {
              "type": "string",
              "enum": [
                "ranked",
                "citations"
              ]
            },
            "ranked_pool": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "order",
            "ranked_pool"
          ]
        },
        "trials": {
          "type": "object",
          "properties": {
            "order": {
              "type": "string",
              "enum": [
                "updated"
              ]
            },
            "ranked_pool": {
              "type": "null"
            }
          },
          "required": [
            "order",
            "ranked_pool"
          ]
        }
      },
      "required": [
        "findings",
        "publications",
        "trials"
      ],
      "description": "How each list is ordered. \"ranked\" = top of a hybrid ranking (full-text plus semantic similarity); ranked_pool is the length of that ranking (at most 400) and is NOT a total of matches, so a client says \"top N ranked\" and never \"N results\". \"evidence\" = human evidence first, then newest. \"citations\" = checked papers first, then most cited. \"updated\" = most recently updated first. counts holds the exact full-text totals."
    }
  },
  "required": [
    "credit",
    "record_type",
    "query",
    "data_seq",
    "peptides",
    "findings",
    "publications",
    "trials",
    "counts",
    "lists"
  ]
}