5 Specification Framework
This document is intended to provide guidance for implementing teams of governments and developer teams of software providers who want to adhere to GovStack's technical best practices. It provides guidelines and principles that should be considered by all building blocks and cross-functional requirements that must be considered for any GovStack-based project.
This will accelerate the collaborative development of best-of-breed digital government services and Digital Public Infrastructure (DPI), enhancing efficiency and transparency across the world - especially in low-resource settings.
5.1 Building Block Specification
Specification (either a high level GovStack specification or that for a building block) consists of a description and one or more (mostly technical) requirements.
5.1.1 Specification Identifiers and Naming Conventions
Identifiers are important for referencing within GovStack as well as outside GovStack (for example in tender documentations). These names of specifications for building blocks need to be unique.
The schema used is govstack-[type]-[name] for the specification, optionally govstack-[type]-[name]-[version] when referring to a version and a requirement can be referred to similarly: govstack-[type]-[name]-[version]#req-[requirement-number]
Cross-functional requirements (the core overarching requirements of GovStack) have the following identifiers:
govstack-cfr-development
govstack-cfr-deployment
govstack-cfr-architecture
govstack-cfr-quality
govstack-cfr-security
govstack-cfr-data
The older verisons of specifications used conventions bb-* and until updated, may still be referenced by their older name.
5.1.2 Specification Versioning (major.minor.patch)
Every GovSpecs specifications document (which includes the whole document, all of its individual requirements) adopts a three-part semantic version number. The label appears in the header of the human-readable text, in the machine-readable schema, and in the metadata that GovMarket can use. A major increment signals a change that can break an existing integration. Examples include removal or fundamental rewriting of a REQUIRED rule, alteration of an immutable interface signature, or a shift in the data model that forces re-migration. When the major digit changes, dependent specifications must assess and, if necessary, revise their own versions before release. The workgroup provides a migration note that lists breaking points, affected test cases, and a recommended upgrade path. A minor increment adds new capability while preserving full backward compatibility. This can involve new OPTIONAL or RECOMMENDED rules, extensions to an existing enumerated value set, or clarifications that broaden but do not narrow acceptable behaviour. Implementations that follow earlier minor versions continue to pass validation without code changes, though they may adopt new tests to display improved coverage in GovMarket. A patch increment corrects errors or omissions that prevent a rule from working as intended. Typical patches fix typographical mistakes, update references to external standards, or align an example with normative text. No behaviour visible to an integration partner may change in a patch; therefore, automated test suites should continue to pass without modification.
Requirements individually are not independently versioned. If a requirement needs to be updated, the whole specification is updated.
As major.minor.patch is a shift from the previous version numbers, it is still an incremental update, thus every new or updated specification that is conforming to the new specification scheme and requirements is expected to publish their first version as 2.0.0 and continue from there onward.
For example, version 2.0.0 of the Workflow building block could be referred to as govstack-bb-workflow-2.0.0
Older versions of specifications use YYQN version naming scheme applied to all specifications. These will be updated to match new expectations laid out here. 25Q2 is expected to be the last version number of this scheme.
5.1.3 Specification Requirements Classification
Each specification consists of a description and then clearly defined requirements. Each requirement must have a unique identifier and then a set of one or more requirements based on the classification defined below.
5.1.4 Unique Identifier
Each requirement has a unique IDENTIFICATION NUMBER. While most specifications will seem to have requirements in sequental numbers, it is expected that numbers under the same unique specification will never be reused for another purpose. This if a requirement becomes outdated or irrelevant, its classification is updated and its number is never reused.
5.1.5 Requirement Level Keywords
GovStack specifications are a combination of descriptions and technical requirements. Each requirement is classified following this model and ONE one of the keywords applies at the time. If this classification changes, then the specification must update version number as well.
REQUIRED - marks a rule that every conformant solution must satisfy exactly as written. Failure to meet a single REQUIRED element disqualifies the product from GovStack compliance, thus all REQUIRED requirements have to be met for a solution to be GovStack compliant. RECOMMENDED - designates a rule that improves quality but remains optional. GovMarket will calculate the proportion of RECOMMENDED rules a solution meets and expose that figure to buyers as an additional decision signal. DRAFT - captures a proposal that has reached public view yet still needs evidence or consensus. It reserves an identifier and lets implementations experiment, but no compliance test will fail if a DRAFT rule is absent. DEPRECATED - freezes a rule that once applied but is now retired. The identifier persists for audit and traceability; future versions will never reuse it, preventing confusion in historical records.
Older versions of specifications apply previous versions of keywords and definitions: "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.
5.1.6 Extensibility and Replaceability Classifiers
GovSpecs adopts an object-oriented philosophy: each building-block specification behaves like a class, inheriting common traits from the cross-functional layer and exposing controlled variation points. To make that inheritance explicit, every requirement now carries a mutability tag that determines how child specifications or local overlays may treat it: INAPPLICABLE - appears only in an overlay or extended specification. It formally switches off an inherited extensible or replaceable rule for a given context, without altering the parent text, and records the rationale so automated validators understand why the rule no longer applies.
IMMUTABLE - the rule is considered frozen and static. Later versions may refine wording for clarity but must not alter its intent, scope, input, or output. Integrations built against an immutable requirement are guaranteed to keep working across all minor and patch releases. For example, govstack-cfr-architecture-5.12 (“5.12 Enforce Transport Security”) would be immutable; breaking this guarantee would demand a new major version of the entire specification that depends on it. EXTENSIBLE - additional constraints or features can be layered on without changing the original text. The base wording stays immutable, ensuring upward compatibility, while overlays can tighten or elaborate the rule or add additional functionalities to the same rule. Tests for the overlay must still confirm that all base behaviour passes unchanged. REPLACEABLE - the rule may be swapped out wholesale, provided the external contract - inputs, outputs, behaviour - remains identical. This enables technology substitution where policy or local ecosystems demand it.
Important! Each specification can only have one of these extensability and replaceability classifications similarly to the requirement general classification. If this classification changes, then the specification must update version number as well.
5.1.6.1 Extensibility and Replaceability
GovStack specifications can be extended and forked for various contexts. To implement variation safely, GovSpecs introduces machine-readable extended specifications, which must explain:
the parent specification version it extends (with its own unique specification name);
a list of requirement reclassifications (e.g., RECOMMENDED→REQUIRED, REQUIRED→INAPPLICABLE);
new requirements with unique identifiers;
dependency statements that show why each change is legal (immutable rules cannot be altered; extensible rules can be tightened; replaceable rules can be disabled or replaced).
A specification that is extended from an existing GovStack specification it must define in the header that it extends an existing specification, such as:
This approach somewhat mirrors profiling in HL7 FHIR and extension taxonomies in XBRL. Validators first enforce the base spec, then apply overlay rules, ensuring deterministic outcomes and auditability.
5.1.7 Example of a requirement
Or in case you wish to refer to specific version of the specification
Last updated
Was this helpful?