Raw Data
This file contains raw search retrieval results or agent logs. The content below shows the original markdown source.
---
layout: raw-data.njk
---
# New Zealand Government API Catalogue: Data Structure Specification
**Version**: 1.0
**Status**: Draft
**Date**: December 2025
---
## Overview
This document defines the authoritative data structure for the New Zealand Cross-Government Public Service API Catalogue. It consolidates the disclosure requirements, phased implementation plan, and DocRef markdown mapping into a single reference.
The catalogue is implemented as a structured markdown document that is:
1. Human-readable when rendered
2. Machine-queryable when exported as a dataset
3. Individually addressable via DocRef URLs
4. Version-controlled with changelogs
---
## Data Structure Definition
### Hierarchy
The catalogue uses a three-level heading hierarchy plus code blocks for structured data.
| Level | Markdown | Prefix | Content |
|-------|----------|--------|---------|
| Level 1 | H2 (`##`) | `agency` | Government agency or provider organisation |
| Level 2 | H3 (`###`) | `api` | Individual API entry |
| Level 3 | H4 (`####`) | `attribute` | Logical grouping of related fields |
| Level 4/5 | Code block | `pf` | Structured JSON data containing fields and constraints |
### Identifier Generation
Identifiers are concatenated to encode full ancestry:
| Element | Identifier Pattern | Example |
|---------|-------------------|---------|
| Agency | `agency{N}` | `agency1` |
| API | `agency{N}-api{N}` | `agency1-api1` |
| Attribute | `agency{N}-api{N}-attribute{N}` | `agency1-api1-attribute1` |
| Code block | `agency{N}-api{N}-attribute{N}-pf{N}` | `agency1-api1-attribute1-pf1` |
Numbering is sequential within each parent context. The prefixes `agency`, `api`, `attribute`, and `pf` are set document-wide.
### Horizontal Rule Requirements
Horizontal rules (`---`) must separate:
1. Consecutive headings (any heading followed by another heading)
2. H4 (attribute) headings and their code block content
This ensures the downstream DocRef conversion system correctly assigns identifiers.
---
## Attribute Types
Each API entry contains the following attributes (H4 headings), with structured JSON in code blocks:
### Phase 1 (MVP) Attributes
| Attribute | Purpose |
|-----------|---------|
| `identity` | Name, description, and contact information |
| `classification` | Exposure level and API type |
| `access` | Documentation and specification URLs |
### Phase 2+ Attributes (Future)
| Attribute | Phase | Purpose |
|-----------|-------|---------|
| `versioning` | 2 | Current version and lifecycle status |
| `authentication` | 2 | Auth method and registration requirements |
| `service` | 2 | Rate limits and SLA information |
| `planning` | 3 | Roadmap and changelog URLs |
| `support` | 5 | Developer portal, examples, community resources |
---
## JSON Schema Definitions
### Agency Identity
```json
{
"name": "string (required) - Full agency name",
"acronym": "string (required) - Short form identifier",
"contact_email": "string|null - Agency API programme contact"
}
```
**Citations:**
- `name`: "The organisation that provides the API" ([Part A Glossary](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-para1))
- `acronym`: Supports discovery where developers may not know "which agency that resource would reside within" ([Part A 3.5](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section5-para3))
- `contact_email`: "Critical when it comes time to implement aspects of the API service life cycle" ([Part B 3.1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para3))
### API Identity
```json
{
"name": "string (required) - API name",
"description": "string|null - Resource description",
"contact_email": "string|null - API-specific contact"
}
```
**Citations:**
- `name`: Catalogue purpose to list "the APIs offered" ([Part A Glossary](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-para1-l3))
- `description`: "The information or functionality exposed by the API" ([Part A 3.5](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section5-para2))
- `contact_email`: "Critical when it comes time to implement aspects of the API service life cycle" ([Part B 3.1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para3))
### Classification
```json
{
"exposure": {
"value": "string|null - Current exposure level",
"allowed_values": ["internal", "external", "partner", "public"]
},
"api_type": {
"value": "string|null - API technology type",
"allowed_values": ["REST", "GraphQL", "AsyncAPI", "gRPC"]
},
"category": {
"value": "string|null - API category (Phase 2+)",
"allowed_values": ["system", "process", "experience"]
}
}
```
**Citations:**
- `exposure`: APIs are "commonly categorised" by exposure level ([Part A 1.2 Table 1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section2-para2-tb1))
- `api_type`: "The type you choose may depend on the technical use cases" ([Part C 1.2](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6))
- `category`: Three categories with "different frequency of change, effort, impact, and ownership" ([Part A 3.2](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section2-para2-tb1))
### Access
```json
{
"docs_url": "string|null - Documentation URL",
"spec_url": "string|null - Machine-readable specification URL",
"spec_format": {
"value": "string|null - Specification format (Phase 4+)",
"allowed_values": ["openapi", "asyncapi", "graphql", "protobuf"]
},
"sandbox_url": "string|null - Interactive testing environment (Phase 4+)"
}
```
**Citations:**
- `docs_url`: "External API MUST be well documented" ([Part C 1.2](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para61))
- `spec_url`: "Interface specifications SHOULD also be provided in a machine-readable format" ([Part A 3.1.2](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para9))
- `spec_format`: Specification formats ([NZ API Standard Draft](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c6-a42))
- `sandbox_url`: "Giving developers a 'sandpit' capability to try the APIs interactively" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-5))
### Versioning (Phase 2+)
```json
{
"version": "string|null - Current version number",
"status": {
"value": "string|null - Lifecycle status",
"allowed_values": ["planning", "development", "beta", "production", "deprecated", "retired"]
},
"supported_versions": ["string"] ,
"deprecation_date": "string|null - ISO date of planned deprecation"
}
```
**Citations:**
- `version`: "APIs should have a clear indication of the version" ([Part C 1.5](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para4))
- `status`: "Life cycle management means managing the full life cycle of APIs" ([Part A 5.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para6-5))
- `supported_versions`: "Old API version SHOULD be maintained alongside the new version" ([Part A 2.6](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para3))
- `deprecation_date`: "Notify all consumers — Provide advance notice" and "Set retirement date" ([NZ API Standard Draft](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c7-a56-p3))
### Authentication (Phase 2+)
```json
{
"method": {
"value": "string|null - Authentication method",
"allowed_values": ["none", "api_key", "oauth2", "openid_connect", "certificate"]
},
"registration_required": "boolean|null - Whether registration is needed",
"registration_url": "string|null - Registration process URL (Phase 4+)",
"tls_version": {
"value": "string|null - TLS version (Phase 4+)",
"minimum": "1.3"
},
"terms_url": "string|null - Terms and conditions URL (Phase 5+)"
}
```
**Citations:**
- `method`: "Authentication is required to identify the consumers" ([Part B 3.1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para1))
- `registration_required`: "Allowing developers to register and sign-up for API usage plans" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-2))
- `tls_version`: "All communications to or from an API MUST be over TLS 1.3 or higher" ([Part B 11.1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section1-para1))
- `terms_url`: Developers must "sign up to terms and conditions" ([Part B 3.1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para3))
### Service (Phase 2+)
```json
{
"rate_limit": "string|null - Rate limit description",
"sla_url": "string|null - SLA document URL",
"uptime_target": {
"value": "number|null - Target uptime percentage (Phase 4+)",
"unit": "percent"
},
"support_hours": "string|null - Support availability (Phase 4+)",
"response_target": {
"value": "number|null - Response time target (Phase 5+)",
"unit": "milliseconds"
},
"maintenance_window": "string|null - Scheduled maintenance (Phase 5+)"
}
```
**Citations:**
- `rate_limit`: "Throttling to make sure all consumers can get access" and "quota management" ([Part A 4.3](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section3-para15))
- `sla_url`: "A place to publish API SLAs" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-8))
- `uptime_target`: "Uptime percentage (e.g., 99.9%)" ([NZ API Standard Draft](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c7-a49-p3-2))
- `support_hours`: "Application developers... will need to know... what support is offered" ([Part A 4.1.2](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para6))
- `response_target`: "Response time thresholds" ([NZ API Standard Draft](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c7-a49-p3-1))
- `maintenance_window`: "Scheduled maintenance windows" ([NZ API Standard Draft](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/#c7-a49-p3-2))
### Planning (Phase 3+)
```json
{
"roadmap_url": "string|null - API roadmap URL",
"changelog_url": "string|null - Version history URL"
}
```
**Citations:**
- `roadmap_url`: "SHOULD include roadmaps to indicate the planned evolution of an API" ([Part A 4.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para2))
- `changelog_url`: "API management gives an agency the capability to deliver good version control capability" ([Part A 2.8](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section8-para2))
### Support (Phase 5+)
```json
{
"portal_url": "string|null - Developer portal URL",
"examples_url": "string|null - Code examples URL",
"community_url": "string|null - Community/forum URL",
"status_url": "string|null - Status page URL"
}
```
**Citations:**
- `portal_url`: "Engage with, onboard, educate and manage application developers" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para2))
- `examples_url`: "Offering example code and sample applications" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-4))
- `community_url`: "Enabling developers to share knowledge... via a support community" ([Part A 5.1.1](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-6))
- `status_url`: "API availability is of utmost importance to API consumers" ([Part A 4.4.2](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section4-para5))
---
## Phased Implementation
### Phase 1: MVP Discovery
**Attributes:** identity, classification, access
| Attribute | Fields |
|-----------|--------|
| identity | name, description, contact_email |
| classification | exposure, api_type |
| access | docs_url, spec_url |
**Total fields:** 8 per API + 3 per agency
### Phase 2: Enhanced Discovery
**New attributes:** versioning, authentication, service
**New fields:**
- classification: category
- versioning: version, status
- authentication: method, registration_required
- service: rate_limit, sla_url
**Total fields:** 15 per API
### Phase 3: Lifecycle Management
**New attributes:** planning
**New fields:**
- versioning: supported_versions, deprecation_date
- planning: roadmap_url, changelog_url
**Total fields:** 19 per API
### Phase 4: Full Specification
**New fields:**
- identity: longevity
- access: spec_format, sandbox_url
- authentication: tls_version, registration_url
- service: uptime_target, support_hours
**Total fields:** 26 per API + 1 code block (embedded spec)
### Phase 5: Complete Compliance
**New attributes:** support
**New fields:**
- access: access_detail
- authentication: terms_url
- service: response_target, maintenance_window
- support: portal_url, examples_url, community_url, status_url
**Total fields:** 33 per API
---
## Markdown Document Structure
### Template
```markdown
# New Zealand Government API Catalogue
Version {N} | Phase {N}
---
## {Agency Name}
---
### Agency Information
---
#### identity
---
```json
{
"name": "{agency_name}",
"acronym": "{acronym}",
"contact_email": "{email|null}"
}
```
---
### {API Name}
---
#### identity
---
```json
{
"name": "{api_name}",
"description": "{description|null}",
"contact_email": "{email|null}"
}
```
---
#### classification
---
```json
{
"exposure": {
"value": "{value|null}",
"allowed_values": ["internal", "external", "partner", "public"]
},
"api_type": {
"value": "{value|null}",
"allowed_values": ["REST", "GraphQL", "AsyncAPI", "gRPC"]
}
}
```
---
#### access
---
```json
{
"docs_url": "{url|null}",
"spec_url": "{url|null}"
}
```
```
### Example Identifier Map
For an API catalogue with ACC as the first agency:
| Identifier | Element |
|------------|---------|
| `agency1` | Accident Compensation Corporation |
| `agency1-api1` | Agency Information |
| `agency1-api1-attribute1` | identity |
| `agency1-api1-attribute1-pf1` | JSON: {name, acronym, contact_email} |
| `agency1-api2` | ACC Developer Resource Centre |
| `agency1-api2-attribute1` | identity |
| `agency1-api2-attribute1-pf1` | JSON: {name, description, contact_email} |
| `agency1-api2-attribute2` | classification |
| `agency1-api2-attribute2-pf1` | JSON: {exposure, api_type} |
| `agency1-api2-attribute3` | access |
| `agency1-api2-attribute3-pf1` | JSON: {docs_url, spec_url} |
---
## DocRef URL Structure
Every element is addressable via the DocRef URL system:
```
https://docref.digital.govt.nz/{jurisdiction}/{publisher}/{document}/{version}/{language}/#{identifier}
```
### Example URLs
| Purpose | URL |
|---------|-----|
| Full catalogue v1 | `https://docref.digital.govt.nz/nz/dia/api-catalogue/1/en/` |
| ACC agency | `https://docref.digital.govt.nz/nz/dia/api-catalogue/1/en/#agency1` |
| ACC Developer Resource Centre | `https://docref.digital.govt.nz/nz/dia/api-catalogue/1/en/#agency1-api2` |
| API classification attribute | `https://docref.digital.govt.nz/nz/dia/api-catalogue/1/en/#agency1-api2-attribute2` |
| Classification JSON data | `https://docref.digital.govt.nz/nz/dia/api-catalogue/1/en/#agency1-api2-attribute2-pf1` |
---
## Dataset Export
When exported as a flattened dataset, each element becomes a row with ancestry columns.
### CSV Structure
```csv
id,url,type,level,parent_id,agency,api,attribute,content
agency1,https://docref.../en/#agency1,h2,1,,Accident Compensation Corporation,,,
agency1-api1,https://docref.../en/#agency1-api1,h3,2,agency1,Accident Compensation Corporation,Agency Information,,
agency1-api1-attribute1,https://docref.../en/#agency1-api1-attribute1,h4,3,agency1-api1,Accident Compensation Corporation,Agency Information,identity,
agency1-api1-attribute1-pf1,https://docref.../en/#agency1-api1-attribute1-pf1,code,4,agency1-api1-attribute1,Accident Compensation Corporation,Agency Information,identity,"{""name"":""Accident Compensation Corporation""...}"
```
### Hierarchy Reconstruction
The flattened export can be reconstructed using:
1. **Parent ID traversal**: Each record's `parent_id` points to its immediate ancestor
2. **Identifier parsing**: The concatenated identifier encodes full ancestry
3. **Level numbering**: The `level` field indicates depth
---
## Version Control
Each catalogue version generates its own identifier set within a versioned URL path.
| Capability | Implementation |
|------------|----------------|
| Reference specific version | Version number in URL path |
| Track changes | Programmatic changelogs |
| Stable historical citations | Previous versions remain addressable |
| API additions/removals | Reflected in that version's identifiers |
When the catalogue is updated, a new version is published. Previous versions remain accessible at their original URLs.
---
## Scale Estimates
At Phase 5 with 40 agencies averaging 6 APIs each:
| Element Type | Count |
|--------------|-------|
| Agency (H2) | 40 |
| API (H3) | ~280 (240 APIs + 40 agency info) |
| Attribute (H4) | ~2,200 |
| Code blocks | ~2,200 |
| **Total addressable elements** | **~4,720** |
---
## Authoritative References
All field definitions trace to these source documents:
| Document | Reference |
|----------|-----------|
| Part A: API Concepts and Management | [DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/) |
| Part B: API Security | [DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/) |
| Part C: API Development | [DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/) |
| NZ API Standard (Draft) | [DocRef](https://docref.digital.govt.nz/nz/dia/nz-api-standard/draft/en/) |
---
## Document History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | December 2025 | Initial authoritative specification |
---
*This document is the authoritative reference for the NZ Government API Catalogue data structure.*