Technical Alignment Subcommittee (TASC)

Issue Title

Verified implementations of GA4GH products

Issue Type

Directive Document

Problem Statement

Current state Currently GA4GH has no way of verifying the level of compatibility or depth of implementation of a GA4GH product. We have a listing of implementations on our central website but what it means to be an implementation is unclear. Finally for those wanting to implement a product we have little to no guidance beyond the documents accompanying our products as they flow through PDAP

Desired state We seek to have a state where we can define a set of criteria and point to verified implementations of products. In the first instance we want to solve this for open source software (since this is the most tangible) but then expand to other types of products. The same is true for all that we want anyone who creates an implementation of a product to be tagged with this status if it meets the laid out criteria

Impact One basic impact is a lack of any kind of end to end implementations demonstrating the interoperability of our products. Projects such as FASP and now those in GIF seek to provide some of this. A suite of implementations that are known to be good would allow for these known demonstration flows to be constructed and demonstrate interoperability. If there are issues they would be flagged as part of this process.

Scope Validation

The work affects everyone in GA4GH who produces products. The PDAP asks for two implementations of a product to review. There is no criteria set to ensure they are "good" implementations of a product though. Plus closed-source or closed network implementations can cause issues in the approval process.

We target this work because it will

• Highlight the need for harmonization in our products and what we consider to be "good"
• Recognises those who produce "good" implementations
• Span across multiple work streams who likely already have implementations that can fit this criteria

Proposed Solution(s)

See our in-progress doc and this has been discussed at the July in person TASC meeting

Estimated Effort Level

Low (1-2 months, minimal resources)

Success Criteria

• Approval of base criteria to assess implementation
• Execution of the criteria against at least three example implementations and feedback into the documentation

Post release:

• External projects submit at least three implementations to go through the process
• Creation of at least one compliance suite in response to this
• Engagement with one closed source project to adapt criteria

How will this issue aid GA4GH harmonization?

• How does this aid harmonization of GA4GH products?
• What barriers to organization-wide harmonization does this address?
• Which specific alignment challenges does this solve?
• Does this require cross-work stream development?Please describe the issue here

Additional context

Please provide any additional pieces of information you feel is relevant to this issue

Work Streams Raising This Issue

• [ ] Clinical & Phenotypic Data (Clin/Pheno)
• [ ] Cloud Work Stream
• [ ] Data Security
• [ ] Data Use & Researcher IDs (DURI)
• [ ] Discovery
• [ ] Genomic Knowledge Standards (GKS)
• [ ] Large Scale Genomics (LSG)
• [ ] Regulatory & Ethics (REWS)
• [ ] Data Models & Schemas Committee (DaMaSC)
• [ ] Genomic Implementation Forum (GIF)
• [x] Technical Team
• [ ] Other (specify below)

Other Groups Raising This Issue

No response

Work Streams That Will Be Impacted

• [x] Clinical & Phenotypic Data (Clin/Pheno)
• [x] Cloud Work Stream
• [x] Data Security
• [x] Data Use & Researcher IDs (DURI)
• [x] Discovery
• [x] Genomic Knowledge Standards (GKS)
• [x] Large Scale Genomics (LSG)
• [x] Regulatory & Ethics (REWS)
• [ ] Data Models & Schemas Committee (DaMaSC)
• [x] Genomic Implementation Forum (GIF)
• [x] Technical Team
• [ ] Other (specify below)

Other Groups That Will Be Impacted

No response

Key Stakeholders to Consult

Org/communities

• Implementation writers
• Products going through PDAP now

Tech experts

• Tech team members
• Implementation developers
• REWS experts

Decision makers

• PSC
• Exec
• TASC

Products affected

We will target htsget (server implementation), VRS (schema), refget (server implementation) and DRS (server implementation) to go through this process. We also want to engage with REWS to understand if such a criteria actually works for their products too

Additional Context

No response

Priority Level

Medium (should be addressed within 3-6 months)

Additional Tags

• [x] Documentation
• [x] API
• [x] Schema
• [x] Security
• [ ] Performance
• [x] Interoperability
• [x] Compliance
• [ ] User Experience
• [ ] Infrastructure
• [x] Testing

