From 800d2631cc38260941960198b91df0736c44030e Mon Sep 17 00:00:00 2001 From: Lawrence Babb Date: Fri, 13 Dec 2024 12:30:09 -0500 Subject: [PATCH] initial draft of design decision topics for issue 571 --- docs/source/appendices/design_decisions.rst | 65 +++++++++++++++++++++ docs/source/appendices/index.rst | 1 + 2 files changed, 66 insertions(+) create mode 100644 docs/source/appendices/design_decisions.rst diff --git a/docs/source/appendices/design_decisions.rst b/docs/source/appendices/design_decisions.rst new file mode 100644 index 00000000..d0038295 --- /dev/null +++ b/docs/source/appendices/design_decisions.rst @@ -0,0 +1,65 @@ +.. _design_decisions: + +Design Decisions +!!!!!!!!!!!!!!!! + +The following design decisions were made in the development of the VRS: + +GA4GH Digest 'ga4gh.inherit' over value objects +----------------------------------------------- + +In VRS 1.0 we operated under the principle that all identifiable objects in VRS (e.g. Allele, SequenceLocation, etc.) +would be *true* value objects. This meant that they should be immutable and contain only required fields that are +necessary to uniquely identify the object. This approach somewhat simplified the ability to genertate the digests by +allowing the computation of the digest to be based on the entire object. + +In VRS 2.0 we deviated from this principle by allowing optional attributes to be added to VRS identifiable objects. +This was done to allow for the VRS to be more flexible, easing implementers requirements to pass useful attributes +as part of the identifiable objects without additional complexity. + +As a result, we had to introduce a new field in the digest model called *ga4gh.inherit* which is described in detail +in the section on :ref: `ga4gh-inherent-properties`` + + +IRIs over CURIEs +---------------- + +In VRS 2.0 we moved away from the use of CURIEs in favor of |iris| or more specifically IRI-References. Several +factors played a role in this decision. + +The main decision to move away from CURIEs occurred as a result of reviwing the approach the FHIR standard +has taken in their *CodebaleConcept* datatype. The *Coding.system* attribute uses a URI instead of namespaces. + +Using URIs instead of Namespaces when sharing data between organizations offers global uniqueness, explicitness, +and interoperability. URIs avoid the ambiguity and context dependency of namespaces, align with modern web +standards, and ensure seamless integration across heterogeneous and distributed systems. These advantages make +URIs the superior choice for robust, scalable, and interoperable communication. + +Choosing to use IRIs over URIs was made because IRIs provide a more inclusive, flexible, and user-friendly +approach to data sharing than URIs, particularly in internationalized or multilingual contexts. By supporting +Unicode characters, IRIs reduce complexity, enhance readability, and align with modern web standards, making +them the preferred choice for global data exchange. + + + +IRI-References over IRIs +------------------------ +We opted for the general use of IRI-References as a way to provide a more flexible approach to the use of IRIs +in the VRS and GKS messages. IRI-references (relative IRIs) benefit the users be allowing efficient, localized +references within a document or local document system. IRI-References do not prohibit the use of absolute IRIs +and can be easily converted to absolute IRIs when needed. + + +VRS identifier syntax and versioning +------------------------------------ + +The VRS identifier syntax is comprised of the following components: + + + +There has been much discussion over the idea of including a version number in the VRS identifier. + + + + + diff --git a/docs/source/appendices/index.rst b/docs/source/appendices/index.rst index 82ac3a98..18970e52 100644 --- a/docs/source/appendices/index.rst +++ b/docs/source/appendices/index.rst @@ -9,4 +9,5 @@ Appendices ga4gh_identifiers resource_identifiers truncated_digest_collision_analysis + design_decisions glossary