GA4GH Schema Registry API 0.1.0

Allows browsing and querying for versioned JSON schema instances across namespaces.

---

Endpoints

---

GET /namespaces

Returns all namespaces hosted by this server

Response 200 OK

Refer to the common response description: NamespacesResponse.

---

GET /schemas/{namespace}/

Returns a paginated list of schema metadata within the given namespace

Description

Returns a paginated list of schemas under this namespace. The list can be filtered using query parameters matching properties of the Schema object, Such as ?schema_name=abcd or ?maintainer=John+Doe.

Input parameters

Parameter	In	Type	Default	Nullable	Description
latest_version	query	string		No	Return only schemas with a matching `latest_version`.
lifecycle_stage	query	string		No	Return only schemas with a matching `lifecycle_stage`.
maintainer	query	string		No	Return only schemas with a matching `maintainer`.
namespace	path	string		No	The namespace containing the schemas.
schema_name	query	string		No	Return only schemas with a matching `schema_name`.

Response 200 OK

Refer to the common response description: SchemasResponse.

---

GET /schemas/{namespace}/{schema_name}/versions

Returns the versions of a specific schema

Input parameters

Parameter	In	Type	Default	Nullable	Description
namespace	path	string		No	The namespace of the schema.
schema_name	path	string		No	The name of the schema.

Response 200 OK

Refer to the common response description: SchemaVersionsResponse.

---

GET /schemas/{namespace}/{schema_name}/versions/{semantic_version}

Returns the JSON Schema document itself

Input parameters

Parameter	In	Type	Default	Nullable	Description
namespace	path	string		No	The namespace of the schema.
schema_name	path	string		No	The name of the schema.
semantic_version	path	string		No	The semantic version. The special value `latest` is equivalent to specifying the same string as in the target schema's `latest_released_version` property.

Response 200 OK

Refer to the common response description: JSONSchemaResponse.

---

Schemas

Namespace

Name	Type
contact_url	string(uri)
namespace_name	string

SchemaRecord

Name	Type
latest_released_version	string
maintainer	Array<string>
maturity_level	string
schema_name	string

SchemaVersion

Name	Type
contributors	Array<string>
release_date	string(date-time)
release_notes	string
status	string
tags
version	string

Common responses

This section describes common responses that are reused across operations.

SchemasResponse

A list of schemas within the specified namespace.

application/json

{
    "namespace": "bioinformatics-pipeline",
    "schemas": [
        {
            "schema_name": "sequencing-metadata",
            "latest_released_version": "2.0.1",
            "maintainer": [
                "Fatima Al-Farsi",
                "Miguel Santos"
            ],
            "maturity_level": "trial_use"
        },
        {
            "schema_name": "clinical-phenotypes",
            "latest_released_version": "1.3.0",
            "maintainer": [
                "Adebayo Okafor"
            ],
            "maturity_level": "normative"
        }
    ]
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "namespace": {
            "type": "string"
        },
        "schemas": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SchemaRecord"
            }
        }
    }
}

SchemaVersionsResponse

Schema versions with details.

application/json

{
    "schema_name": "sequencing-metadata",
    "versions": [
        {
            "version": "1.0.1",
            "status": "current",
            "release_date": "2023-11-20T00:00:00+00:00",
            "contributors": [
                "Fatima Al-Farsi",
                "Miguel Santos",
                "Adebayo Okafor"
            ],
            "release_notes": "Updated schema with additional metadata fields for improved annotation.",
            "tags": {
                "maturity_level": "trial_use"
            }
        },
        {
            "version": "1.0.0",
            "status": "deprecated",
            "release_date": "2023-06-15T00:00:00+00:00",
            "contributors": [
                "Miguel Santos"
            ],
            "release_notes": "Initial trial-use release.",
            "tags": {
                "maturity_level": "trial_use"
            }
        },
        {
            "version": "0.9.1",
            "status": "latest",
            "release_date": "2022-12-10T00:00:00+00:00",
            "contributors": [
                "Fatima Al-Farsi"
            ],
            "release_notes": "Experimental changes to metadata definitions.",
            "tags": {
                "maturity_level": "draft"
            }
        }
    ]
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "schema_name": {
            "type": "string"
        },
        "versions": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SchemaVersion"
            }
        }
    }
}

JSONSchemaResponse

The JSON Schema for the requested version.

application/json

{
    "$id": "https://example.com/schemas/genomics-analysis/versions/2.0.1",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Genomics Analysis Schema",
    "type": "object",
    "properties": {
        "sample_id": {
            "type": "string",
            "description": "Unique identifier for the biological sample."
        },
        "sequencing_platform": {
            "type": "string",
            "description": "Platform used for sequencing, e.g., Illumina NovaSeq."
        }
    }
}

Schema of the response body

{
    "type": "object"
}

NamespacesResponse

A list of namespaces hosted by the server.

application/json

{
    "server": "https://example.com/schemas",
    "namespaces": [
        {
            "namespace_name": "bioinformatics-pipeline",
            "contact_url": "https://github.com/genomics-lab/schema-registry"
        },
        {
            "namespace_name": "clinical-data-exchange",
            "contact_url": "https://github.com/hospital-group/clinical-data"
        }
    ]
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "server": {
            "type": "string"
        },
        "namespaces": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Namespace"
            }
        }
    }
}