Archive of Conceptual Notes

Owned by Nico Lueck
Last updated: Aug 22, 2023
7 min read

Stages of Compliance

Title

GovStack Candidate Software

Non-compliant Software

Partially Compliant Software

Fully Compliant Software

Def

Software that is potentially compliant

Software that does not fulfill all MUST Key Digital Functionalities

Software that does fulfill all MUST Key Digital Functionalities and additional Cross-Cutting Requirements, Functional Requirements and API Services.

All integration scenarios possible.

Software that fulfills all MUST requirements and some SHOULD requirements of one or multiple Building Blocks Specifications.

All integration scenarios possible.

Evaluation Schema

Criterion

Partially Compliant Software

Fully Compliant Software

Criterion

Partially Compliant Software

Fully Compliant Software

Deployability via container

Availability of an adapter or native interfacing support

Fulfillment of MUST Key Digital Functionalities stated in the respective BB specifications

All

All

Fulfillment of Service API requirements (using the provided test harness, see Steps to check compliance against a GovStack API spec )

>=1

All

Fulfillment of MUST cross-cutting and functional requirements stated in the respective BB specifications

>=1

All

Fulfillment of SHOULD cross-cutting and functional requirements stated in the respective BB specifications

Optional

Optional

Fulfillment of MUST cross-cutting requirements stated in the Architecture BB specifications

>=1

All

Fulfillment of SHOULD cross-cutting requirements stated in the Architecture BB specifications

Optional

Optional

Usage rights (proprietary or FOSS license) of the software are stated.

Documentation for deployment, integration and configuration (incl. examples) is provided.

Categories of Compliance (Alternative suggestion to “compliance stages”)

Target group: Procurer and Integrator

Objective: Ease process of system integration and increase transparency. Not: gate keeping or certification processes

There is no minimum, every solution can be listed with its degree of compliance.

Deployment Check

Level 1

Level 2

Level 1

Level 2

Must be deployable via container

Must be deployable via container

 

Provide deployment scripts (Helm Chart in Kubernetes)

 

 

 

Interface Check

Level 1

Level 2

Level 1

Level 2

Fulfillment of at least one Service API (via adapter or native support)

Fulfillment of all Service APIs (via adapter or native support)

 

Fulfillment of all MUST API related requirements in the Architecture BB specifications (ch. 5.1-5.4, 5.6, 5.13)

Fulfillment of APIs can be tested using the provided test harness, see Steps to check compliance against a GovStack API spec

 

Requirements Specification Check

Level 1

Level 2

Level 1

Level 2

Fulfillment of all MUST Key Digital Functionalities stated in the respective BB specifications

Fulfillment of all MUST Key Digital Functionalities stated in the respective BB specifications

Fulfillment of at least one MUST cross-cutting and functional requirements stated in the respective BB specifications

Fulfillment of all MUST cross-cutting and functional requirements stated in the respective BB specifications

Fulfillment of at least one MUST cross-cutting requirements stated in the Architecture BB specifications

Fulfillment of all MUST cross-cutting requirements stated in the Architecture BB specifications

 

 

 

Stages of Compatibility (Alternative suggestion to “compliance stages” focusing on integration)

The following categories are used to insert and list software provided by market actors in a GovStack catalog/marketplace.

Title

GovStack Candidate Software

Partially Compatible Software

Fully Compatible Software

Def

Software that is potentially compatible

Software that does not fulfill all MUST requirements of a Building Block Specification, but partially fulfills MUST and SHOULD functional requirements and can be interfaced via an adapter. Usually, the functions are a useful additions to the GovStack ecosystem.

Similar to Level 1 Integration Scenario, see below

Software that fulfills all MUST requirements and to certain degree SHOULD requirements of one or multiple Building Blocks Specifications.

 

 

Similar to Level 2 and 3 Integration Scenario, see below

Criteria

 

  1. Deployability

    1. Attest the deployability via container.

  2. Interfaceability

    1. Attest the availability of an adapter

  3. Functional Requirements

    1. Declare degree (percentage) of fulfillment of MUST APIs and SHOULD APIs

  1. Deployability

    1. Attest the deployability via container.

  2. Interfaceability

    1. Attest the availability of an adapter or native interfacing support

    2. Attest the usage of OpenAPI descriptions 3.0.0 or newer

  3. Functional Requirements

    1. Attest the fulfillment of all MUST APIs (using the provided test harness)

    2. Declare degree (percentage) of fulfillment of SHOULD APIs

  4. Non-Functional Requirements (“cross-cutting requirements”)

    1. Attest the fulfillment all MUST requirements stated in the Architecture BB specifications

    2. Declare degree (percentage) of fulfillment of SHOULD requirements stated in the Architecture BB specifications

    3. Attest the fulfillment all MUST requirements stated in the respective BB specifications

    4. Declare degree (percentage) of fulfillment of SHOULD requirements stated in the respective BB specifications

  5. Usage Rights

    1. Declare the usage rights (proprietary or FOSS license) of the software

  6. Documentation

    1. Declare the documentation for deployment, integration and configuration (incl. examples)

Integration Scenarios

work in progress

Level 1: Integrate non-compliant system

Description: A GovStack instance needs to be connected to an external, non-compliant system (does not meet all required API specs and other criteria), that is managed by an organisation outside of the GovStack instance.

