When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. You will find the GovStack issue queue on Jira.

Please note we have a code of conduct, please follow it in all your interactions with the project.

The GovStack community understands that there are a wide variety of people from different backgrounds that have valuable insight into the work GovStack is doing. Therefore, we provide multiple ways in which people from those different backgrounds can interact and give us their insight. Here are three:

1. Proposing changes via a pull request

Some members of the community will have experience using git to directly interact with specification content and you may do so with the following process.

Note that the content in the GovStack specifications follows the markdown standards applied by the GitBook tool.

1. Check our issue queue first to see if anyone else has already reported this issue.

2. Create a new "bug" and tell us about the problem that you see.

3. The maintainer of this section will be alerted and work with you to decide what changes should be made.

4. If invited to do so, create a pull request in the GovStack Specifications repository, including the issue number and short description in the pull request title, for example: {issue number] - {short description of the change}- an example would be gov-001 - Adding contribution information ``Note that pull requests that do not mention an associated issue number will not be alerted to our maintainers.

5. Once the issue describes the reason for a change and links to the change you propose, tag the issue with the correct building block tag so that a maintainer for that building block is alerted.

6. The maintainer will work with you to ensure that the change meets our standards for inclusion.

7. Once a maintainer approves the change, a release manager will be alerted to commit the change.

8. We value all contributions to the project and, even if the change is not accepted, we always strive to give feedback that helps you understand the decisions taken.

2. Proposing a change via GitBook

Other people may prefer to interact with the GovStack specifications by proposing their changes

1. Make an issue in the issue queue.

2. Describe the changes you propose in the issue.

3. Tag the issue with the appropriate building block tag to alert Maintainers in that area of the project.

4. Request access to GitBook as an Editor.

5. Create a new Change Request in GitBook in the "GovStack Specification - main" space which is where we work on new changes. Add the issue number to the subject of the change request in the format {issue number] - {short description of the change}

6. The maintainer will work with you to ensure that the change meets our standards for inclusion.

7. Once a maintainer approves the change, a release manager will be alerted to commit the change.

8. We value all contributions to the project and, even if the change is not accepted, we always strive to give feedback that helps you understand the decisions taken.

3. Proposing a change via email

Finally, some people might prefer to simply send an email:

1. Send an email to the GovStack issue queue automatically, describing the change you think should be made and include a link to the public page of the part of the specification that needs the change.

2. An issue in our issue queue will be automatically created and a maintainer will be in contact with you to work on the change together.

As with any software implementation, there are constraints and limitations in the GovStack approach that must be addressed. In any country context, there will be deficiencies that present challenges to any technology implementation. In the context of GovStack, the constraints and deficiencies that may be present must be considered at the outset of any project.

Here is a list of potential deficiencies that may be encountered with high-level descriptions:

Additionally, the Principles for Digital Development are especially relevant when designing for low resource setting. Refer to https://digitalprinciples.org/ for information on these Principles.

Each building block specification SHOULD specify mitigations for these issues.

Developed by Max Carlson, Kristo Vaher, Steve Conrad, Dr. P. S. Ramkumar, Uwe Washer, and Trevor Kensey

This document is intended to provide guidance for building block working groups and developers of products that will be integrated into a GovStack implementation. It also provides guidlines for implementers and system integrators who are deploying solutions that leverage the GovStack approach. It provides guidelines and principles that should be considered by all building blocks and cross-cutting requirements that must be considered for any GovStack project.

This will accelerate the collaborative development of best-of-breed digital public goods, enhancing efficiency and transparency across the world - especially in low-resource settings.

2.1 GovStack and the Building Blocks Approach

GovStack aims to provide a reference architecture for digital governance software to support sustainable development goals. Rooted in a "Whole-of-Government" approach, the GovStack Framework provides a methodology for leveraging common technology components and infrastructure to more easily create and deploy interoperable digital platforms which can address high-priority use cases across multiple sectors. The guidelines and requirements described in this document provide a framework for the development of digital building blocks oriented toward this goal.

2.2 Criteria for Building Blocks

The following provide criteria and definitions for Building Blocks, developed by organizations whose work is focused around achievement of the Sustainable Development Goals (SDGs).

