Skip to main content
Last updated: 15 Apr 2025

govuk-chat: 7. Serialisation and Schema Validation for GOV.UK Chat API

Date: 2025-04-15

Context

We are building an API for GOV.UK Chat, and as part of that we need to choose tools for two concerns:

  1. Serialising Ruby objects into JSON responses
  2. Validating API requests and responses against our OpenAPI specification

These tools should be simple, reliable, and maintainable, with minimal dependencies and good community support.

Decision

Serialisation

We have chosen to use Blueprinter for serializing objects into JSON. It provides a clean and lightweight way to define how data is exposed through the API.

We decided against

Blueprinter is preferred because:

  • It’s simple to configure and easy to read
  • It keeps response logic isolated and maintainable
  • It is actively maintained and stable

OpenAPI Request and Response Validation

We are using Committee middleware to validate that API request and response payloads match the OpenAPI 3 specification at runtime. This gives us immediate feedback if responses drift from the specification.

In addition to runtime validation, we’re also using Committee in our request specs to ensure we're checking responses conform to the schema during automated testing.

We considered rswag, but opted not to use it due to:

  • Its focus on documentation and Swagger UI, which isn’t a priority right now
  • Its more complex setup and less intuitive behaviour for schema validation
  • Committee providing simpler, targeted validation of actual responses

Status

accepted

Consequences

  • Developers will use Blueprinter to define API response formats
  • Request and response validation against the OpenAPI spec will happen at runtime via middleware, and in automated tests