GA4GH Schema Registry API 0.2.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 the schemas in 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 ?maintainers=John+Doe.

Input parameters

Parameter	In	Type	Default	Nullable	Description
maintainers	query	string		No	Return only schemas with a matching entry in their `maintainers` array.
maturity_level	query	string		No	Return only schemas with a matching `maturity_level`.
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 the given 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
server	string

PagedResponse

Name	Type
pagination	Properties: page, page_size, total, total_pages
results	Array<>

SchemaRecord

Name	Type
latest_released_version	string
maintainers	Array<string>
maturity_level	string
namespace	string
schema_name	string

SchemaVersion

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

Common responses

This section describes common responses that are reused across operations.

SchemasResponse

The schemas within the specified namespace.

application/json

{
    "pagination": {
        "page": 0,
        "page_size": 100000,
        "total": 2,
        "total_pages": 1
    },
    "results": [
        {
            "namespace": "bioinformatics-pipeline",
            "schema_name": "sequencing-metadata",
            "latest_released_version": "2.0.1",
            "maintainers": [
                "Fatima Al-Farsi",
                "Miguel Santos"
            ],
            "maturity_level": "trial_use"
        },
        {
            "namespace": "bioinformatics-pipeline",
            "schema_name": "clinical-phenotypes",
            "latest_released_version": "1.3.0",
            "maintainers": [
                "Adebayo Okafor"
            ],
            "maturity_level": "normative"
        }
    ]
}

Schema of the response body

{
    "allOf": [
        {
            "$ref": "#/components/schemas/PagedResponse"
        },
        {
            "type": "object",
            "properties": {
                "results": {
                    "type": "array",
                    "items": {
                        "$ref": "#/components/schemas/SchemaRecord"
                    }
                }
            }
        }
    ]
}

SchemaVersionsResponse

Available versions of a given schema.

application/json

{
    "pagination": {
        "page": 0,
        "page_size": 100000,
        "total": 3,
        "total_pages": 1
    },
    "results": [
        {
            "schema_name": "sequencing-metadata",
            "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"
            }
        },
        {
            "schema_name": "sequencing-metadata",
            "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"
            }
        },
        {
            "schema_name": "sequencing-metadata",
            "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

{
    "allOf": [
        {
            "$ref": "#/components/schemas/PagedResponse"
        },
        {
            "type": "object",
            "properties": {
                "results": {
                    "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

The namespaces hosted by the server.

application/json

{
    "pagination": {
        "page": 0,
        "page_size": 100000,
        "total": 2,
        "total_pages": 1
    },
    "results": [
        {
            "server": "https://example.com/schemas",
            "namespace_name": "bioinformatics-pipeline",
            "contact_url": "https://github.com/genomics-lab/schema-registry"
        },
        {
            "server": "https://example.com/schemas",
            "namespace_name": "clinical-data-exchange",
            "contact_url": "https://github.com/hospital-group/clinical-data"
        }
    ]
}

Schema of the response body

{
    "allOf": [
        {
            "$ref": "#/components/schemas/PagedResponse"
        },
        {
            "type": "object",
            "properties": {
                "results": {
                    "type": "array",
                    "items": {
                        "$ref": "#/components/schemas/Namespace"
                    }
                }
            }
        }
    ]
}

Notes:

There is not currently anything defined at /schemas. This is intentional: the namespace attribute is mandatory, and forms part of the path to a specific schema version. Future revisions of the specification may include something here if a need arises.