SDG Digital Investment Framework

The SDG Digital Investment Framework, developed by the International Telecommunication Union (ITU) and the Digital Impact Alliance (DIAL), has formally defined criteria. Building blocks MUST meet the following criteria:

• Reusable software components

• Licensed as open source, proprietary, or freely available with Open Access to data

• Facilitates one or more generic Workflows

• Applicable to multiple SDG Use Cases across multiple sectors

• Interoperable with other ICT Building Blocks

• Designed for Scalability

• Designed for Extensibility

• Standards Based Conformance or Compliance

Digital Public Goods Alliance (DPGA)

Additionally, the Digital Public Goods Alliance has created a definition of Building Blocks. In this definition, a building block:

• Refers to software code, platforms, and applications that are interoperable, provide a basic digital service at scale, and can be reused for multiple use cases and contexts.

• Serves as a component of a larger system or stack.

• Can be used to facilitate the delivery of digital public services via functions, which may include registration, scheduling, ID authentication, payment, data administration, and messaging.

• Building blocks can be combined and adapted to be included as part of a stack of technologies to form a country’s Digital Public Infrastructure (DPI).

• Building blocks may be open source or proprietary and therefore are not always DPGs.

"Building blocks can be as simple as a common set of rules or protocols (for example email programs like Simple Mail Transfer Protocol - SMTP), or complex (for example an open-source health information system like the DPG, District Health Information Software - DHIS2)“

Characteristics of building blocks:

• Autonomous: building blocks provide a standalone, reusable service or set of services, they may be composed of many modules/microservices.

• Generic: building blocks are flexible across use cases and sectors.

• Interoperable: building blocks must be able to combine, connect, and interact with other building blocks.

• Iterative evolvability: building blocks can be improved even while being used as part of solutions.

Per the DPGA definition, to be considered a building block, solutions must meet the following technical requirements determined by the GovStack Initiative which includes:

1. Open API, Open API Specifications, Rest API

2. Packaged in a container

3. Include a information mediator where communication flows between services that are not co-located

2.3 Building Blocks

Building blocks are software modules that can be deployed and combined in a standardized manner. Each building block is capable of working independently, but they can be combined to do much more:

Building blocks are composable, interoperable software modules that can be used across a variety of use cases. They are standards-based, open source and designed for scale.

Each Building Block represents, as much as possible, the minimum required functionality (MVP) to do its job. This ensures each Building Block is usable and useful on its own, and easily extensible to support a variety of use cases.

A Building Block is composed of domain-driven microservices, modeled as closely as possible on existing roles and processes. This helps ensure each building block is as useful as possible in the real world.

Building Blocks exchange data using lightweight, human-readable data that can easily be extended where needed. Data models and APIs are described in a lightweight manner that’s human-readable, allowing them to be easily and quickly understood and validated.

2.3.1 Building Blocks and UI/UX

A building block may also be an application which provides re-usable interfaces:

1. An admin-only form builder which facilitates building user interfaces (e.g., select questions to be displayed in a maternal-and-child-health registration process)

2. User interfaces (i.e., forms) which can be used in lieu of individual end-user apps building their own forms (e.g. I’m building a new maternal and child health application; I’d like to use a registration screen flow that’s been pre-built in the registration building block as part of a larger, composed application.)

3. A public API which exposes the critical back-end services performed by this BB (adding a mom to a database; checking for a mom’s enrollment status in a program) to be used (as a microservice) by existing or new applications with legacy/bespoke needs (e.g., i’ve already got a maternal and child health app that the CHWs are using, and I want to send a webhook to the registration BB after a CHW clicks “submit” on our custom form.)

2.4 Cross-Building Block Communication

A building block is only so useful on its own. In practice, building blocks MUST be connected together in a secure, robust, trusted manner that facilitates distributed deployments and communications with existing services.

It is STRONGLY RECOMMENDED that a building block use an information mediator (as described below and in the Information Mediator Building Block specification) for any communications across the internet. An Information Mediator is not required for communication between building blocks which are co-located. In this case, communication may occur using standard API calls.

2.4.1 Federation and Data Exchange Requirements

