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

# NZ API Standard Compliance Assets System

## Part 1: What You Need to Know (Executive Summary)

### The Problem We're Solving

New Zealand government agencies must build APIs that comply with official standards. These standards are spread across four documents totaling hundreds of pages, containing 135 specific requirements. Manually checking compliance is:
- **Time-consuming**: Reading through all requirements for each API
- **Error-prone**: Easy to miss requirements or misinterpret them
- **Inconsistent**: Different people interpret requirements differently
- **Hard to track**: Difficult to prove compliance to auditors

### What This System Does

This project provides **digital tools and datasets** that automate compliance checking and tracking. Think of it as a "compliance toolkit" that:

1. **Automatically validates API specifications** against government standards
2. **Generates checklists** tailored to your specific API type
3. **Tracks compliance** across your organization's APIs
4. **Provides test specifications** your team can run
5. **Documents decisions** when you need to deviate from standards

### Key Benefits

| Benefit | Impact |
|---------|--------|
| **Speed** | Validate an API spec in seconds, not hours |
| **Consistency** | Same rules applied every time |
| **Traceability** | Every check links back to the official requirement |
| **Auditability** | Generate compliance reports for governance |
| **Automation** | Integrate into CI/CD pipelines |

### Coverage Summary

The OpenAPI validator covers **87% of requirements that can be checked from a specification**. The remaining 13% require runtime testing or process audits (e.g., "Does your team follow a design-driven approach?").

Some requirements simply cannot be validated from a specification file:
- TLS/encryption configuration (infrastructure level)
- Token security in production (runtime)
- Team collaboration practices (process)

For these, we provide **test specifications** that describe how to verify compliance manually or through runtime testing.

### Who Should Use This

| Role | Primary Tools |
|------|---------------|
| **API Developers** | OpenAPI Validator, Checklist Generator |
| **Security Teams** | Security Decision Matrix, Test Specifications |
| **Architects** | Gateway Policies, Decision Log |
| **Compliance Officers** | Compliance Dashboard, Lifecycle Tracker |
| **Management** | Compliance Dashboard (aggregated view) |

---

## Part 2: Technical Deep Dive

### How the System Was Created

#### Source: The Four Authoritative Documents

All compliance assets trace back to official NZ Government documents:

1. **Draft API Standard** - The consolidated requirements
2. **Part A: API Concepts and Management** - Foundational concepts
3. **Part B: Technical Specifications** - Security and technical requirements
4. **Part C: Implementation Guidance** - Practical implementation patterns

These documents were processed using **DocRef**, a system that:
- Converts documents into structured JSON
- Assigns unique identifiers (GHIs) to every paragraph, table cell, and list item
- Provides permanent URLs for precise citations

#### Extraction Process

From these documents, we extracted:
- **135 normative requirements** (MUST, SHOULD, MAY statements)
- **52 MUST/MUST NOT requirements** (mandatory compliance)
- **81 SHOULD recommendations** (best practices)

Each requirement is tagged with:
- Normative level (MUST, SHOULD, MAY)
- Lifecycle phase (design, development, security, deployment, operations)
- API category (experience, process, system)
- Exposure level (public, partner, internal)
- DocRef URL for traceability

### Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                    Source Documents (DocRef)                     │
│  Part A (Concepts) │ Part B (Security) │ Part C (Implementation) │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Requirements Registry (135 requirements)            │
│         JSON + CSV formats with DocRef citations                 │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  OpenAPI         │ │  Checklist       │ │  Test            │
│  Validator       │ │  Generator       │ │  Specifications  │
│  (42 rules)      │ │  (filters)       │ │  (36 tests)      │
└──────────────────┘ └──────────────────┘ └──────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Supporting Assets                             │
│  Gateway Policies │ Security Matrix │ Decision Log │ Dashboard   │
└─────────────────────────────────────────────────────────────────┘
```

### The 10 Compliance Assets

#### 1. Requirements Registry (`assets/requirements-registry/`)

**What it is**: The master dataset of all 135 requirements extracted from source documents.

**Files**:
- `requirements-registry.json` - Machine-readable format
- `requirements-registry.csv` - Spreadsheet-friendly format

**Key fields**:
```json
{
  "requirement_id": "STD-M-0020",
  "requirement_text": "APIs MUST define authentication...",
  "normative_level": "MUST",
  "lifecycle_phase": "security",
  "docref_url": "https://docref.digital.govt.nz/..."
}
```

**Use case**: Foundation for all other tools; can be queried directly for custom analysis.

---

#### 2. OpenAPI Validator (`assets/openapi-validator/`)

**What it is**: A Python tool that validates OpenAPI 3.x specifications against 42 rules derived from the standard.

**How it works**:
1. Parses your OpenAPI spec (YAML or JSON)
2. Runs 42 validation checks
3. Calculates compliance score (MUST requirements only)
4. Outputs detailed report with remediation guidance

**Usage**:
```bash
# Basic validation
python validator.py your-api-spec.yaml

