2023-02-03 - Comments on Current Specification

Owned by Wes Brown
Last updated: Feb 14, 2023 by Esther Ogunjimi
10 min read

General

Template Feedback

Add content examples so that it is more clear what types of content each section should include and so that consistent formatting can be defined

Data Structures

  • Needs description

  • Need to define the common approach for describing data elements and the associated fields

    • Swagger is great but we want to have something in the spec as well

Workflows

  • More detailed guidance and examples on what a workflow is supposed to be in this context and how they should be described and modeled is needed

Other Resources

  • More detailed guidance and examples on the type resources that should be included and the format for including them

Key Decision Log

  • Is this needed along with the history that we can get in github?

    • If so, what constitutes a "key decision"?

  • What format should we use for the decisions?

  • Date ordering of the decisions should be defined

Future Considerations

  • What is the intent here? Should this really be a part of a Specification?

BB-Specific Feedback

Information Mediator https://govstack-global.atlassian.net/browse/IM-28

2 Description https://govstack-global.atlassian.net/browse/IM-29

The guidance from the TC on when to use an Information Mediator (documented n the non-functional requirements document) should also be documented or referenced here.

6 Functional Requirements

  • How does a network diagram relate to functional requirements?

  • Sub-bullet points in 6.1.3 Registration appear are not formatted properly

  • The level of detail does not match what is described in the template, lots of APIs and technical details are described

7 Requirements Clarification

  • Should be moved to a sub-section of the Functional Requirements section

  • We should remove references to ‘Rooms’ as that is X-Road specific. We should instead talk about PubSub and how it should be implemented

8 Performance Requirements

  • Should be moved to a sub-section of the Cross-Cutting Requirements

9 Data Structures

  • The github urls are not a specific version or tag

  • The field-level information has no details

  • Why do some things have github resources and others do not?

10 Service APIs

  • Are the swagger links linking to a specific version or just the most recent?

  • Are the colors supposed to signify something? If so, create a legend

11 Workflows

  • The referenced workflows should be here instead of the Functional Requirements section

  • 11.1 Where is the sequence diagram?

12 Key Decision Log

  • Order by date, either ASC or DESC but consistently

  • Level of "key decisions" here is not consistent

14 Annexes and Appendices

  • This seems to be a catch-all for a lot of different kinds of content. This needs to be reviewed to see what really needs to be included in the spec, what can be moved into other sections within the spec, and should be moved to another location (Confluence)

 

 

Registration

This BB appears to be a functional description of one specific solution (UNCTAD eRegistrations) and not a general-purpose specification for Registration functionality. In my opinion, this specification does not adhere to the GovStack standards and needs significant revisions

3 Key Digital Functionalities

  • The first functionality is a No-Code Development Platform? This doesn't seem related to registration functionality and is more of an implementation detail

  • Registration will involve the creation of forms – it will likely have a UX component. and we need to define how that process will work between the Registration BB, UI/UX and other BBs.

5 Functional Requirements

  • 5.1.1 - Once again, No-Code seems like an implementation detail and not a requirement in registration specification

  • 5.1.2 - Describing specific UI requirements should not be a requirement for a registration specification

  • 5.2 - The spec should not be defining the specifics of how a UI should look/work, it should be defining the functionality that is required to provide the set of services needed (as defined by the Use Cases)

  • 5.3 - What is the value of this table?

  • 5.4 - This should be in the Cross-Cutting Requirements section

6 Data Structures

  • 6.1 - Are these different from the standards defined in the Arch Requirements? If not, remove them

  • 6.2 - What type of relationships are these and on what fields?

  • 6.3 - There is no detail about what these resources should contain

7 Service APIs

  • 7.1

    • The resource model should be in the Data Structures section

    • The APIs should be defined in the spec, not referenced in github

    • Is the Standards sub-section needed?

  • The core APIs for the registration process are not defined in this section. There is only a statistics API. I would expect to see APIs for submitting a registration, updating a registration, etc.

10 Key Decision Log

  • Dates should be included for decisions

11 Future Considerations

  • Should this comments section be in the spec?

 

 

