Aquae - gov.uk Personal Data Exchange Specification
  ===================================================

  Copyright (C) 2017, The Personal Data Exchange Team, Crown Copyright (Government Digital Service).

 1. Introduction

        gov.uk Personal Data Exchange is a way to query existing personal data
        held by government. This distribution is the technical specification
        for how the system operates and a set of tools for working with the
        messages and protocols defined.

        There are a number of files supplied:

        + transport.md

            This file documents the low-level transport protocols used
            by participants in the system.

        + metadata.md

            This file documents the format and structure of the configuration
            file produced.

        + messaging.md

            This file documents the format and sequences of messages sent
            by pariticpants in the system.

        + md2protobuf

            This is a script to extract Protocol Buffers definitions from
            Markdown files. We use it to produce the .proto files
            automatically from our specification documentation so that the two
            can be maintained together.

        + build.ps1

            This provides md2protobuf style functionality for PowerShell on
            Windows.

        + Makefile

            Here we script the tools to produce the outputs.

        + build.ps1

            This provides the build functionality of the Makefile
            for PowerShell on Windows.

        The whole package is distributed under an MIT license and as such is
        free to use and modify as long as you agree to its terms.

        Note: Should you have any trouble in setting up and using these tools,
        please feel free to contact:

            + Andy Bennett <[email protected]>
            + Simon Worthington <[email protected]>


 2. Installation

        The tools in this package can be run straight away; they do not need to
        be built or installed. However, they do have a number of dependencies
        which need to be satisfied.

        For UNIX systems, the tools require GNU Make and Perl. These tools are
        usually available by default or from system packages.

        For Windows systems, the tools require PowerShell, which is availble by
        default in Windows 10 or from http://msdn.microsoft.com/en-us/powershell.


 3. Usage

        In order to render the specification and build the protocol and
        message definition, on UNIX invoke `make` thus:

            make all

        Or from PowerShell on Windows:

            .\build.ps1

        This will produce two files:

        + metadata.proto

            This contains the Protocol Buffer definitions for the metadata
            file that is used to set policy in a federation of Aquae nodes.

        + messaging.proto

            This contains the Protocol Buffer definitions for the inter-node
            messaging protocol.


 4. Compatibility notes

        This specification is not yet stable and, as such, we make no
        gurantees of backwards or fowards compatibility. We do not recommend
        that this system is deployed in anger.


 5. What's next?

        First and foremost, enjoy the tools and use and extend them to build
        your own Personal Data Exchange Federations.

        Please feel free to send tools that you build with this so that they
        can be integrated and distributed with this package.

        Suggestion, extensions and patches are welcome.

        If you have any questions or problems (even the slightest problems, or
        the most stupid questions), then please feel free to get in touch with
        us directly using the addresses above. We will try to help you, get you
        going or point you in the right direction.