From 46b8054bbda8b277f2eaea8c690b3776c3a6b36b Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 08:24:36 +0100 Subject: [PATCH 01/11] add documentation --- namespace-resolver/README.md | 43 ++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 namespace-resolver/README.md diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md new file mode 100644 index 0000000..963ffc7 --- /dev/null +++ b/namespace-resolver/README.md @@ -0,0 +1,43 @@ +# GA4GH Service Info Types + +This file details how to register prefixes and resolution patterns for the `GA4GH` namespace. + +## Background + +GA4GH standards such as refget and VRS provide methods for the construction of computed identifiers under the GA4GH namespace. These identifiers have type prefixes allowing for sharing of the GA4GH namespace, e.g. `ga4gh:SQ.cQvw4UsHHRRlogxbWCB8W-mKD4AraM9y` representing a refget sequence identifier. To avoid namespace collisions (e.g. another standard using the `SQ` type string), a centralized registry of identifier types and resolution patterns should be managed by TASC. This enables coordination across the GA4GH organization and provides a means for community members seeking to dereference `ga4gh` namespaced identifiers to documentation about what those objects are. + +## Using This File + +`identifier-prefixes.yaml` captures the identifier name, schema URI, and documentation URI, as applicable. + +### YAML format + +The YAML file shall feature entries in the following format: +```yaml +prefixes: + - SQ: + name: refget sequence + documentation: https://ga4gh.github.io/refget/sequences/#refget-checksum-algorithm + - VA: + name: VRS Allele + documentation: https://vrs.ga4gh.org/en/stable/concepts/MolecularVariation/Allele.html + schema: https://w3id.org/ga4gh/schema/vrs/2.0/json/Allele +``` + +## Process + +Additional namespace type prefixes raised as required for standards. It is recommended that this is done in conjunction with the preparation of Product Approval documentation. For further guidelines see [the GA4GH Product Approval Process Guide](https://w3id.org/ga4gh/product-approval). + +To add an item to this list, please take the following steps: + +- Create a fork of the TASC repo in your own user space +- Modify the YAML file with the values needed for your specification, keeping the entries ordered alphabetically +- Submit the changes as a PR back into the TASC repository +- Notify GA4GH TASC directly +- GA4GH TASC will review and inform on subsequent steps + +Items should not be removed from this list, as otherwise eventual new additions may collide with historical values which may be still in use with their original meanings by older servers. +If an item is to be retired or renamed, the existing entry should be retained with two additional fields: + +- `status`, which must be one of `"superseded"` or `"withdrawn"`; +- `note`, which is a free-form string describing why the item is no longer active. From 4e720741a357d3f0af77487866d6f085a6164ae3 Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 08:27:20 +0100 Subject: [PATCH 02/11] closes #59 --- namespace-resolver/identifier-prefixes.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 namespace-resolver/identifier-prefixes.yaml diff --git a/namespace-resolver/identifier-prefixes.yaml b/namespace-resolver/identifier-prefixes.yaml new file mode 100644 index 0000000..42dd75b --- /dev/null +++ b/namespace-resolver/identifier-prefixes.yaml @@ -0,0 +1,8 @@ +prefixes: + - SQ: + name: refget sequence + documentation: https://ga4gh.github.io/refget/sequences/#refget-checksum-algorithm + - VA: + name: VRS Allele + documentation: https://vrs.ga4gh.org/en/stable/concepts/MolecularVariation/Allele.html + schema: https://w3id.org/ga4gh/schema/vrs/2.0/json/Allele \ No newline at end of file From 3788081a715daeb68bd877518180c439b95e64ec Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 08:34:05 +0100 Subject: [PATCH 03/11] update docs --- namespace-resolver/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 963ffc7..714c31d 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -26,7 +26,7 @@ prefixes: ## Process -Additional namespace type prefixes raised as required for standards. It is recommended that this is done in conjunction with the preparation of Product Approval documentation. For further guidelines see [the GA4GH Product Approval Process Guide](https://w3id.org/ga4gh/product-approval). +Additional namespace type prefixes raised as required for standards. It is recommended that this is done in conjunction with the preparation of Product Approval documentation. Prefix requests require the approval of the specification product owners. For further guidelines see [the GA4GH Product Approval Process Guide](https://w3id.org/ga4gh/product-approval). To add an item to this list, please take the following steps: From 26458d80eaed025a6ea6a0261d4cbc354e217160 Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 08:35:48 +0100 Subject: [PATCH 04/11] add CODEOWNERS for the namespace-resolver issues --- CODEOWNERS | 1 + 1 file changed, 1 insertion(+) create mode 100644 CODEOWNERS diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..0bf5bac --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1 @@ +namespace-resolvers @ahwagner @larrybabb @andrewyatz \ No newline at end of file From d842cbd0f32998ce5b4c84fcef68278e3e5043f3 Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 10:54:50 +0100 Subject: [PATCH 05/11] Update README.md --- namespace-resolver/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 714c31d..60ba5f1 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -1,4 +1,4 @@ -# GA4GH Service Info Types +# GA4GH Namespaced Identifier Registration This file details how to register prefixes and resolution patterns for the `GA4GH` namespace. From 626aeb120ee275bd8fcdbc65044b3dd5087a4002 Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:10:41 +0100 Subject: [PATCH 06/11] Update README.md --- namespace-resolver/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 60ba5f1..c5b9af3 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -24,6 +24,24 @@ prefixes: schema: https://w3id.org/ga4gh/schema/vrs/2.0/json/Allele ``` +### Type Prefixes + +![GA4GH type prefixes](./img/type-prefixes.png) + +A GA4GH identifier is constructed according to this syntax: + +``` +"ga4gh" ":" type_prefix "." digest +``` + +The `digest` is computed as described above. The type_prefix is a short alphanumeric code that corresponds to the type of object being represented. + +These are our recommendations for type prefixes: + +* Prefixes SHOULD be short, ideally 2-4 characters. +* Prefixes SHOULD be for concrete types, not polymorphic parent classes. +* A prefix MUST map 1:1 with a schema type. + ## Process Additional namespace type prefixes raised as required for standards. It is recommended that this is done in conjunction with the preparation of Product Approval documentation. Prefix requests require the approval of the specification product owners. For further guidelines see [the GA4GH Product Approval Process Guide](https://w3id.org/ga4gh/product-approval). From 57280b6a8ab987c730f59c265bbcb58fb9e1b54d Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:11:11 +0100 Subject: [PATCH 07/11] Update README.md --- namespace-resolver/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index c5b9af3..ed6faec 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -26,8 +26,6 @@ prefixes: ### Type Prefixes -![GA4GH type prefixes](./img/type-prefixes.png) - A GA4GH identifier is constructed according to this syntax: ``` From 033bb2119f21b339a15c65e20f33cd6d0229bb89 Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:18:15 +0100 Subject: [PATCH 08/11] Update README.md --- namespace-resolver/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index ed6faec..6f99214 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -37,6 +37,7 @@ The `digest` is computed as described above. The type_prefix is a short alphanum These are our recommendations for type prefixes: * Prefixes SHOULD be short, ideally 2-4 characters. +* Characters MUST be uppercase only. * Prefixes SHOULD be for concrete types, not polymorphic parent classes. * A prefix MUST map 1:1 with a schema type. @@ -57,3 +58,7 @@ If an item is to be retired or renamed, the existing entry should be retained wi - `status`, which must be one of `"superseded"` or `"withdrawn"`; - `note`, which is a free-form string describing why the item is no longer active. + +## Notes + +It is strongly recommended that these prefixes do not change with new versions of the product. From 262c34b2f2af62d7ac142f900127865d18ffc27c Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:32:49 +0100 Subject: [PATCH 09/11] Update README.md --- namespace-resolver/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 6f99214..4c85916 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -8,7 +8,7 @@ GA4GH standards such as refget and VRS provide methods for the construction of c ## Using This File -`identifier-prefixes.yaml` captures the identifier name, schema URI, and documentation URI, as applicable. +`identifier-prefixes.yaml` captures the identifier name, schema URI, and documentation URI, as applicable. Prefixes are used to represent specific concepts, though schemas for these concepts may change over time. The schema URI, therefore, can be used as a representative of this concept but SHOULD NOT be assumed to be the only schema for this concept. Concept definitions should be retrievable from the documentation URI. ### YAML format From 4ebd6ee7bcdee735d2cecce4201121555889e7be Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:34:30 +0100 Subject: [PATCH 10/11] Update README.md --- namespace-resolver/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 4c85916..73c3595 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -56,7 +56,7 @@ To add an item to this list, please take the following steps: Items should not be removed from this list, as otherwise eventual new additions may collide with historical values which may be still in use with their original meanings by older servers. If an item is to be retired or renamed, the existing entry should be retained with two additional fields: -- `status`, which must be one of `"superseded"` or `"withdrawn"`; +- `status`, which must be one of `"active"` `"superseded"` or `"withdrawn"`; - `note`, which is a free-form string describing why the item is no longer active. ## Notes From ac56fd4b410043ac3487ecbdba4c9328ca757c0b Mon Sep 17 00:00:00 2001 From: "Alex H. Wagner, PhD" Date: Fri, 18 Jul 2025 11:35:02 +0100 Subject: [PATCH 11/11] Update README.md --- namespace-resolver/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/namespace-resolver/README.md b/namespace-resolver/README.md index 73c3595..f39dc60 100644 --- a/namespace-resolver/README.md +++ b/namespace-resolver/README.md @@ -56,7 +56,7 @@ To add an item to this list, please take the following steps: Items should not be removed from this list, as otherwise eventual new additions may collide with historical values which may be still in use with their original meanings by older servers. If an item is to be retired or renamed, the existing entry should be retained with two additional fields: -- `status`, which must be one of `"active"` `"superseded"` or `"withdrawn"`; +- `status`, which must be one of `"active"`, `"superseded"`, or `"withdrawn"`; - `note`, which is a free-form string describing why the item is no longer active. ## Notes