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.
Pagination
Include meta information such as total, current_page and last_page and more. The result records are available via the data key in the JSON array. Here is an example of the JSON created by returning a paginator instance from a route:
{
"total": 50,
"per_page": 15,
"current_page": 1,
"last_page": 4,
"first_page_url": "http://example.com/taxonomy/example_taxonomy/?page=1",
"last_page_url": "http://example.com/taxonomy/example_taxonomy/?page=4",
"next_page_url": "http://example.com/taxonomy/example_taxonomy/?page=2",
"prev_page_url": null,
"path": "http://example.com/",
"from": 1,
"to": 15,
"data":[
{
// Record...
},
{
// Record...
}
]
}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 |
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"
}
}
]