Challenge: The GovStack instance operator needs to exchange data with but has no control over the target instance.

Justification: Different organisation / host, Different technology choices, Legacy obligations

Solution: Set up an empty Building Block instance with only an adapter gateway specific to the target system.

To Be revised

Requirements (Target System):

  • Authentication, e.g. SAML <-> JWT in HTTP headers

  • Filtering and aggregation logic

  • Adapter must publish static OpenAPI spec to Information Mediator, including JSON Schemas

Requirements (GovStack Adapter):

  • Data Translation,
    e.g. HL7 2.5/3.0  <->  JSON Schema

  • Protocol Translation,
    e.g. SOAP <->  REST

Benefits:

  • Quick connectivity

  • No migration scenario required in external system

  • No detailed harmonisation of IT governance principles

Flavors:

  • Partner organisation runs adaptor

  • Partner organisation only provides API & documentation

Level 2: Integrate partially compliant system

Description: A GovStack instance needs to integrate an partially compliant software/application (e.g. deployment requirement fulfilled but API only thorugh an adapter) inside of the GovStack instance.

Challenge: GovStack manages the installation of the instance, but has no influence on the development of the software.

Justification: Organisation requests specific software/application; software is not fully GovStack compliant

Solution: Set up a GovStack instance with the software and an adapter gateway.

To Be revised

Requirements (Target System):

  • Authentication, e.g. SAML <-> JWT in HTTP headers

  • Filtering and aggregation logic

  • Adapter must publish static OpenAPI spec to Information Mediator, including JSON Schemas

  • Packaged as a container (Docker/Docker Compose/OCI)

  • Include a complete OpenAPI/Swagger specification to be published to GovStack peers though the information mediator. Must include descriptions of all exposed APIs with schemas for payloads, including examples.

Requirements (GovStack Adapter):

  • Data Translation, e.g. HL7 2.5/3.0  <->  JSON Schema

  • Protocol Translation, e.g. SOAP <->  REST

DPG = Digital Public Good (related to FOSS)

Benefits:

  • Quick connectivity

  • No migration scenario required in external system

  • No detailed harmonisation of IT governance principles

Flavors:

  • Partner organisation runs adaptor

  • Partner organisation only provides API & documentation

Level 3: Integrate fully compliant system

Description: An existing software was adapted to fully meet GovStack requirements and can be deployed just like any other GovStack BB.

Challenge: Software must pass all GovStack compliance requirements

Benefits:

  • Re-use existing software

  • Profit from high application maturity

  • GovStack certification implies adherence to GovStack security standards

  • Visibility through listing as building block in the catalogue

To Be revised

Requirements (DPG):

  • Must have an accepted rating as a digital public good

  • BB must publish static OpenAPI specs to Information Mediator, including JSON Schemas

  • Web-Hooks

  • Docker Packages

  • GovStack needs to be able to build the package & analyse the source

 

Based on concept draft for integration scenarios by GovStack and OpenIMIS team

Suggestions for future releases

Please keep in mind that we do not aim to release integrators of BB from any responsibility and caution. Certain criteria are nice to have, but can be checked when the integrator chooses the fitting BB candidate from our marketplace (e.g. according to their security level).

Compliance Concept 1.0 (Purpose: Channel everyone interested to the process with minimal effort)

  • Differentiate in criteria 3 and 4 ((non-)functional requirements) between required and optional (similar to criterion 1)

  • Add security requirements

  • Add documentation requirements (e.g. Documentation on Business Flows, data mapping principles, test cases)

  • Add maintenance requirement e.g. “Receives regular updates/patches (> every 6 months)”

Compliance Concept 2.0 (Improve quality of being “GovStack compliant”)

  • Ask for declaration of reference e.g. “At least 1 existing real-life usage/in production usage/real world implementation.”

  • Make the ecosystem transparent e.g. “Integration is supported by multiple integrators”

  • Add further requirements in case of FOSS e.g. Public access to code repository, Active repository contributions, OSI approved licence

List of a former draft

  1. Interfaceability (Must): OpenAPI descriptions 3.0.0 or newer and pass all API test scripts either natively or through an adapter (automatic assessment by applicant)

  2. Deployability (Must): Be deployable via container and minimal ansible scripts (self-assessment by applicant)

  3. Usage Rights (Must): Usage rights are clearly defined in a proprietary or FOSS licence (self-assessment by applicant)

  4. Non-Functional (Must): Fulfill “cross-cutting requirements” stated in the Architecture BB specifications (self-assessment by applicant)

  5. Functional (Must): Fulfill “cross-cutting requirements” stated in the respective BB specifications (self-assessment by applicant)

  6. Security (Should): Fulfill ……. (self-assessment by applicant)

  7. Documentation (Should): Manuals and descriptions on …. [e.g. deployment, configuration, functionalities exceeding the specs] are publicly available (self-assessment by applicant)

  8. Maintenance (Should): Receives regular updates/patches (> every 6 months) (self-assessment by applicant)

  9. Reference (Should): At least 1 existing real-life usage/in production usage/real world implementation.

  10. Diverse Ecosystem (Should): Integration is supported by multiple integrators

  11. In case of Open Source (Must)

    1. Public access to code repository

    2. Active repository contributions

    3. OSI approved licence

Useful Attachments

First proof of concept by @Ingmar Vali , here: