From 2225912f59259d539822a8c33c9e98bd299d84e1 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 28 Mar 2024 10:00:55 -0700 Subject: [PATCH] update doc --- src/docs/appendices.md | 6 +----- src/docs/implementation-guidance.md | 24 +++++++++++------------- 2 files changed, 12 insertions(+), 18 deletions(-) diff --git a/src/docs/appendices.md b/src/docs/appendices.md index 73c3e31..ea62ebe 100644 --- a/src/docs/appendices.md +++ b/src/docs/appendices.md @@ -13,7 +13,7 @@ identifier component (e.g. ‘infores:dgidb’) * **synonym**: * other names for the resource (will facilitate search/discovery) * **url**: - * a url describing the resource - this should be a Translator Wiki page following the templating guidance in that resource. + * a url describing the resource - this should be a Translator Wiki page following the templating guidance in that resource * **description**: * a free text description of the resource @@ -40,7 +40,3 @@ for different scenarios / use cases we encounter in the registry. Aggregator Scenario: KPs/ARAs that aggregate content from one or more existing resource and transform the semantics and or structure of the data to be better aligned with Translator standards - -Resource Examples: -Molecular Data Provider, Biolink, ROBOKOP, SRI Reference KG, RTX KG2 (these aggregate content from multiple sources into a single KG / API) -Automat APIs (stands up a separate API per source - each of which gets its own InfoRes) \ No newline at end of file diff --git a/src/docs/implementation-guidance.md b/src/docs/implementation-guidance.md index a821420..d3aa130 100644 --- a/src/docs/implementation-guidance.md +++ b/src/docs/implementation-guidance.md @@ -11,8 +11,8 @@ the Translator Resource Wiki: https://github.com/NCATSTranslator/Translator-All/ page filled out for any new information resource added to the catalog via a pull request. Information about the format of the wiki page can be found in the [Translator Resource Wiki](https://github.com/NCATSTranslator/Translator-All/wiki/). -You may also suggest an infores CURIE in the ‘id’ column, and populate any of the other metadata columns as desired -(see [Appendices 1 and 2](appendices.md) for more guidance). PRs will require a review by any member of the Infores Catalog team. +Please also suggest an infores CURIE in the ‘id’ field, (see [Appendices 1 and 2](appendices.md) for more guidance). +PRs will require a review. ## Editing metadata for an existing entry: @@ -23,34 +23,32 @@ of being deleted from the registry. This helps maintain provenance of the ids m ## Modifying an existing Information Resource entry in the registry: -Making changes to the registry to the information-resource-registry github repository. Any of the -fields in an Information Resource entry can be modified, but the id field MUST not be changed. If the id field is -changed, it MUST be treated as a new entry and the old entry MUST be deprecated. +Making changes to the registry to the information-resource-registry GitHub repository. Any of the +fields in an Information Resource entry can be modified, but the id field must not be changed. If the id field is +changed, it must be treated as a new entry and the old entry must be deprecated. This gives downstream applications +a chance to update their records to reflect the change and keeps links to the existing resource from breaking. ## Adding a new Information Resource entry to the registry: -Adding a new entry to the registry is as easy as adding a stanza to the information_resource_registry.yaml file in the -repository and submitting the change via pull request in the repository. Alternatively, making a ticket for a new +Adding a new entry to the registry is as easy as adding a stanza to the infores_catalog.yaml file in the +repository and submitting the change via pull request. Alternatively, making a ticket for a new resource in the information-resource-registry GitHub repository will also work. ## Minting new Information Resource identifiers: - Each smartAPI-registered Translator API gets its own InfoRes, as will each upstream source from which it aggregates knowledge. - Each upstream source from which a Translator API retrieves data computed on to generate knowledge will also get its own InfoRes. -- Create an InfoRes IRI for each registered Biothings-generated API, that includes a 'biothings-' prefix in the identifier component. -If the resource whose content was wrapped in a Biothigns API is a pre-existing resource with established use and identity, an -InfoRes is created for it as well. -- Identifiers should be short, readable, strings deliminated with a dash ('-'). These identifiers will be used +- Identifiers should be short, readable, strings delimited with a dash ('-'). These identifiers will be used in user-facing applications and should be as readable as possible. - In general, the 'status' field of an Information Resource stanza should be one of two values: 'released' or 'deprecated'. The following is an example of a new entry in the -information_resource_registry.yaml file: +infores_catalog.yaml file: ``` - id: infores:my-new-resource name: My New Resource description: This is a new resource - url: https://my-new-resource.org/ + url: https://github.com/NCATSTranslator/Translator-All/wiki/my-new-resource status: released ```