5.1 Specification Template

This is the recommended framework for a Building Block specification. The use of this template is optional, but it is highly recommended to be followed for each Building Block.

The core aspects of what a Building Block is and what a specification for GovStack is expected to be is listed under parent page 5 Specification Framework and 4 Building Block Architecture page.

The following is the document tree, with examples and sub-pages recommended for GovStack Building Block specification.

Building Block Title and Authors Page

GovStack specification must follow GovStack Specification Framework (the parent document of this Template document).

The first page of the specification should include the visual title page and a list of authors and the latest version number of the specification.

A building block specification should have a technical name and identifier following this format: govstack-bb-[name] where [name] is a unique business function describing keyword for the function, such as govstack-bb-workflow

Specifications are expected to be versioned using semantic versioning. Specific version of a spec can be thus referred to as govstack-bb-workflow-2.3.0

1. Version History

A simple table that records the major changes between published versions.

Recommended table format

Use a 3-column table:

• Version

• Author

• Comment

What to write in “Comment”

Keep each entry to 1-2 lines:

• What changed (one clear sentence)

• Impact: Breaking or Non-breaking

Optional (only if useful):

• Short note like “Editorial only” or “Security requirement update”

• Reviewer note (only if it is genuinely important)

Practical rule

If a change affects APIs, data schemas, or REQUIRED requirements, it must be listed here and must state whether it is Breaking or Non-breaking.

2. Description

Use this section to set the context and purpose of the Building Block without going into detailed requirements or APIs. A good description covers:

• Purpose and scope: Explain why the Building Block exists, what problems it solves and where it sits in the ecosystem. Keep it high‑level - save technical details for later sections.

• Context of use: Describe typical scenarios or sectors where the Building Block is needed.

• Approach and design choices: Note any overarching models or philosophies. State clearly if the description is focused on a particular approach and whether alternatives will be addressed in future revisions.

• Sub‑components overview: List the major internal modules or services the Building Block consists of and their roles. This helps readers understand the scope before they dive into detailed functional requirements.

• Out of scope: Briefly mention what is explicitly not covered in this specification to manage expectations and avoid misinterpretation.

Keep paragraphs short and avoid normative language. The description is explanatory, not prescriptive. It should leave the reader with a clear understanding of the block’s purpose, its main parts and the context in which it operates.

3. Terminology

Purpose: Give clear definitions for terms that are specific to the Building Block so that readers understand exactly what is meant in later sections.

What to include:

• Building block–specific concepts: List only the terms that are unique to the block’s domain or have a special meaning within this specification.

• Short, plain-language definitions: Use a simple two-column table (Term / Description). Keep each description to a sentence or two - long explanations belong elsewhere.

• Component sub-sections when useful: If the block has distinct functional areas (e.g., “Service Access” and “Pub/Sub”), group terms under those headings for clarity.

What to avoid:

• Common terminology: Do not repeat definitions that are already in the GovStack common glossary (e.g., API, Building Block, Use Case). Link to the common terminology page instead or assume the reader is familiar with those concepts.

By following these pointers, the Terminology section stays focused on what makes this Building Block unique and helps implementers and reviewers share a common understanding of its vocabulary.

4. Key Functionalities

Purpose: Provide a descriptive list of core functional description of what the Building Block does. Every building block serves a specific business-functional need for a digital government.

Keep this section implementation-agnostic. Describe capabilities as outcomes, not components. Each capability should be testable later through Functional Requirements and Testing, if possible.

What to include:

• A short intro definition: “Key Functionalities describe the core functions this Building Block must be able to perform.”

• Core function and capability list, each is recommended to include:

  • What is this key functionality about and what value it brings.

  • One-sentence description of the outcome

  • Primary actor(s) and system boundary (who benefits from it and how)

• Out-of-scope capabilities.

What to avoid:

• “The system uses X technology” statements.

• Requirements language (MUST/SHOULD) - that belongs in sections 5 and 6.

• Duplicating functional or cross-functional requirements - this should stay high-level.

Key Functionalities should be provided by technical functions provided by Functional and Cross-Functional requirements and should be testable or verifiable.

