GOV.UK content schemas

This repo contains schemas and examples of the content that uses them on GOV.UK.

The aim of it is to support 'contract testing' between the frontend and publisher apps by expressing the schema and examples in strict, machine processable form.

We use JSON Schema to define the schemas.

For each schema, there are three possible representations:

• the 'publisher' representation, which is used when a publishing application transmits data to the content store.
• the 'frontend' representation, which is produced by the content store when a frontend application requests data
• the 'notification' representation, which is used when broadcasting messages about content items on the message queue

Howtos

• How to change a schema
• How to add a new content schema
• Working with JSON Schema keywords
• Adding contract tests to your app
• Suggested workflows
• Why do contract testing?
• Running your frontend against the examples and random content (content-store not needed)
• Deployment

Background

Publisher schema defined using component parts

Schemas are built from a single file defined in the formats directory. An example file defining the schema is available in formats/_example.jsonnet.

These files are stored in the govuk-content-schemas repository in the formats subdirectory. A build process (implemented using a Rakefile) combines the three component files into the final schema.json file.

The generated files are all stored in the dist subdirectory.

The build process applies the rules for the various different schema representations.

There are a number of shared definitions that are used across multiple schemas these are defined in the formats/shared directory.

Examples of schemas are available in the examples directory.

DO NOT EDIT FILES in the dist directory directly, instead, edit the source files in the formats directory.

In summary the folder structure is:

dist
└── formats
    └── case_study
        ├── frontend
        │   └── schema.json
        └── publisher
            └── schema.json
examples
└── case_study
    └── frontend
        ├── archived.json
        ├── case_study.json
        └── translated.json
formats
└── case_study.jsonnet

Validation of examples

To validate examples against the generated schemas, use the validate_examples Rake task:

$ bundle exec rake validate_examples

This will print the errors out to the console if validation fails.

Rakefile

A Rakefile exists which combines these scripts. It automatically re-generates the intermediate schema files and validates all the examples.

To invoke the default task just invoke rake on its own.