Digital Registries

2 Description

  • This BB is described as a ‘no-code’ application with graphical interface to design databases. This is not true for digital registries – there are APIs defined and any candidates should provide that functionality through APIs. The APIs are described in the BB spec - we should remove references to no-code platform

6 Functional Requirements

  • Should functional requirements be organized around use cases? I would expect to see a list of the high-level functional requirements with details, irrespective of any use cases

7 Data Structures

  • 7.1 - Are these different from the standards defined in the Arch Requirements? If not, remove them

  • 7.2 - What type of relationships are these and on what fields?

  • 7.3 - How do the referenced "Data Element" relate to the resources mentioned in 7.2?

8 Service APIs

  • The schemas should be in the Data Structures section

  • The github links are not valid

  • The swagger api definitions will not load

  • Standards info at the bottom is not needed

9 Workflows

  • This BB really has no workflows? I suspect we need a better definition for Workflow so it is more clear what is expected to be defined here

Key Decision Log

  • Missing

Appendix 1 & 2

  • This should be moved into the Data Structures section

 

 

Identity

7 Data Structures

  • No field information for the data objects

8 APIs and Services

  • Change title to Service APIs to be consistent

  • Use embedded swagger for APIs like other BBs

  • 8.2

    • This doesn't seem like the right place for this content. The Functional Requirements section could be a better fit

    • Use the same terminology for MUST, SHOULD, MAY, etc rather than Mandatory, Recommend, Specific, and optional

9 Workflows

  • I guess that these are ToDo?

  • Should the use cases be moved from Functional Requirements to Workflows, if that is what they really are?

11 Key Decision Log

  • Dates should be included for decisions along with deciders

  • Only "Key" decisions should be noted

 

 

Payments

4 Payment Infrastructure Deployment Scenarios

  • Why is this a dedicated section? It is not defined for any other BBs and should likely be put into another section or removed entirely (just kept as a Confluence page)

  • The BB spec should talk about the different components that make up a Payments BB (as several of the other BBs do). These can be borrowed from the G2PConnect work. And the Payments spec should clearly describe which components are in the scope of the BB. Throughout the BB, the spec should talk about component manages each part of a payment flow – switch, core banking, mobile money, account mapping, etc.

5 Key Digital Functionalities

  • The key digital functionalities shouldn’t be rooted in use cases (G2P payments, etc). Should rather be core functionalities – like the ability to lookup an account based on foundational ID or mobile number. 

6 Cross-Cutting Requirements

  • The additional requirements are not detailed enough and/or not non-functional requirements

7 Functional Requirements

  • Voucher management system is not a core component of payments. And we are missing things like account lookup (which is briefly described under voucher management) and core banking. Again, refer to G2PConnect

9 Service APIs

  • There should be API definitions for each component - payment switch, account mapping, core banking functionality, etc.

  • The APIs are very incomplete – we should have clear APIs defined for core use cases. Mojaloop has well-documented flows that can be used to extract what APIs would be needed. Or can reference the Mifos PaymentHub as well

  • 9.1, 9.2, 9.6 - Where are the API endpoints defined?

  • 9.3, 9.5 - Use embeded swagger APIs

  • 9.4 - We should not reference other unversioned specifications. What happens if mojaloop changes their spec?

  • 9.6.6.1 - We don't need to document the status codes unless they deviate from the HTTP standard (which they shouldn't)

10 Workflows

  • Where is 10.1?

  • If a workflow has different options, shouldn't they each be considered a separate workflow?

  • Does the level of detail for these workflows contain too much internal payment BB descriptions? Other BBs shouldn't need to know about the internals of how payment systems work

  • There is a ton of content here but I'm not sure that this is the right place for it (or if this content really needs to be so detailed)

11 Other Resources

  • Standards are not needed here

  • GovStack Resources do not need to be linked here

  • Google Drive documents should not be linked

  • 11.3 The links to this content should be located where they are referenced within the spec

12 Key Decision Log

  • Dates should be included along with deciders

  • Comments seems out of place here (and in the spec in general)

 

 

Consent