# JSON output for CI/CD
python validator.py your-api-spec.yaml --format json

# Save report
python validator.py your-api-spec.yaml -o report.json
```

**Sample output**:
```
============================================================
NZ API STANDARD - VALIDATION REPORT
============================================================
API: Customer API
Version: 1.0.0
Compliance Score: 95.5%
Status: NON-COMPLIANT

Results: 20 passed, 1 failed, 3 warnings, 2 skipped

FAILURES (MUST FIX)
[DOC-005] external_docs_defined
  API should define externalDocs with a URL to documentation
  Remediation: Add externalDocs section with url pointing to API catalogue
  DocRef: https://docref.digital.govt.nz/...
```

**Coverage**:
- 87% of validatable MUST requirements (27 of 31)
- 21 requirements are out of scope (documented in `coverage_limitations`)

**Exit codes** (for CI/CD):
- `0` = Compliant (100% MUST requirements pass)
- `1` = Non-compliant

---

#### 3. Checklist Generator (`assets/checklist-generator/`)

**What it is**: Generates filtered compliance checklists based on your API's characteristics.

**Why it matters**: Not all 135 requirements apply to every API. A public-facing API has different requirements than an internal system API.

**Usage**:
```bash
# Generate checklist for security phase, MUST requirements only
python checklist-generator.py "My API" \
  --phase security \
  --levels MUST "MUST NOT" \
  --format markdown

# Generate full CSV for tracking
python checklist-generator.py "My API" --format csv -o checklist.csv
```

**Filters available**:
- `--phase`: design, development, security, deployment, operations
- `--levels`: MUST, "MUST NOT", SHOULD, "SHOULD NOT", MAY
- `--category`: experience, process, system
- `--exposure`: public, partner, internal

---

#### 4. Test Specifications (`assets/test-specifications/`)

**What it is**: 36 pre-built test specifications for requirements that can't be validated from specs alone.

**Categories**:
| Category | Tests | Focus |
|----------|-------|-------|
| Security | 5 | Authentication, authorization |
| Error Handling | 4 | Error format, validation |
| HTTP Methods | 5 | Idempotency, correct usage |
| Pagination | 3 | Collection handling |
| Versioning | 2 | Version compatibility |
| Contract | 3 | Spec-to-implementation match |
| TLS Security | 3 | Certificate, cipher validation |
| Input Validation | 4 | Injection prevention |
| Token Security | 3 | OAuth token handling |
| Documentation | 2 | API catalogue requirements |
| Error Security | 2 | No sensitive data leakage |

**Each test includes**:
- Requirement IDs it validates
- Step-by-step test procedure
- Sample requests/responses
- Expected outcomes

---

#### 5. Gateway Policies (`assets/gateway-policies/`)

**What it is**: Pre-configured gateway policies for common API management platforms.

**Platforms supported**:
- AWS API Gateway
- Kong
- Azure API Management
- Generic (platform-agnostic)

**Policy categories**: Security, Rate Limiting, Validation, Headers, Logging

---

#### 6. Security Decision Matrix (`assets/security-matrix/`)

**What it is**: A decision guide for choosing security implementations based on API characteristics.

**Covers**:
- Authentication methods (API keys, OAuth, JWT)
- Transport security (TLS configuration)
- Token management
- Authorization patterns
- Threat protection

---

#### 7. Lifecycle Tracker (`assets/lifecycle-tracker/`)

**What it is**: JSON Schema for tracking an API's compliance through its lifecycle.

**Tracks**:
- Current lifecycle phase
- Gate approvals (who approved, when)
- Compliance scores per phase
- Evidence artifacts (test results, audit reports)

---

#### 8. Compliance Dashboard (`assets/compliance-dashboard/`)

**What it is**: JSON Schema for organization-wide compliance reporting.

**Features**:
- Aggregate scores across all APIs
- Trend analysis over time
- Common gaps identification
- Alert thresholds

---

#### 9. Decision Log (`assets/decision-log/`)

**What it is**: JSON Schema for documenting compliance decisions and deviations.

**Use case**: When you can't meet a requirement, document why, what alternatives you chose, and who approved the deviation.

---

#### 10. Documentation Templates (`assets/documentation-templates/`)

**What it is**: Markdown templates ensuring all required documentation elements are included.

**Includes compliance markers** like `<!-- COMPLIANCE: DOC-001 -->` for traceability.

---

### Understanding Coverage Limitations

The validator achieves 87% coverage of **validatable** MUST requirements. Here's what that means:

**Total MUST requirements**: 52

**Validatable via OpenAPI** (31 requirements):
- Security scheme definitions
- Error response formats
- HTTP method usage
- Documentation completeness
- Versioning patterns

**Out of Scope** (21 requirements):

| Category | Why Can't Validate | Examples |
|----------|-------------------|----------|
| Process/Governance | Organizational practices | "Design-driven approach MUST be taken" |
| TLS/Infrastructure | Server configuration | "MUST use TLS 1.3", "MUST validate certificates" |
| Token/Key Security | Runtime behavior | "API keys MUST be 40+ characters" |
| Threat Protection | Implementation details | "MUST prevent SQL injection" |
| Terminology | Definitional only | "MUST/MUST NOT indicates absolute requirement" |

**For out-of-scope requirements**: Use the Test Specifications to verify compliance through runtime testing.

---

### Getting Started

#### Prerequisites

```bash
# Python 3.8+
python3 --version

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

