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

Responses

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	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`.

Responses

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.

Responses

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	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.

Responses

200 OK

Refer to the common response description: JSONSchemaResponse.

Schemas

Namespace

Name	Type	Description
`contact_url`	string(uri)	A reference for learning more about the namespace. Should provide enough information to contact the maintainers: it could be a `mailto:` link, a link to a project website, a GitHub project, issue tracking system, or similar.
`namespace_name`	string	The identifier for the namespace. Uniquely identifies a namespace within a given instance of the schema registry, but not across registries. For example, `https://example.com/schemas/my-great-namespace` and `https://another.example/schemas/my-great-namespace` can both exist, and they refer to different namespaces.
`server`	string	The HTTP(S) URL of the schema registry server hosting this namespace.

PagedResponse

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

SchemaRecord

Name	Type	Description
`latest_released_version`	string	The latest version of this schema that currently exists in this repository, excluding any versions with pre-release tags.
`maintainers`	Array<string>
`maturity_level`	string	The maturity level of the schema, as defined by the [GA4GH GKS Maturity Model specification](https://vrs.ga4gh.org/en/2.0.0-ballot.2024-11/appendices/maturity_model.html).
`namespace`	string
`schema_name`	string

SchemaVersion

Name	Type	Description
`contributors`	Array<string>
`release_date`	string(date-time)
`release_notes`	string
`schema_name`	string	The name of the schema this version belongs to.
`status`	string
`tags`		User-definable key/value pairs that provide additional information about this schema version.
`version`	string	Immutable identifier for this schema version. Follows the [GA4GH GKS Maturity Model specification](https://vrs.ga4gh.org/en/2.0.0-ballot.2024-11/appendices/maturity_model.html).

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.