Issue Title

Clarify the issue submission form issue type for IANA registration

Issue Type

Other

Problem Statement

If someone wants a ga4gh IANA registration (see #36 and samtools/hts-specs #407), they'd use Issue Type = Other, or maybe they'd think Schema Alignment was about right. Also imagine someone wanted a unique URL redirect, it's another namespace alignment issue but not specifically Schema Alignment.

Scope Validation

TASC must handle global names within ga4gh, and the issue form should make it clear how to request them.

Proposed Solution(s)

Should there be extra issue types? Should Schema Alignment be renamed to Namespace Alignment?

Estimated Effort Level

Low (1-2 months, minimal resources)

Success Criteria

More clarity in the issue form.

How will this issue aid GA4GH harmonization?

• How does this aid harmonization of GA4GH products?
• What barriers to organization-wide harmonization does this address?
• Which specific alignment challenges does this solve?
• Does this require cross-work stream development?Please describe the issue here

wasn't this covered in another form field?

Additional context

Please provide any additional pieces of information you feel is relevant to this issue

Work Streams Raising This Issue

• [ ] Clinical & Phenotypic Data (Clin/Pheno)
• [ ] Cloud Work Stream
• [x] Data Security
• [ ] Data Use & Researcher IDs (DURI)
• [ ] Discovery
• [ ] Genomic Knowledge Standards (GKS)
• [x] Large Scale Genomics (LSG)
• [ ] Regulatory & Ethics (REWS)
• [ ] Data Models & Schemas Committee (DaMaSC)
• [ ] Genomic Implementation Forum (GIF)
• [ ] Technical Team
• [ ] Other (specify below)

Other Groups Raising This Issue

No response

Work Streams That Will Be Impacted

• [ ] Clinical & Phenotypic Data (Clin/Pheno)
• [ ] Cloud Work Stream
• [ ] Data Security
• [ ] Data Use & Researcher IDs (DURI)
• [ ] Discovery
• [ ] Genomic Knowledge Standards (GKS)
• [ ] Large Scale Genomics (LSG)
• [ ] Regulatory & Ethics (REWS)
• [ ] Data Models & Schemas Committee (DaMaSC)
• [ ] Genomic Implementation Forum (GIF)
• [ ] Technical Team
• [ ] Other (specify below)

Other Groups That Will Be Impacted

No response

Key Stakeholders to Consult

No response

Products affected

Just this form

Additional Context

No response

Priority Level

Low (can be addressed in normal course of work)

Additional Tags

• [ ] Documentation
• [ ] API
• [ ] Schema
• [ ] Security
• [ ] Performance
• [ ] Interoperability
• [ ] Compliance
• [ ] User Experience
• [ ] Infrastructure
• [ ] Testing

closes #50

No description.

V1 document is here: https://docs.google.com/document/d/1xPFXRF7_Ppe5SDBHTBa1E-MBHHNtoc1Q-jZ1olOrtc4/edit?tab=t.0

Expansion to follow.

Problem Statement Implementation registry service is used for cataloguing implementations of GA4GH standards. Most of the implementations that can be included in the service registry are web-based API standards. The current specification for the registry doesn't expect implementation submission to include geolocation information. With the recent rise in implementations of GA4GH standards, geolocation would be useful information to help understand the geographies where GA4GH standards are being actively implemented. This would help drive GA4GH objectives and decisions to explore ways of increasing the outreach and adoption of standards in nascent geographies.

Alignment between GA4GH standards As the registry serves as the catalogue for all web-based API implementations, it can foster collaboration between Work Streams and align with the wider GA4GH objectives such as implementation support and interoperability. This data would also help understand the uptake of standards and any blockers in implementation of any GA4GH standards.

Background research and landscape analysis Current specification of service registry doesn't support this data being captured. This gap makes it difficult to understand the adoption map of the standards across the globe. This also blocks providing timely support to institutions who are looking to implement standards in their infrastructure. The implementations currently documented in the registry would need retrospective updates which would be requested from the owners or contacts of the implementations. This would also have the additional benefit of helping flag redundant implementations, and refreshing the list of active implementations in the registry.

Proposed solution The solution being proposed is that all the implementations to be catalogued into the service registry should share geolocation information. It would be a mandatory parameter and modelled similar GeoJson (https://geojson.org).

GA4GH products utilize different technologies to support development of specifications and tooling. As a result, an instance of data might be serialized differently depending on the product with which it is used.

To improve the interoperability of GA4GH products with each other, key touch points between products should be identified and documented, and harmonized data structures should be developed when the same information is used by two or more products.

This issue proposes:

1. documenting practical use cases that utilize two or more GA4GH products (e.g., a workflow from Cloud WS or architecture from GIF)
2. developing an inventory of data elements that are common across two or more GA4GH products
3. identifying instances of data at touchpoints between products that are serialized differently
4. developing a process for harmonizing common data elements across GA4GH products
5. developing harmonized common data types and elements, and/or libraries of transformations, that improve interoperability across GA4GH products

Problem statement The GA4GH Technical Alignment Subcommittee (TASC) needs a formalised governance and leadership structure to be an effective technical leadership group.

How this will impact alignment between GA4GH standards The mission of the Technical Alignment Sub-Committee (TASC) of the GA4GH Standards Steering Committee (SSC) is to aid the harmonisation of aspects of GA4GH's products to ensure that they can be used together effectively. TASC provides outputs mechanisms and decisions to create internal consistency and technical alignment across GA4GH Work Streams and deliverables. While TASC functions as a central decision-making body, all of its decisions are informed by relevant stakeholders. The TASC outputs of TASC, including all documentation and decisions, are regularly and openly communicated back to the GA4GH community. Where appropriate, TASC can action product development within its structure when there is need for it and would benefit the GA4GH community, the nature of the work does not naturally fit within one of the work streams, requires significant cross-work stream development, and where sufficient interest and resources exist to develop the solution. Having a well-considered governance structure will determine the scope, leadership and functioning of TASC.

Proposed solution The draft governance and leadershup document can be found here, which will need to be voted on and approved.

We should work towards formalizing and aligning on practices for developing GA4GH products and representing their maturity level.

The GKS Work Stream has worked to formalize this in their Technical Specification Maintenance processes. There is an opportunity to share and align on these and other work stream practices at the TASC in-person meeting.

GKS Technical Specification Maintenance

Since we are having TASC build the resolver for across all workstreams (not just GKS) then the digest method should be under TASC too. This will also help with setting up a web page that describes the method/algorightm as the "formal" method for referencing.

Create a yaml file for prefix registration and use with resolver service.

Resolve ga4gh objects to return the object and references to information about the object type.

The problem

TASC mandates a format for issues to follow but fails to provide a template which would help to enforce the requirements.

The solution

Write a template and deposit in this repository. Confirm with TASC that this is what is needed to actual capture an issue or if we want to add anything else to the template

Additional context

No additional context needed

To assess and reform current GA4GH workspace structure, practice and naming conventions.

Problem Statement

The GKS Work Stream is trying to align conventions for resolving persistent URLs (pURLs) for schemas maintained by GA4GH.

Impact of alignment between standards

Consistency in the structure of pURLs drives consistency and cohesion across products, and makes it easier to document and describe GA4GH schema resources at a high level.

Background research and landscape analysis

GA4GH already uses w3id.org as a persistent URL resolver for GA4GH products, including VRS 1.3 definitions. The need for persistent URLs is important for use of online JSON Schema documents that should be resolvable by an $id attribute.

Proposed solution

We would like to establish a convention for registering GA4GH schema resolution at w3id.org, and propose the following syntax:

In this proposal, the product specific section may be variable from product to product, but otherwise all components are consistent across specifications.

This solution requires:

1. TASC to register GKS schemas under the /ga4gh/schema/ path
2. TASC to review requests for other GA4GH schema registrations at w3id.org and enforce consistent pURL patterns under the /ga4gh/schema/ path

This issue outlines the criteria for moving a standard into maintenance mode, defining responsibilities, establishing review schedules, and documenting any changes or updates that are made during the maintenance phase.

https://docs.google.com/document/d/1AdK2_vSNdXf280TgDdGhXsVsjhXvOD0sQSzQgWxH2IY/edit

We're putting together a draft proposal from WSMs to describe the problem space and some workflows to facilitate discussions within TASC

The problem

API product managers currently each design their own process (possibly with guidance from the corresponding) for releasing updates. This involves a number of decisions to be made and artifacts to be generated and may therefore slow down the release process and lead to inconsistencies between standards or even mistakes.

It would be great to define guidelines/policies for releases and reusable artifacts to streamline the process of GA4GH API products.

The solution

Guidelines could be drafted that cover, for example:

• How and where API specifications should be published (e.g., GitHub, Crossref)
• If/how commits should be tagged
• What Git branching model to adopt (e.g., Git Flow, GitHub Flow, GitLab Flow) and how to apply it in preperation of future releases, considering that there may be multiple options (next release could be patch, minor or major); this should ideally not just reference the branching model, but concrete info, e.g., keep main (for releases only, head commit always points to latest release), develop (working branch to create feature branches off), release branches for next patch, minor, major release
• How SemVer applies to API changes; again, guidelines for the most common scenarios should be concretized
• What merge strategy to adopt / linear vs. non-linear history and how the merge strategy impacts the release process
• What other GitHub options to set
• How to maintain, update and publish (continuous) documentation, where to publish them and if and how to keep versioned documentation
• How specs, code and data should be licensed
• How to write and keep release notes and changelogs
• How the process can be automated as much as possible (e.g., whole release process is triggered automatically if commit message includes specific regex)

Reusable artifacts could include:

• A checklist for creating a new release
• GitHub repository template with boilerplate following the guidelines above
• GitHub Actions workflows or specific Actions for releases, docs, OpenAPI linting/validation etc.
• Templates for releases notes/changelogs, GitHub issue, PRs
• Boilerplate parts for the documentation (links to GA4GH, Code of Conduct, contributing guidelines etc.)

Additional context

A lot of these guidelines are already in place, implicit or explicit, across the various API products. Similarly, a number of the artifacts may already exist and may already be reusable.

Therefore, a survey of the different available guidelines, solutions and artifacts would be useful to further inform the requirements and the work necessary to provide the support as outlined here.

Of course, guidelines and corresponding artifacts could themselves be versioned and iteratively improved/amended.

Problem

There are situations where managers of GA4GH API products deem certain functionalities "nice to have", but feel that they may not be necessary for all implementations or that they would unduly raise the bar for new implementers. In such cases, product managers/contributors may recommend or even specify support for such features if implementers (or administrators of individual instances) choose to adopt/provide them.

Currently, there is no common method for service instances to broadcast any such optional capabilities to make clients aware of such support.

An example

A Driver Project may be interested in the GA4GH Task Execution Service (TES) API providing dedicated support for Crypt4GH-encrypted inputs. Such support may require changes to the TES specification, e.g., additional properties in the task resource creation schema). TES product managers may agree that specific Crypt4GH support is useful but find it unreasonable to mandate that all TES implementations provide such support. They would now have at least two options to provide/specify support:

• Add the necessary fields to the existing task resource creation schema nad make them optional (or required only upon some condition)
• Publish a Crypt4GH extension of the TES specification

Either way, if TES implementers choose to provide Crypt4GH support, there is currently no common way of letting clients know about this support.

A possible solution

Broadcast optional, but clearly defined capabilities via an API service instance's GET /service-info endpoint. To make it easy for clients to consume (identify and understand) such capabitlies, at least the following requirements have to be met:

1. A controlled vocabulary of capabilities. These may be product-specific or cross-product; a given capability may also appear to be product-specific at first, but turn out later to be applicable to other products as well. They may also be hierarchical. An example could be crypt4gh.
2. A schema for specifying capabilities in the service info API. This could look, e.g., something like this:

components:
  ...
  schemas:
    Service:
      description: 'GA4GH service'
      type: object
      ...
      properties:
        ...
        capabilities:
          $ref: '#components/schemas/Capabilities'
    ...
    Capabilities:
      type: object
      description: Information on the support of optional capabilities of this service.
      additionalProperties:
        $ref: '#/components/schemas/Capability'
    Capability:
      type: object
      required:
        - supported
      properties:
        supported:
          type: boolean
          description: Whether the capability is supported by the service instance.
      anyOf:
        - properties:
            documentationUrl:
              type: string
              description: URL to documentation of this capability.
        - properties:
            specificationUrl: 
              type: string
              description: URL to an API specification supporting this capability.

This defines an interface for any named Capability, listed under property capabilities. The generic interface would require, for any listed capability, at least information on whether that capability is supported and either or both of a documentationUrl and/or a specificationUrl (in case there is a specific extension defined).

Then, in TES, one could further specify the general interface (this shows the general pattern of how the service info's Capability schema could be extended, if necessary; details would of course differ for each capability):

components:
  ...
  schemas:
    CapabilityCrypt4GH:
      allOf:
        - '$ref': https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/v1.0.0/service-info.yaml#/components/schemas/Capability
        - properties:
            some_tes_crypt4gh_specific_property:
              type: string
              description: Some capability-specific parameter

Note that the suggested (ad hoc) solution does not support nesting of capabilities. For example, crypt4gh-decrypt and crypt4gh-encrypt capabilities would have to be listed separately, rathan than as:

crypt4gh:
  decrypt:
    ...
  encrypt:
    ...

If support for nesting is desired, this will need additional work and decisions on whether there is a pre-defined number of nestings, whether nesting is always required and so on.

Possible alternatives

I was considering raising this issue in the Service Info API. However, I am not sure whether the service info is definitely the way to go here. Also, I feel that a solution should be dicussed and agreed upon by a wide range of GA4GH API product managers.

Additional context

Broadcasting capabilities via the /service-info endpoint would have the additional strong benefit that capabilities would become discoverable through Service Registry API implementations.

Problem statement

Service developers may choose to add implementation-specific properties to a GA4GH API. Or they may even choose to add additional endpoints (e.g., for POST, PUT, DELETE operations) that might make sense to host next to the existing endpoints at the same path.

To give clients the chance to discover and potentially be mindful of OpenAPI modifications, we could mandate or at least encourage the hosting of the actual OpenAPI specification at a well-known location, relative to the API.

A possible solution

Encourage or mandate the hosting of the actual (Open)API specfication for a given service instance, as a single source of truth, statically at path/to/api/specification, or - if we agree that such a feature should apply only to OpenAPI specifications - perhaps at a more descriptive location, such as path/to/api/openapi.json (see Additional Context below).

Given a URL to where the actual specification is hosted (or a base URL to which the client then applies any suffixes or rules described in the servers section of an OpenAPI specification to construct the path to the API), any client would then be able to obtain the definite version of the specification underlying any given service instance.

Note that this may actually drop the requirement for a given client to be coded against a specific version of an API altogether. A sufficiently "smart" client (if people chose to implement such a client - opinions may differ on whether that is useful or desirable) would not need to be tied to a specific API version, or even be aware of the specification beforehand at all, in order to interact with it.

Additional context

I would like to credit the excellent Connexion framework for the "modelless" implementation of "API first" services based on Python Flask (which is underlying almost all of the ELIXIR Cloud & AAI DP services) for inspiration here, as it is statically hosting the final compiled OpenAPI specification, including all modifications, at a configurable path - a feature which we have found useful for the reasons described above, and which we think would be even more useful if all implementers adhere to it (at least optionally).

An example of a service for which the API is hosted is here: https://elixir-cloud.dcc.sib.swiss/ga4gh/registry/v1/ui. The API definition for that service, in JSON, is hosted here: https://elixir-cloud.dcc.sib.swiss/ga4gh/registry/v1/openapi.json

The Crypt4GH encrypted file format standard is currently part of the hts-specs repo, where it lives next to the SAM, BAM, CRAM, VCF, BED file format standards: https://github.com/samtools/hts-specs. The reason it was placed in there was originally that it is essentially another file format standard (not an API, etc). And samtools was actually the first tool that natively supported it.

However, there have been calls to move Crypt4GH into its own GitHub repo instead; which is reasonable. We have two questions:

1 - Is this a good idea? Does it fit with the larger view on standards in the GA4GH?

2 - What would be the best name/location for this new repo? (Is there a naming scheme that differentiates between standards, implementations, APIs, etc. in https://github.com/ga4gh/?)

This issue has been raised recently in two Work Streams.

LSG have discussed the issue here: https://github.com/samtools/hts-specs/issues/179

In addition, Discovery have had this question in relation to citation of the Data Connect standard in the time period before a publication can be released.

As additional background, GA4GH is redeveloping its website, which could theoretically play a role in some of the possible solutions to this.

It would be useful for TASC to investigate and determine an approach that can, ideally, be applied consistently across GA4GH.

Problem Statement

The VRS standard submitted a proposal to the GA4GH Steering Committee to approve the use of the ga4gh namespace for VRS computed identifier CURIEs. This was approved by the Steering Committee, with the understanding that a governance mechanism would be established for object identifiers under this namespace once an appropriate technical committee was established (TASC).

VRS is preparing to release new data type prefixes under the ga4gh namespace as part of its upcoming minor version releases. We intend to move forward with these as scheduled until a formal mechanism for registering / requesting identifier prefixes is created.

Impact of alignment between standards

Due to the organization-level namespacing, any CURIEs generated under this namespace should have a consistent meaning across products. If two standards (e.g. refget and VRS) develop identifiers with similar prefixes or inconsistent structures under the ga4gh namespace, interoperability between resources implementing multiple GA4GH products expecting ga4gh CURIEs will fail.

Background research and landscape analysis

We have worked to create an identifier scheme that has been reviewed and approved by unanimous vote of the GA4GH Steering Committee.

We have established several type prefixes already, with more that will be generated over the next year as we iteratively expand VRS.

This has direct relevance to the DRS, VRS, and refget standards, and likely others down the road.

Proposed solution

The VRS Project Maintainers are granted authority to build additional type prefixes under the ga4gh namespace without external review, so long as those identifiers begin with V, (e.g. VS for VariationSet, VA for Allele, VH for Haplotype). Data type prefixes outside of this scope must be reviewed and approved by TASC before implementation. Similar project-level subdomains could be approved and allocated by TASC for other standards as needed.

In addition, a TASC-maintained public registry of type prefixes (approved, reserved, and pending) should be provided for quick reference by product developers and implementers.

There are a number of short identifier-sized pieces of metadata that are used across many GA4GH products. For example:

• Reference sequence names

  In SAM/BAM/CRAM, this is the @SQ-SN header field and RNAME/RNEXT/etc fields. In VCF/BCF, it's the ##contig ID. In htsget, it's referenceName. In refget, it may be returned as an alias.

• Sample identifiers

  In SAM/BAM/CRAM, this is the @RG-SM header field. In VCF/BCF, it's the ##SAMPLE ID and it also appears on the #CHROM header line. In htsget, it forms the bulk of the path part of request URLs, and there is a proposal to encode samples in the query part as well (samtools/hts-specs#430). In Phenopackets, it's a Biosample's id field.

These items of metadata are embedded within the surrounding text using various delimiters in these various formats and protocols. So there are various restrictions on what characters may appear in them so as to avoid conflicting with the delimiter characters or otherwise requiring complicated escaping or encoding mechanisms. It would be good to harmonise these restrictions across GA4GH products, so that a value that was e.g. a valid Sample identifier in one product could be assumed to also be valid in other products.

Per M Haendel:

a place to put requests such as these. It would be terrific if there was a more coordinated suite of GitHub repos and a central ticketing/work tracking system across them for GA4GH. Please let us know if you want help or advice in setting up such a thing, we are happy to contribute.

Per M Haendel:

I think we need a central, computable metadata registry for approved standards. This information can then be automatically ingested by other systems. For example, we have a really nice metadata registry for the OBO ontology standards here. Here is an example for HPO: https://github.com/OBOFoundry/OBOFoundry.github.io/blob/master/ontology/hp.md