Skip to content

docs: enhance score set create/patch endpoints with detailed OpenAPI schema for file uploads #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bencap merged 2 commits into from
Jan 14, 2026
Merged

docs: enhance score set create/patch endpoints with detailed OpenAPI schema for file uploads #630

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc8514a
docs: enhance score set create/patch endpoints with detailed OpenAPI …
bencap Dec 23, 2025
746ef88
Update OpenAPI documentation for the score set upload and patch endpo…
davereinhart Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions src/mavedb/routers/score_sets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1691,6 +1691,41 @@ async def create_score_set(
response_model_exclude_none=True,
responses={**BASE_400_RESPONSE, **ACCESS_CONTROL_ERROR_RESPONSES},
summary="Upload score and variant count files for a score set",
openapi_extra={
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"scores_file": {
"type": "string",
"format": "binary",
"description": "CSV file containing variant scores. This file is required, and should have at least one score column.",
},
"counts_file": {
"type": "string",
"format": "binary",
"description": "CSV file containing variant counts. If provided, this file should have the same index and variant columns as the scores file.",
},
"score_columns_metadata": {
"type": "string",
"format": "binary",
"description": "JSON file containing metadata for score columns. If provided, this file should have metadata for one or more score columns in the scores file. This JSON file should provide a dictionary mapping column names to metadata objects. Metadata objects should follow the DatasetColumnMetadata schema: `{'description': string, 'details': string}`.",
},
"count_columns_metadata": {
"type": "string",
"format": "binary",
"description": "JSON file containing metadata for count columns. If provided, this file should have metadata for one or more count columns in the counts file. This JSON file should provide a dictionary mapping column names to metadata objects. Metadata objects should follow the DatasetColumnMetadata schema: `{'description': string, 'details': string}`.",
},
},
"required": ["scores_file"],
}
},
},
"description": "Score files, to be uploaded as multipart form data. The `scores_file` is required, while the `counts_file`, `score_columns_metadata`, and `count_columns_metadata` are optional.",
}
},
)
async def upload_score_set_variant_data(
*,
Expand Down Expand Up @@ -1763,6 +1798,41 @@ async def upload_score_set_variant_data(
response_model_exclude_none=True,
responses={**BASE_400_RESPONSE, **ACCESS_CONTROL_ERROR_RESPONSES},
summary="Update score ranges / calibrations for a score set",
openapi_extra={
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
**score_set.ScoreSetUpdateAllOptional.model_json_schema(by_alias=False)["properties"],
"scores_file": {
"type": "string",
"format": "binary",
"description": "CSV file containing variant scores. If provided, this file should have at least one score column.",
},
"counts_file": {
"type": "string",
"format": "binary",
"description": "CSV file containing variant counts. If provided, this file should have the same index and variant columns as the scores file.",
},
"score_columns_metadata": {
"type": "string",
"format": "binary",
"description": "JSON file containing metadata for score columns. If provided, this file should have metadata for one or more score columns in the scores file. This JSON file should provide a dictionary mapping column names to metadata objects. Metadata objects should follow the DatasetColumnMetadata schema: `{'description': string, 'details': string}`.",
},
"count_columns_metadata": {
"type": "string",
"format": "binary",
"description": "JSON file containing metadata for count columns. If provided, this file should have metadata for one or more count columns in the counts file. This JSON file should provide a dictionary mapping column names to metadata objects. Metadata objects should follow the DatasetColumnMetadata schema: `{'description': string, 'details': string}`.",
},
},
}
},
},
"description": "Score set properties and score files, to be uploaded as multipart form data. All fields here are optional, and only those provided will be updated.",
}
},
)
async def update_score_set_with_variants(
*,
Expand All @@ -1780,6 +1850,13 @@ async def update_score_set_with_variants(
"""
logger.info(msg="Began score set with variants update.", extra=logging_context())

# TODO#629: Use `flexible_model_loader` utility here to support both form data and JSON body.
# See: https://github.com/VariantEffect/mavedb-api/pull/589/changes/d1641de7e4bee43e8a0c9f9283e022c5b56830ff
# Currently, only form data is supported but this would allow us to also support JSON bodies
# in cases where no files are being uploaded. My view is accepting score set calibration
# information via a single form field is also more straightforward than handling all the score
# set update fields as separate form fields and parsing them into an object. Doing so will also
# simplify the OpenAPI schema for this endpoint.
try:
# Get all form data from the request
form_data = await request.form()
Expand Down