Gatepost spec

The shared contract for every Gatepost SDK: the postcode grammar, the data files, the test vectors and the coding standards.

Docs · Playground · Grammar · Contributing · Discussions

Unofficial. Not made or endorsed by NIPOST.

This repo defines how every Gatepost SDK reads and writes Nigeria's digital postcodes, and how every Gatepost client calls NIPOST's gateway. An SDK is correct when it passes the shared vectors and the contract scenarios. If grammar.md and a vector disagree, grammar.md wins, and the disagreement is a bug.

The current version is in VERSION.

A postcode in three forms

Form	Example	Use
Compact	EK01A03FK01	storage and comparison
Canonical	EK-01-A03-FK-01	APIs and logs
Display	EK 01 A03 FK 01	screens and print

A postcode has five segments, from large to small: state, LGA, district, area and unit. grammar.md has the rules.

One test vector

This case is contains-001 in vectors/contains.json.

{
  "id": "contains-001",
  "description": "finds a full code in its district",
  "input": {
    "prefix": "EK-01-A03",
    "code": "EK-01-A03-FK-01"
  },
  "options": {},
  "expect": {
    "value": true
  }
}

Every SDK runs the cases in vectors/.

Contents

Path	Holds
grammar.md	how every SDK reads and writes postcodes, and the public interface
client.md	how every client calls NIPOST's gateway: results, errors, retries and the queue
field.md	how every postcode field behaves: settings, events, states, accessibility and privacy
messages/	the text of the field, one message catalogue for each language
openapi/	NIPOST's gateway, completed with the responses that its own file leaves out
fixtures/	synthetic gateway responses and keys for the mock server
contract/	shared client test cases that every client must pass against the mock server
data/	state codes, GPS accuracy limits and the postcode format
vectors/	shared test cases that every SDK must pass
standards/	the coding standards and one file for each language
CONTEXT.md	the glossary
templates/	files for new repos
scripts/	check-tells, the vector builder, a plain reading of the grammar that checks each vector, and the checks of the OpenAPI file, the fixtures and the scenarios

Who uses it

Repo	Language	Implements
js	TypeScript	the grammar and the client
php	PHP	the grammar and the client

The docs site shows the same grammar and client contract as pages for readers.

Change the spec

A change to the public interface of an SDK starts here. Open an issue first. Then read CONTRIBUTING.md. Run make check before you open a pull request. It needs Python 3.11 or later and uv.

Support

Ask questions in GitHub Discussions. Report bugs in GitHub Issues. Report security problems through the private form.

Licence

Apache-2.0. See LICENSE and NOTICE.