4 Key Digital Functionalities

  • Remove links to Google Drive docs in functionalities

5 Cross-Cutting Requirements

  • Remove content from Arch Requirements

7 Data Structures

  • 7.1 Convert the diagrams to align to similar relationship diagrams from other BBs

  • 7.2 Does this belong in this section?

  • 7.3 Are these different from the standards defined in the Arch Requirements? If not, remove them

  • 7.4 Just put the models here, don't reference another document

8 Service APIs

  • The APIs need to be listed here and included as embedded swagger APIs

  • Comments and suggested edits should happen on this page, not in a linked spreadsheet

  • The github link just goes to the root repo, not to an OpenAPI spec

9 Workflows

  • The numbering is off here, 4 should be 9 and it should start with 9.1 instead of 4.4

  • Embed the diagrams so that they are viewable within the spec

10 Other Resources

  • Use a sentence rather than NA, something like "There are no other resources for the Consent Building Block."

11 Key Decision Log

  • This looks great, could also include who made the decisions

 

 

Workflow

4 Key Digital Functionalities

  • More detail is needed here, at least to be consistent with the other BBs and how the BB template describes this section

5 Cross-Cutting Requirements

  • Remove content from Arch Requirements

6 Functional Requirements

  • Referenced image is missing

  • Some markup issues

  • For Future Consideration should not be included in the spec

7 Data Structures

  • Remove future support from spec

  • While linking to a specific version in swaggerhub is fine, I think that the spec should also contain the schema as well

8 Service APIs

  • The APIs need to be listed here and included as embedded swagger APIs

  • In discussion topics and future plans should not be included in the spec

9 Workflows

  • Invalid url near the top

  • Why are we organzing around use cases for workflows? The content here should be organized around functionality that relates to other BBs

10 Other Resources

  • Discussions should not be in the spec

  • UI Examples

    • The linked images are not loading

    • This seems like it would better be located in the Workflows or Functional Requirements section

11 Key Decision Log

  • Only include decisions that impact the spec, not discussions/thoughts or things that may be done in the future

 

 

Messaging

4 Key Digital Functionalities

  • Need additional detail and evaluation of the functionalities listed. The supposed functionalities mentioned are not specific enough

5 Cross-Cutting Requirements

  • These need to be reviewed, there is a lot of very opinioned requirements here that may not be needed

6 Functional Requirements

  • 6.2 This doesn't seem to belong in this section

  • 6.3 This doesn't seem to belong in this section

  • 6.5 Remove this section from the specification

7 Data Structures

  • 7.2 Are these different from the standards defined in the Arch Requirements? If not, remove them

  • 7.3 The schemas for all messaging-related elements should be defined here

8 Service APIs

  • Nothing is defined here

9 Workflows

  • 9.1 - This can be removed

  • 9.2

    • The sub-item numbering appears to be off

    • The sequence diagram is not displaying properly

  • 9.3

    • The sub-items are numbered incorrectly

      • I am unclear what this content is supposed to describe

      • The content here needs some significant review and editing

10 Other Resources

  • This content should likely be in the workflow and aligned to the workflow format, once defined

11 Key Decision Log

  • This is not a meeting notes page, that content belongs in Confluence not in a spec

 

Scheduling

7 Data Structures

  • Standards - Are these different from the standards defined in the Arch Requirements? If not, remove them

  • Data Elements is lacking detail (eg field type)

8 Service APIs

  • API Standards do not need to be included unless they are different from the Arch requirements

  • The APIs need to be listed here and included as embedded swagger APIs

9 Workflows

  • This is nothing like any of the other Workflow sections, need to decide on a format

  • Workflows should not, in my opinion, be organized around specific use cases

    • Perhaps this content can be used as the basis for the Use Case Example Implementations?

10 Other Resources

  • Links to other GovStack documents are not needed

11 Key Decision Log

  • Include dates and who was involved in each decision

Tasks

Update the specification template to show expected structure and format of the content in each section
Update with any decisions made here
Develop a more detailed approval process for checking content against standards as it is approved for inclusion (see as an example - sorry, yet another Drupal reference but I know where to find what I need there after so long!)