{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-peptide-brief-schema.json",
  "title": "PeptideBrief",
  "description": "Chat-ready summary of one peptide: identity, counts by evidence class, key findings with citations and coverage.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-openapi.json#/components/schemas/PeptideBrief",
  "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": [
        "peptide_brief"
      ]
    },
    "study_counts": {
      "type": "object",
      "properties": {
        "papers_with_results": {
          "type": "integer",
          "minimum": 0,
          "description": "Linked current papers with checked findings for this peptide, any role, source active or corrected."
        },
        "papers_with_results_administered": {
          "type": "integer",
          "minimum": 0,
          "description": "Of those papers, those with an administered finding."
        },
        "results_administered": {
          "type": "integer",
          "minimum": 0,
          "description": "Checked administered findings in those papers."
        }
      },
      "required": [
        "papers_with_results",
        "papers_with_results_administered",
        "results_administered"
      ]
    },
    "query": {
      "type": "string"
    },
    "resolution": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "unique",
            "ambiguous",
            "unresolved"
          ]
        },
        "candidates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "peptide_id": {
                "type": "string"
              },
              "preferred_name": {
                "type": "string"
              },
              "basis": {
                "type": "string"
              }
            },
            "required": [
              "peptide_id",
              "preferred_name"
            ],
            "additionalProperties": {}
          }
        }
      },
      "required": [
        "status",
        "candidates"
      ]
    },
    "peptide": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "peptide_id": {
          "type": "string"
        },
        "preferred_name": {
          "type": "string"
        },
        "kind": {
          "type": "string"
        },
        "sequence": {
          "type": [
            "string",
            "null"
          ]
        },
        "length_residues": {
          "type": [
            "integer",
            "null"
          ]
        },
        "modifications": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "related": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "xrefs": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "peptide_id",
        "preferred_name",
        "kind",
        "sequence",
        "length_residues",
        "modifications",
        "aliases",
        "xrefs"
      ],
      "additionalProperties": {}
    },
    "evidence_summary": {
      "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"
          ]
        },
        "trials": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "Registered trials that test the peptide (role tests)."
            },
            "by_overall_status": {
              "type": "object",
              "additionalProperties": {
                "type": "number"
              }
            },
            "results_posted": {
              "type": "integer"
            },
            "other_registry_entries": {
              "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 name the peptide without testing it. They are not trials of the peptide."
            }
          },
          "required": [
            "total"
          ],
          "additionalProperties": {}
        },
        "retracted_publications_excluded": {
          "type": "integer"
        },
        "latest_publication_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "endogenous_findings": {
          "type": "integer",
          "description": "Checked findings that measure the body's own peptide. The counts above leave them out."
        }
      },
      "required": [
        "human",
        "animal",
        "laboratory",
        "predicted",
        "trials",
        "retracted_publications_excluded"
      ],
      "additionalProperties": {}
    },
    "coverage": {
      "type": "object",
      "properties": {
        "checked_years": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "integer",
                "null"
              ]
            },
            "to": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ],
          "description": "The real span of the publication years of the papers with checked findings (retracted, withdrawn and removed papers left out). Null when no paper is checked."
        },
        "search_scope_years": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "integer",
                "null"
              ]
            },
            "to": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ],
          "description": "The years that the literature search covers (configuration), not the years of the checked papers."
        },
        "stored_years": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "integer",
                "null"
              ]
            },
            "to": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ]
        },
        "stored_only_publications": {
          "type": "integer",
          "description": "Papers of the peptide that are stored and not checked yet (status stored_only). Retracted, withdrawn and removed papers are left out."
        },
        "queued_publications": {
          "type": "integer"
        },
        "out_of_scope_publications": {
          "type": "integer",
          "description": "Papers of the peptide that are out of scope by a scope policy. They are stored, but PepBank does not check them. stored_only_publications and queued_publications leave them out."
        },
        "scope_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "rule": {
                "type": "string"
              },
              "topic": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "papers": {
                "type": "integer"
              }
            },
            "required": [
              "rule",
              "topic",
              "label",
              "papers"
            ]
          },
          "description": "The scope rules that put papers of this peptide out of scope, with the number of papers of each rule."
        },
        "live_sources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "scope_source": {
          "type": "string"
        }
      },
      "required": [
        "checked_years",
        "stored_years",
        "stored_only_publications",
        "queued_publications",
        "live_sources",
        "scope_source"
      ],
      "additionalProperties": {}
    },
    "ranking": {
      "type": "object",
      "properties": {
        "rule": {
          "type": "string"
        },
        "limit": {
          "type": "integer"
        },
        "limit_source": {
          "type": "string"
        }
      },
      "required": [
        "rule",
        "limit",
        "limit_source"
      ]
    },
    "key_findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "finding_id": {
            "type": "string"
          },
          "evidence_class": {
            "type": "string",
            "enum": [
              "human",
              "animal",
              "laboratory",
              "predicted"
            ],
            "description": "Evidence class: human, animal, laboratory or predicted."
          },
          "design": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "direction": {
            "type": "string"
          },
          "validation_status": {
            "type": "string"
          },
          "citation": {
            "type": "object",
            "properties": {
              "publication_id": {
                "type": "string"
              },
              "pmid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "doi": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "publication_id"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "finding_id",
          "evidence_class",
          "design",
          "statement",
          "direction",
          "validation_status",
          "citation"
        ],
        "additionalProperties": {}
      }
    },
    "notices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "text"
        ]
      }
    },
    "community": {},
    "regulatory": {
      "type": "object",
      "properties": {
        "approval": {
          "type": "string",
          "description": "Approval status in words, with the places: for example \"Approved in the US and EU (Ozempic, 2017)\" or \"Not approved for any use\"."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ]
        },
        "approved_products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "where": {
                "type": "string"
              },
              "product": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "approved_for": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "where",
              "product",
              "year",
              "approved_for",
              "source_url"
            ]
          },
          "description": "Every approved product with where and for what it is approved. Never infer an indication from the approval label."
        },
        "sport_status": {
          "type": [
            "string",
            "null"
          ],
          "description": "Status on the WADA Prohibited List, in words. Null when not recorded."
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ],
          "description": "Date of the regulatory record."
        }
      },
      "required": [
        "approval",
        "detail",
        "approved_products",
        "sport_status",
        "as_of"
      ],
      "description": "Regulatory and sport status from the peptide record. Quote the approval label as written; never write only the word approved."
    },
    "data_seq": {
      "type": "integer"
    },
    "generated_at": {
      "type": "string"
    },
    "freshness_lag_hours": {
      "type": "number"
    },
    "usage": {
      "type": "object",
      "properties": {
        "units_charged": {
          "type": "number",
          "minimum": 0,
          "description": "Units that this request used."
        },
        "meter": {
          "type": "string",
          "enum": [
            "query",
            "live_lookups",
            "chat_messages",
            "exports"
          ],
          "description": "Meter that counted this request."
        },
        "remaining": {
          "type": [
            "number",
            "null"
          ],
          "description": "Units left in the current window. Null means no limit."
        },
        "window_resets_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the current window ends (ISO 8601)."
        }
      },
      "required": [
        "units_charged",
        "meter",
        "remaining",
        "window_resets_at"
      ],
      "description": "Usage of this request. REST also sends these values in RateLimit headers."
    }
  },
  "required": [
    "credit",
    "record_type",
    "query",
    "resolution",
    "peptide",
    "evidence_summary",
    "coverage",
    "ranking",
    "key_findings",
    "notices",
    "data_seq",
    "generated_at",
    "freshness_lag_hours",
    "usage"
  ]
}