4.1 Use-Case Scenarios

Purpose: Define the concrete contexts in which this Building Block’s services are consumed and what outcomes are expected. Scenarios make service behavior unambiguous and provide a direct bridge into requirements and testing.

Each scenario should include things such as:

• Scenario description

• Triggers for the use-case

• Preconditions and assumptions

• Actors

• Data inputs (including validation expectations)

• Normal course of the use-case (numbered steps)

• Alternative courses (at least one where meaningful)

• Data outputs

• Postconditions

• Exceptions and timeouts

• Related Building Blocks (dependencies and interactions)

• Notes

Scenarios should be written so they can be converted into test cases without re-interpretation.

5. Functional Requirements

Purpose: Define the technical behaviors an implementation must provide. Functional requirements are actual functions of the digital component and are most commonly functions that can be used over the API (either directly or with the UI/UX component using the API).

Functional requirements are requirements that are business-only, as in directly tied to Key Functionalities and core value of the digital component.

What to include:

• Each requirement should describe what this requirement is about and what value it brings to the organization.

• Requirement name or title should be a single sentence, as brief yet as accurate as possible.

  • After the title, identifier and classifiers you can explain the requirement and its details further, include references, sources, links and other reading materials if needed.

• Each functional requirement should follow GovStack specification framework and identification rules. Each requirement (functional and cross-functional) must have a unique numeric identifier that is not reused within its own specification namespace. Thus each requirement should be possible to be referred to like this: govstack-bb-workflow#req-13 or in case it is versioned, like this govstack-bb-workflow-2.3.0#req-13 (which means a number 13 requirement of Workflow specifation version 2.3.0)

  • It is important to keep in mind that the unique requirement number is never to be reused. In case a requirement becomes unimportant or invalid, it should reach a DEPRECATED Requirement Level state in the new version of the document (and can be listed in a separate document for archiving reasons).

• Each requirement must include Requirement Level (REQUIRED, RECOMMENDED, DRAFT, DEPRECATED)

• Each requirement must include Extensibility and Replaceability Classifiers (INAPPLICABLE, IMMUTABLE, EXTENSIBLE, REPLACABLE)

Assumptions and prerequisites

For each functional requirement, explicitly state:

• Preconditions: what must be true before the behavior is invoked

• Required dependencies: external systems or Building Blocks that must be available (if any)

• Data readiness: required identifiers, registrations or reference data

• Operational prerequisites: configuration, keys, trust relationships or onboarding steps etc.

If a prerequisite is not required for interoperability, it must be labeled as deployment-specific guidance and moved to Implementation Guides.

What to avoid:

• Avoid requirements that are not testable.

• Do not bundle multiple obligations into one requirement.

Remember that internal design mandates do not directly affect functional interoperability. Functional requirements should focus on actual business functions.

If implementers can comply in multiple ways, specify the external behavior not the internal method.

6. Cross-Functional Requirements

Purpose: Define the internal technical and quality behaviors an implementation must provide, including non-feature constraints that affect security, privacy, performance and operations of the building block. Cross-functional requirements are technical requirements. It is expected that all GovStack building blocks comply with the all central cross-functional requirements of GovStack (govstack-cfr). In the Building Block specification you should not duplicate or create conflicts with requirements that are already in govstack-cfr.

Cross-functional requirements of a building block are not required to be defined, there may be building blocks that have no cross-functional requirements itself.

What to include:

• Each requirement should describe what this requirement is about and why does it exist (a requirement is not good if there is no reasonable excuse for existing).

• Requirement name or title should be a single sentence, as brief yet as accurate as possible.

  • After the title, identifier and classifiers you can explain the requirement and its details further, include references, sources, links and other reading materials if needed.

• Each requirement should follow GovStack specification framework and identification rules. Each requirement (functional and cross-functional) must have a unique numeric identifier that is not reused within its own specification namespace. Thus each requirement should be possible to be referred to like this: govstack-bb-workflow#req-13 or in case it is versioned, like this govstack-bb-workflow-2.3.0#req-13 (which means a number 13 requirement of Workflow specifation version 2.3.0)

  • It is important to keep in mind that the unique requirement number is never to be reused. In case a requirement becomes unimportant or invalid, it should reach a DEPRECATED Requirement Level state in the new version of the document (and can be listed in a separate document for archiving reasons).

