Taxonomy JSON Feed Spec
Written by Jane Boppert
Updated at March 20th, 2025
Table of Contents
Taxonomy Feed Specification
Overview
This document specifies the structure of JSON feeds that will communicate taxonomy terms and their associated metadata. Each feed is taxonomy-specific and provides a list of terms within that taxonomy.
Feed Structure
Each taxonomy feed must be a JSON array containing term objects. Each term object must follow the structure detailed below.
Term Object Structure
Each term object represents a taxonomy term and includes its ID, name, metadata, and other relevant properties.
Example Term Object
{
"id": 234,
"description": "News description",
"link": "https://www.pugpig.com/sections/news",
"name": "News",
"slug": "news",
"taxonomy": "sections",
"meta": {
"rank": "999",
"follow": true,
"term-picker": "normal",
"search": true,
"dynamic": true,
"suppress": false,
"image_url": "https://www.pugpig.com/news.jpg",
"section-color": "#000000",
"secondary-section-color": "#FFFFFF",
"section-color-dark": "#FFFFFF",
"secondary-section-color-dark": "#000000"
}
}Field Descriptions
Top-Level Fields
| Field | Type | Description |
|---|---|---|
id |
int |
Unique identifier for the term |
description |
string |
A brief description of the term |
link |
string |
URL associated with the term |
name |
string |
Human-readable name of the term |
slug |
string |
URL-friendly identifier for the term |
taxonomy |
string |
The taxonomy to which the term belongs |
meta |
object |
Additional metadata related to the term (optional) |
Taxonomy Meta Fields
All taxonomy meta fields are optional
| Field | Type | Default | Description |
rank |
integer |
999 | A number between 1 and 999. Used to order the taxonomy term list |
follow |
boolean |
true | Whether this term can be followed in app |
term-picker |
string |
‘normal’ | ‘featured’, ‘normal’, ‘hidden’. Where this term shows in the term picker in app |
search |
boolean |
true | Whether this term is searchable in app |
dynamic |
boolean |
true | Whether this term can generate a dynamic timeline in app |
suppress |
boolean |
false | Soft delete this term |
sections Taxonomy Meta Fields
| Field | Type | Description |
image_url |
string |
URL of an image representing the term |
section-color |
string |
Primary colour associated with the term (HEX format) |
secondary-section-color |
string |
Secondary colour associated with the term (HEX format) |
section-color-dark |
string |
Primary colour for dark mode (HEX format) |
secondary-section-color-dark |
string |
Secondary colour for dark mode (HEX format) |
contributor Taxonomy Meta Fields
| Field | Type | Description |
image_url |
string |
URL of an image representing the contributor |
byline |
string |
Contributor's byline or credit |
color |
string |
Primary color associated with the contributor (HEX format) |
Requirements
The feed must be served as a valid JSON document.
The root of the feed must be an array containing term objects.
Each term object must include all required fields.
Color values must be in HEX format (e.g., #000000).
Image URLs must be absolute and accessible.
Example Sections Feed
[
{
"id": 234,
"description": "News description",
"link": "https://www.pugpig.com/sections/news",
"name": "News",
"slug": "news",
"taxonomy": "sections",
"meta": {
"image_url": "https://www.pugpig.com/news.jpg",
"section-color": "#000000",
"secondary-section-color": "#FFFFFF",
"section-color-dark": "#FFFFFF",
"secondary-section-color-dark": "#000000"
}
},
{
"id": 235,
"description": "Sports description",
"link": "https://www.pugpig.com/sections/sports",
"name": "Sports",
"slug": "sports",
"taxonomy": "sections",
"meta": {
"image_url": "https://pugpig.com/sports.jpg",
"section-color": "#000000",
"secondary-section-color": "#FFFFFF",
"section-color-dark": "#FFFFFF",
"secondary-section-color-dark": "#000000"
}
}
]Example Contributors Feed
[
{
"id": 101,
"description": "Award-winning journalist covering global affairs.",
"link": "https://www.pugpig.com/contributors/jane-doe",
"name": "Jane Doe",
"slug": "jane-doe",
"taxonomy": "contributor",
"meta": {
"image_url": "https://pugpig.com/jane-doe.jpg",
"byline": "Senior Journalist, Global Affairs",
"section-color": "#123456"
}
},
{
"id": 102,
"description": "Technology reporter and editor.",
"link": "https://www.pugpig.com/contributors/john-smith",
"name": "John Smith",
"slug": "john-smith",
"taxonomy": "contributor",
"meta": {
"image_url": "https://example.com/john-smith.jpg",
"byline": "Technology Editor",
"section-color": "#654321"
}
}
]