What is this?

This document explains how to build a Taxonomy JSON Feed for Pugpig. A taxonomy feed is a structured data file that tells the Pugpig app about your content categories (e.g. Sections like "News" or "Sport") and contributors (e.g. journalists or authors).

Pugpig reads this feed to power features like section browsing, following topics, and contributor pages.

Feed Format

Your feed must be a valid JSON file served over HTTPS. It should contain a data array of term objects, one per taxonomy term (e.g. one per section or contributor).

Pagination

If your feed has many terms, you can paginate the results. Wrap the data array in a pagination envelope like this:

{
  "total": 50,
  "per_page": 15,
  "current_page": 1,
  "last_page": 4,
  "first_page_url": "https://example.com/taxonomy/sections/?page=1",
  "last_page_url": "https://example.com/taxonomy/sections/?page=4",
  "next_page_url": "https://example.com/taxonomy/sections/?page=2",
  "prev_page_url": null,
  "path": "https://example.com/",
  "from": 1,
  "to": 15,
  "data": [
    { ... },
    { ... }
  ]
}

If you have fewer terms and don't need pagination, you can serve the data array directly.

Term Object

Each item in the data array describes one term. Here is a full example:

{
  "id": 234,
  "name": "News",
  "slug": "news",
  "taxonomy": "sections",
  "description": "The latest news from around the world.",
  "link": "https://www.example.com/sections/news",
  "meta": {
    "rank": 1,
    "follow": true,
    "term-picker": "normal",
    "search": true,
    "dynamic": true,
    "suppress": false,
    "image_url": "https://www.example.com/images/news.jpg",
    "section-color": "#000000",
    "secondary-section-color": "#FFFFFF",
    "section-color-dark": "#FFFFFF",
    "secondary-section-color-dark": "#000000"
  }
}

Required Fields

These three fields must be present on every term:

Optional Fields

Meta Fields

The meta object lets you control how a term appears and behaves in the Pugpig app.

General Meta Fields (apply to all taxonomies)

All of these are optional. Defaults are shown below.

sections Taxonomy Meta Fields

Use these when taxonomy is "sections":

contributor Taxonomy Meta Fields

Use these when taxonomy is "contributor":

Full Examples

Sections Feed

{
  "data": [
    {
      "id": 234,
      "name": "News",
      "slug": "news",
      "taxonomy": "sections",
      "description": "The latest news.",
      "link": "https://www.example.com/sections/news",
      "meta": {
        "rank": 1,
        "image_url": "https://www.example.com/images/news.jpg",
        "section-color": "#000000",
        "secondary-section-color": "#FFFFFF",
        "section-color-dark": "#FFFFFF",
        "secondary-section-color-dark": "#000000"
      }
    },
    {
      "id": 235,
      "name": "Sport",
      "slug": "sport",
      "taxonomy": "sections",
      "description": "Sports news and coverage.",
      "link": "https://www.example.com/sections/sport",
      "meta": {
        "rank": 2,
        "image_url": "https://www.example.com/images/sport.jpg",
        "section-color": "#FF0000",
        "secondary-section-color": "#FFFFFF",
        "section-color-dark": "#FF0000",
        "secondary-section-color-dark": "#000000"
      }
    }
  ]
}

Contributors Feed

{
  "data": [
    {
      "id": 101,
      "name": "Jane Doe",
      "slug": "jane-doe",
      "taxonomy": "contributor",
      "description": "Award-winning journalist covering global affairs.",
      "link": "https://www.example.com/contributors/jane-doe",
      "meta": {
        "image_url": "https://www.example.com/images/jane-doe.jpg",
        "byline": "Senior Journalist, Global Affairs",
        "color": "#123456"
      }
    }
  ]
}

Checklist Before Submitting Your Feed

• The feed is served over HTTPS and returns valid JSON
• Every term has name, slug, and taxonomy fields
• All colour values are in HEX format (e.g. #000000)
• All image URLs are absolute (start with https://) and publicly accessible
• Slugs are URL-friendly (lowercase, hyphens instead of spaces, no special characters)