5.2 Building Block Specification
This page gives a general overview about the technical details of what a GovStack specification is about.
Specification consists of a description and one or more (mostly technical) requirements. A Building Block specification is an extension of GovStack Architecture Specification's cross-functional requirements, which means that every specification (and thus every resulting software solution) must also comply with core cross-functional requirements.
In other words, even if a new Building Block may only have 5 requirements, it will also automatically have all of the requirements of GovStack core Architecture Specification.
5.2.1 Specification Identifiers and Naming Conventions
Identifiers are important for referencing within GovStack as well as outside GovStack (for example in tender documents). The names of specifications for Building Blocks need to be unique and never re-used. When a new specification is created, make sure it does not replicate an existing one.
The schema used is govstack-[document-type]-[name] for the specification. When referring to a version, then the schema is, govstack-[document-type]-[name]-[version]. When referring to a requirement then the schema is similarly: govstack-[document-type]-[name]-[requirement-type]#req-[requirement-number] and when together with version it is govstack-[document-type]-[name]-[requirement-type]-[version]-#req-[requirement-number].
The [document-type] for a Building Block specification would be "bb", for example govstack-bb-wallet.
Already existing cross-functional requirements (the core overarching requirements of GovStack) have the following identifiers:
govstack-cfr (main central specification)
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 they are updated to 2.0.0, may still be referenced by their older name.
Reserved Name Tags/Nodes
The following keywords have a specific meaning in GovStack namespace and should only be used in their own context. The following keywords cannot be a name or one of the words in a name of a Building Block specification.
govstack - This is the prefix node for every GovStack specification name. It is used always only at the very start of the specification name.
bb - This is a shorthand for a "building block". Every Building Block specifcation of GovStack has thus a full name prefix of "govstack-bb-", to differentiate core specifications, guides and other materials from Building Block specifications.
fr - This means functional requirements, a specific level of business functional requirements. These requirements are specific to a Building Block (such as govstack-bb-wallet-fr-*). Each "fr" can have its own sub-names (such as govstack-bb-wallet-fr-credentials).
Between 'bb' and 'fr' would be the building block specification name, with or without dashes (e.g. govstack-bb-information-mediator-fr).
cfr - This means cross-functional requirements, a specific level of technical requirements. CFR's can be GovStack core requirements (such as govstack-cfr-*) or Building Block cross-functional requirements (such as govstack-bb-wallet-cfr-*). Each "cfr" can have its own sub-names (such as govstack-bb-wallet-cfr-data).
Between 'bb' and 'cfr' would be the building block specification name, with or without dashes (e.g. govstack-bb-wallet-fr).
Cross-functional requirements are not required to be defined for Building Blocks, but govstack-cfr is always expected to apply to Building Blocks.
5.2.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 change 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 themselves are individually not versioned. If a requirement needs to be updated, the whole specification document has to be updated.
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.
Since every specification is essentially an extension of core Architecture Specification of GovStack, its correct definition would be for example: govstach-bb-workflow-2.0.0 extends govstack-cfr-2.0.0 (this is further covered below)
5.2.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 classifiers based on the classification defined below.
5.2.4 Unique Identifier
Each requirement has a unique IDENTIFICATION NUMBER within its own specification. 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 within that specification. If a requirement becomes outdated or irrelevant, its classification is updated to deprecated and its number is never reused.
For example, wallet specification requirement number 1 could be referred to as govstack-bb-wallet#req-1
This is important for external dependencies as a procudement requirement may refer to a specific requirement and this needs to be fundamentally unique when referred back years from now.
5.2.5 Requirement Level Classifiers
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 its 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, but future versions will never reuse it, preventing confusion in historical records (unless it becomes relevant again and gets any of the above classifiers).
If none of these classifiers is defined for a requirement, it is considered RECOMMENDED by default.
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". When specifications will be updated to match 2.0.0 core specification then the new classifiers have to be defined, however the wording can still be used within the specification requirement text itself.
5.2.6 Observability Classifiers
Each requirement may carry a verification classifier that defines how compliance can be confirmed. Exactly one of the following keywords applies at a time.
OBSERVABLE - compliance can be verified through external interaction with the running system. Observable means capable of being verified, measured, or proven true or false through testing, observation or experimentation. This includes API calls, protocol exchanges, behavioral tests or any method that does not require access to source code, configuration or internal infrastructure.
Observable requirements should be observable in one of the three following methods:
Automatically testable. Specifications could be tested automatically with a script or a compliance tool (like web API tests or Robotic Process Automation etc.).
Manually testable. If automatic testing is not possible: there is a defined test procedure and there is a clear pass/fail outcome - anyone following the documented steps should reach the same result.
Operationally observable. If neither automatic testing nor test procedure is possible, it should be operationally observable: verification relies on observing the runtime evidence or behavior. Outcome may not be binary or reproducible in identical conditions.
AUDITABLE - If compliance cannot be determined from external behavior alone and requires inspection of internals such as architecture documentation, source code, deployment configuration, access control policies or third-party audit reports. Specifications should pair each AUDITABLE requirement with a list of evidence artefacts the implementer must produce - for example architecture decision records, deployment diagrams or signed audit statements - so that the verification process remains deterministic even when manual.
If this classification changes for a given requirement, the specification must update its version number accordingly.
If neither of these classifiers is defined for a requirement, it is considered AUDITABLE by default.
5.2.7 Mutability 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:
IMMUTABLE - the requirement 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-security#req-1 (“#1 Transport security is enforced”) would be immutable and 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. Extended requirements can tighten the rule, but never broaden it. 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. A requirement like this can change the execution of the rule without changing the rule itself.
INAPPLICABLE - appears only in an 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 for that specific building block.
If none of these classifiers is defined for a requirement, it is considered REPLACEABLE by default.
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 the version number as well.
5.2.8 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 made inapplicable 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.2.9 Example of a specification definition
To define a new specification for a Building Block that returns weather data, it can be defined like this:
Or in case to be specific with versions:
This "extends govstack-cfr" is not necessarily required. If this is not defined for a specification which is still considered GovStack building block specification, then it is assumed by default. No GovStack building block can avoid compliant extension of core cross-functional requirements.
5.2.10 Example of a requirement
To define a new requirement for example for a new "weather" building block and I want to require that there is an API call which returns current weather based on some parameters (not shown here in the example) then it can be defined as a requirement like this:
... in which case it can be referred to as govstack-bb-weather-fr#req-7 requirement.
Or in case you wish to refer to specific version of the specification:
Was this helpful?