Each building block deployment SHOULD use an Information Mediator to federate and communicate with other data consumers and providers, particularly when communicating between services that are not co-located. This ensures the confidentiality, integrity, and interoperability between data exchange parties. An Information Mediator MUST provide the following capabilities:

• address management

• message routing

• access rights management

• organization-level authentication

• machine-level authentication

• transport-level encryption

• time-stamping

• digital signature of messages

• logging

• error handling

• monitoring and alerting

• service registry and discovery

Refer to the full description of the Information Mediator Building Block for more information.

2.4.2 Organizational Model

In order to effectively deploy a software solution using the Information Mediator, several policies and processes will need to be applied. This section briefly describes that organizational processes that must be in place.

First, a central operator will be identified and created. This organization will be responsible for the overall operation of the system, including operations and onboarding new members. Policies and contractual agreements for onboarding need to be created.

Trust services need to be set up internally or procured from third parties, including timestamp and certificate authorities. This provides the necessary infrastructure to support distributed deployments.

Finally, members can be onboarded and provided with access to the Information Mediator and methods to register the services that they provide as well as discover services that are available.

Once agreements are in place, members can deploy new services in a decentralized, distributed manner. Before deploying a new service, the central operator must be notified of any changes to access-rights, including organization and machine-level authentication before it can publish or consume data.

2.4.3 Technical Architecture

This section provides an overview of the technical processes and architecture that must be implemented once the organizational model has been created.

1. A Central Operator is responsible for maintaining a registry of members, the security policies for building blocks and other member instances, a list of trusted certification authorities and a list of trusted time-stamping authorities. The member registry and security policies MUST be exposed to the Information Mediator.

2. Certificate authorities are responsible for issuing and revoking certificates used for securing and ensuring the integrity of federated information systems. Certificate authorities MUST support the Online Certificate Status Protocol (OCSP) so that an Information Mediator can check certificate validity.

3. Time-stamping authorities securely facilitate time stamping of messages. Time stamping authorities MUST support batched time stamping.

4. The Service Registry provides a mechanism for building blocks to register the services that they provide and for other building blocks to discover and consume those services. Any services provided or consumed by a Building Block that leverages the Information Mediator architecture MUST use this service registry functionality.

2.5 Keywords and Definitions

Within this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

2.5.1 Building Block-specific definitions

The following provides definitions for terms that are used by various building blocks.

Registration: Any approval/license/certificate issued by a public entity as a result of a request/declaration made by a user of the public service. The result of a “registration” is usually a number and/or a document (called certificate, license, permit, authorization, registration, clearance, approval, etc.)

Authentication: This is the technical process of establishing that the credentials (i.e. username, password, biometric etc.) provided by a party (user, system, other) is valid and that the party can be granted basic access to system resources with default access rights. Note that authorization also needs to be applied for a party to access protected resources.

Authorization: This is the technical process of establishing whether or not an authenticated party has rights to access a given protected resource. Access rights can typically be granted or revoked administratively on a read-only and/or read-write and/or execute basis through an administrative provisioning process. Permissions or rights defined for a party typically manifest in an access token that is granted at the time of authentication for the party. Hence the processes of authentication and authorization are intrinsically related.

Workflow Terminology: See more comprehensive descriptions of the workflow terminology in the Workflow and Business Process Automation Building Block specification.

• (Workflow) Activity - a single step in a workflow process.

• (Workflow) Process - a workflow process contains one or many activities.

• (Workflow) Instance - an instance of execution for a workflow process.

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people

• Being respectful of differing opinions, viewpoints, and experiences

• Giving and gracefully accepting constructive feedback

• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience

• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind

• Trolling, insulting or derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others’ private information, such as a physical or email address, without their explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

The GovStack initiative aims to build a common understanding and technical practice on fundamental reusable and interoperable digital components, which we collectively refer to as Building Blocks. Our effort is expert-driven and community-based, and includes the participation of multiple stakeholders to bring together expertise for strengthening a government's cross-agency architecture view.

Our focus is to enable countries to kickstart their digital transformation journey by adopting, deploying, and scaling digital government services. Through the digital "building blocks" approach, governments can easily create or modify their digital platforms, services, and applications by also simplifying cost, time, and resource requirements.