#### Quick Start: Validate Your First API

```bash
# 1. Activate environment
source .venv/bin/activate

# 2. Run validator on your OpenAPI spec
python assets/openapi-validator/validator.py your-api.yaml

# 3. Generate a checklist
python assets/checklist-generator/checklist-generator.py "My API" --format markdown
```

#### Running Tests

```bash
# Run all tests (50 tests)
pytest tests/ -v

# Run validator tests only
pytest tests/test_validator.py -v
```

---

### Integration Patterns

#### CI/CD Pipeline Integration

```yaml
# GitHub Actions example
- name: Validate OpenAPI Spec
  run: |
    python assets/openapi-validator/validator.py api/openapi.yaml --format json -o compliance-report.json

- name: Upload Compliance Report
  uses: actions/upload-artifact@v3
  with:
    name: compliance-report
    path: compliance-report.json
```

#### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit
python assets/openapi-validator/validator.py api/openapi.yaml
if [ $? -ne 0 ]; then
  echo "API spec is non-compliant. Fix issues before committing."
  exit 1
fi
```

---

### Where to Start

**If you're a developer**:
1. Run the validator on your existing API spec
2. Review the failures and warnings
3. Use the remediation guidance to fix issues
4. Generate a checklist for requirements not covered by the validator

**If you're a security engineer**:
1. Review the Security Decision Matrix for your API type
2. Use Test Specifications to plan security testing
3. Configure Gateway Policies for your platform

**If you're a compliance officer**:
1. Set up the Compliance Dashboard schema
2. Use the Lifecycle Tracker to monitor APIs through phases
3. Establish a Decision Log process for deviations

**If you're an architect**:
1. Review the Requirements Registry for design requirements
2. Use Gateway Policies as reference architectures
3. Establish lifecycle gates using the Tracker schema

---

### Traceability

Every rule, test, and policy links back to source requirements via DocRef URLs:

```
Rule SEC-001 (security_scheme_required)
  ↓
Requirement STD-M-0020
  ↓
DocRef URL: https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c5-a29
  ↓
Original text in Part B: "APIs MUST define at least one security scheme..."
```

This traceability chain supports:
- Audit evidence
- Requirement change tracking
- Impact analysis when standards update

---

### Contributing and Extending

The system is designed to be extended:

- **Add new validation rules**: Edit `validation-rules.json` and add check function to `validator.py`
- **Add test specifications**: Extend `test-specifications.json`
- **Add gateway policies**: Add platform configurations to `gateway-policies.json`

All additions should include:
- Requirement ID references
- DocRef URLs for traceability
- Unit tests (for Python tools)

---

### Summary

This compliance assets system transforms the NZ API Standard from a static document into an **active, automated compliance toolkit**. It:

1. **Extracts** 135 requirements from 4 source documents
2. **Validates** 87% of checkable MUST requirements automatically
3. **Documents** what can't be automated with test specifications
4. **Tracks** compliance through the API lifecycle
5. **Reports** across your organization's API portfolio

The result: faster compliance checking, consistent enforcement, and full audit traceability back to authoritative sources.