Bufdir Format Serializer
Component Detail
Description
Transforms aggregated internal activity data into the canonical Bufdir JSON payload structure. This intermediate representation is consumed by both the PDF/CSV generators and the future Bufdir API client, making it the single source of truth for the Bufdir data model.
bufdir-format-serializer
Summaries
The Bufdir Format Serializer is the organisation's single point of compliance for how internal data maps to Norway's official Bufdir reporting format. By centralising this transformation, the business eliminates the risk of different parts of the system producing inconsistent or incorrect Bufdir submissions. This is critical because errors in government reporting can result in funding clawbacks or reputational damage. The serializer also future-proofs the organisation by versioning the payload schema, meaning that when Bufdir updates its requirements, only this one component needs to change — not every report generator across the platform.
This medium-complexity component sits at the intersection of the data pipeline and output generation, making it a coordination bottleneck. It depends on the Bufdir Category Mapper being completed first, and it is itself a dependency for both the PDF/CSV generators and the future Bufdir API client. Any changes to the Bufdir schema requirements must flow through this component, so version it carefully and establish a change-control process with the product owner. Plan for at least one round of stakeholder review of the payload structure against official Bufdir documentation before sign-off.
Testing must include payload validation against the official schema spec, including edge cases for missing or null activity counts.
Implements a pure transformation layer — no I/O, no side effects. serialize() accepts the aggregated data structure from the aggregation service and a category mappings object from bufdir-category-mapper, returning a typed Bufdir payload object. validatePayload() runs JSON Schema validation (use Ajv or similar) against getPayloadSchema(version) to catch structural errors before they reach file generators or API clients. toJSON() and fromJSON() provide serialisation round-trip support for caching and debugging.
Version the schema as a constant (e.g. BUFDIR_SCHEMA_V1) and route version selection via a factory if multiple versions are needed concurrently. This component should have 100% unit test coverage given its compliance-critical nature — every field mapping must be explicitly tested.
Responsibilities
- Map aggregated data to Bufdir payload schema
- Apply Bufdir category codes from mapper
- Validate payload completeness before output
- Version the payload schema for future API compatibility
Interfaces
serialize(aggregatedData, mappings)
validatePayload(payload)
getPayloadSchema(version)
toJSON(payload)
fromJSON(json)
Relationships
Related Data Entities (1)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on