---
layout: raw-data.njk
---

# Making API Compliance a Byproduct, Not a Burden

*How machine-readable compliance assets are changing the way NZ public service teams build APIs*

---

## The Problem with Compliance Checklists

Every public service developer building an API knows the feeling: you've shipped a working system, and now someone asks for "compliance documentation." You dig through the NZ API Standard—four documents, hundreds of requirements—trying to figure out which ones apply, whether you've met them, and how to prove it.

This backwards approach treats compliance as an afterthought. It creates documentation that exists to satisfy auditors rather than to help developers. And it produces evidence that's disconnected from the actual implementation.

We built something different.

## Compliance Through Usage

The core insight behind our compliance assets is simple: **the best compliance evidence is generated automatically by doing the right thing.**

Instead of asking teams to document their compliance after the fact, we provide tools that embed requirements into the development workflow. Use the tools correctly, and compliance evidence appears as a natural byproduct.

Here's what that looks like in practice.

## The Assets

We've created 10 integrated assets that cover the API lifecycle:

### 1. Requirements Registry
A machine-readable database of all 135 requirements from the NZ API Standard. Each requirement includes its normative level (MUST, SHOULD, MAY), lifecycle phase, and a permanent URL linking to the authoritative source text.

This isn't just a list—it's the foundation everything else builds on.

### 2. OpenAPI Validator Rules
26 validation rules that check your OpenAPI specification against requirements. Run it in CI/CD, and every pull request gets automatic compliance checking:

```
FAIL: SEC-001 - API specification must define security schemes
      Requirement: STD-M-0020 (MUST)
      Source: https://docref.digital.govt.nz/.../c5-a29
```

The violation links directly to the source requirement. No ambiguity about what's wrong or why it matters.

### 3. Security Decision Matrix
Building an API means making security decisions: OAuth vs API Keys, TLS 1.2 vs 1.3, scopes vs roles. The matrix guides these choices by mapping options to requirements.

Each option shows when to use it, when not to use it, and which requirements it satisfies. When you select OAuth 2.0 with PKCE for your external API, you're not just making a technical choice—you're documenting compliance with authentication requirements.

### 4. Test Specifications
Pre-built test cases mapped to requirements. The "Authentication Required" test verifies your API rejects unauthenticated requests. The "Error Response Format" test checks RFC 7807 compliance.

Run the tests, and the results become your compliance evidence. No separate "compliance testing" phase needed.

### 5. Checklist Generator
Generate context-specific checklists based on your API's characteristics. An internal system API has different requirements than a public experience API.

```bash
python checklist-generator.py "Customer API" \
  --category experience \
  --exposure external \
  --phase development
```

Output: A filtered checklist with only relevant requirements, each linked to source.

### 6. Lifecycle Tracker
Track your API through gates: Design, Development, Security, Deployment, Operations. Each gate records which requirements were checked, by whom, and what evidence was collected.

The audit trail writes itself.

### 7. Documentation Templates
Markdown templates with compliance markers embedded. Fill in the blanks, and you've created documentation that satisfies requirements—complete with traceability comments:

```markdown
<!-- COMPLIANCE: SEC-001 - Authentication methods MUST be documented -->
<!-- Requirement: STD-M-0020 -->
<!-- DocRef: https://docref.digital.govt.nz/.../c5-a29 -->

## Authentication

This API uses OAuth 2.0 with PKCE for authentication...
```

### 8. Design Decision Log
A structured format for recording decisions and their rationale. Critical for SHOULD requirements, where deviation is allowed with justification.

"We chose not to implement HATEOAS because our mobile consumers reported 40% payload overhead without benefit for their use case."

That's not non-compliance—it's documented, justified deviation.

### 9. Gateway Policies
Enforceable policies for API gateways, with requirement traceability. Rate limiting isn't just a technical control; it's compliance with threat protection requirements.

### 10. Compliance Dashboard Schema
Aggregate compliance status across your API portfolio. See which APIs are compliant, which have approved deviations, and which need attention.

## How It Works Together

The magic is in the integration. Every asset uses the same requirement IDs. When the validator flags a missing security scheme, that's the same requirement the checklist tracks, the same requirement the test verifies, and the same requirement the dashboard reports on.

Change the requirement in the registry, and the change flows everywhere.

## Traceability: The Non-Negotiable Feature

Every requirement, rule, and recommendation links to its source via DocRef URLs:

```
https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c5-a29
```

That URL points to Article 29 of Chapter 5: "Authentication Requirements" in the NZ API Standard.

This isn't about trusting our interpretation. It's about enabling verification. An auditor can follow any claim back to the authoritative text. A developer can understand *why* a rule exists, not just *what* it requires.

## Getting Started

You don't need to adopt everything at once. Here's a practical path:

**Week 1:** Run the OpenAPI Validator against your existing API specs. See what fails. Fix the easy ones.

**Week 2:** Generate checklists for your in-flight projects. Assign owners to unchecked requirements.

**Month 1:** Establish a design decision log practice. Start capturing rationale for architecture choices.

**Quarter 1:** Deploy the dashboard. Get portfolio-wide visibility into compliance status.

## The Bigger Picture

These assets represent a shift in how we think about compliance. Not as a separate activity with its own artifacts, but as a property that emerges from good development practice.

When your CI/CD pipeline validates your OpenAPI spec, that's compliance checking. When your test suite runs security tests, that's compliance verification. When your documentation follows the template, that's compliance evidence.

The work doesn't change. The evidence just appears.

---

*The NZ API Standard Compliance Assets are available for public service agencies building APIs. All assets are JSON and Markdown based, version controllable, and extensible for agency-specific requirements.*