• Each requirement must include Requirement Level (REQUIRED, RECOMMENDED, DRAFT, DEPRECATED)

• Each requirement must include Extensibility and Replaceability Classifiers (INAPPLICABLE, IMMUTABLE, EXTENSIBLE, REPLACABLE)

What to avoid:

• Avoid requirements that are not testable.

• Do not bundle multiple obligations into one requirement.

• Avoid vague statements like “fast” or “secure” without measurable criteria.

• Avoid vendor-specific tooling mandates unless clearly optional.

If implementers can comply in multiple ways, specify the external behavior not the internal method.

7. Data Structures

Purpose: This section describes the minimum information model the Building Block uses. It defines the required resources and fields so implementations can exchange data consistently and evolve schemas without breaking consumers.

This section is optional, but can be helpful for providing understanding with more complicated data structures of a building block.

Goal of this section is also to define the minimum information model needed for the building block and provide a stable reference for schemas and data compatibility.

What to include:

• Resource model overview: entities and relationships at a conceptual level.

• Minimum required fields for each resource: name, type.

• Validation rules: required fields, formats, enums and constraints.

• Extension rules: how to add fields safely and how consumers must handle unknown fields.

• References to canonical schema artifacts if you maintain them elsewhere.

What to avoid:

• Optional fields that are treated as mandatory without stating it.

• Ambiguous identifiers or unspecified uniqueness constraints.

8. Testing

Purpose: This section defines how conformance is verified. It links requirements to testable criteria and provides the basis for validating candidate implementations consistently.

Goal of this is to make compliance verifiable and repeatable and ensure that at least every REQUIRED rule has a verification path.

What to include:

• Conformance definition: what it means to be compliant.

• Every REQUIRED requirement mapped to at least one verification item.

• Test types: contract tests, negative tests, security checks, performance checks and observability checks as well as required test artifacts: fixtures, sample data and environment assumptions.

What to avoid:

• Test descriptions without expected outcomes.

• Dependence on a single vendor toolchain.

• Non-deterministic tests that cannot be repeated reliably.

9. Internal Workflows

This section describes the main end-to-end flows the Building Block must support, especially where it interacts with other Building Blocks or external systems. The goal is to make the expected sequence of steps clear and to remove ambiguity about who does what, when and with what inputs and outputs.

Document a small set of workflows that cover the common path and at least one failure and recovery path. For each workflow list actors, preconditions, numbered steps, key decisions (authz, validation, routing) and postconditions. Include what must be logged and what errors must be returned. Diagrams are fine but the text must stand on its own.

10. Other Resources

This section contains supporting material that is useful but not part of the requirements. It is where you put context and references that help readers understand decisions and future direction without cluttering functional and cross-functional requirements.

Include links to future considerations and out-of-scope assumptions. Add pointers to example schemas, reference configurations, known limitations and issue trackers if they help implementers. Do not introduce new rules here. If something affects compliance or interoperability it belongs in the requirements or testing sections.

10.1 Implementation Guides

This section explains how to implement and run the Building Block in real deployments. It is where you can provide practical guidance that goes beyond the specification - architecture patterns, configuration, operations and integration examples that help teams deliver a working system.

Implementation guidance can be universal or region-specific and it can reflect policy constraints, procurement realities, and local standards. It can also include technology- and vendor-specific approaches as long as they are clearly labeled as examples or options. Do not hide compliance rules here - anything required for interoperability or conformance must stay in the main specification and tests.

10.2 Key decisions log

Purpose: Record decisions that materially affect interoperability, security posture or future evolution.

For each decision include:

• Date (YYYY-MM-DD)

• Decision statement (one sentence)

• Rationale (short)

• Alternatives considered (optional)

• Implications (compatibility, migration, deprecation, risks)

• Affected sections (e.g., requirements, data structures, APIs, testing)

This section must not introduce new normative rules. If a decision changes compliance, reflect it in requirements and tests.