6.4 Quality

govstack-cfr quality related requirements

govstack-cfr-quality

Quality cross-functional requirements define what a Building Block must provide so that it can be evaluated, tested and used by people who did not build it. This covers documentation, standards compliance for user-facing components, accessibility, testability and localization. A Building Block that lacks these qualities may work internally but cannot be meaningfully assessed during procurement, verified during compliance testing or operated across different countries and user populations.

#1 English documentation is provided (REQUIRED EXTENSIBLE AUDITABLE) (previously 5.5)

govstack-cfr-quality#req-1

The Building Block provides written documentation in English that covers installation, configuration and operational use. Documentation is stored alongside the source code in the same repository. Where applicable, documentation is generated directly from code (for example, inline API annotations or structured comments).

English serves as the shared working language across GovStack implementations. Without it, no reviewer, integrator or procurement authority can easily evaluate the Building Block and related materials.

#2 Web user interfaces comply with HTML5 and CSS3 standards (REQUIRED EXTENSIBLE OBSERVABLE)

govstack-cfr-quality#req-2

Every web-based user interface delivered by the Building Block produces valid HTML5 markup and valid CSS3 styling. The interface follows responsive design principles and accessibility best practices. Compliance can be verified through standard HTML and CSS validation tools applied against representative pages of the running application.

This requirement applies only when the Building Block includes a web UI component.

#3 Applications meet the accessibility requirements of WCAG 2.1 at the AA level (RECOMMENDED IMMUTABLE OBSERVABLE)

govstack-cfr-quality#req-3

All user-facing applications conform to the Web Content Accessibility Guidelines 2.1 at AA level. This means the application is usable by people with disabilities, including those who rely on screen readers, keyboard-only navigation or alternative input devices. WCAG 2.1 AA is a legal baseline in many jurisdictions and a core condition for inclusive government services. Compliance can be verified through automated accessibility scanning tools combined with structured manual testing against the WCAG 2.1 AA success criteria.

More: https://www.w3.org/TR/WCAG21/

#4 OpenAPI specification is provided (RECOMMENDED EXTENSIBLE OBSERVABLE) (previously 5.6)

govstack-cfr-quality#req-4

The Building Block publishes a machine-readable API definition using the OpenAPI 3.x specification format for every external-facing service endpoint. The specification file validates against the official OpenAPI schema without errors. This specification is the primary contract that other Building Blocks and integrators rely on; without it, integration depends on informal knowledge and point-to-point agreements that break at scale.

More: OpenAPI Standard, Swagger OpenAPI 3.0 Specification.

#5 Functional scope of the system is defined and documented in clear business use cases and user stories (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-quality#req-5

The Building Block documents its functional scope using business use cases and user stories that describe what the system does, for whom and under what conditions. This documentation establishes the boundary of what the Building Block is responsible for, which directly determines what must be tested and what falls outside scope. A Building Block with undocumented scope cannot be reliably evaluated for compliance or compared against alternatives during procurement.

#6 All end-user functionality is covered by functional tests, including both UI and API interactions (RECOMMENDED EXTENSIBLE AUDITABLE)

govstack-cfr-quality#req-6

Every feature accessible to end users - whether through a UI or an API - has a corresponding automated test that exercises the expected behavior and verifies the outcome. Test suites include API contract tests, integration tests and UI tests where applicable. Full coverage means that a change to any user-facing behavior triggers at least one test failure if the behavior breaks, which is essential for regression safety across Building Block versions.

Tests can be run in continuous integration pipelines and produce a pass/fail result per test case.

#7 Compliance test mock/example implementation is provided (RECOMMENDED REPLACEABLE OBSERVABLE) (previously 5.26)

govstack-cfr-quality#req-7

The Building Block provides a working mock or example implementation that demonstrates API endpoints with realistic request and response payloads. This implementation runs independently and responds to API calls as defined in the OpenAPI specification. Its purpose is to enable third-party compliance testing: evaluators and integrators can verify their client code against the mock without access to a full production deployment. See GovStack BB Template Examples for reference.

#8 Building blocks are localizable (RECOMMENDED EXTENSIBLE AUDITABLE) (previously 5.27)

govstack-cfr-quality#req-8

Where a Building Block has a user-facing interface, it supports presenting content in the user's local language. The Building Block is designed to support multiple locales without requiring changes to application logic when a new language is added.

This requirement exists because GovStack operates across countries with different official languages. A Building Block that hard-codes a single language cannot serve its intended international audience (including for countries that internally support multiple languages).