Period Data Source

7 min

Overview

The period data source generates a list of time periods — years or months — derived from the publication dates of issues in the Catalog API. It enables archive navigation by letting users browse issues organized by when they were published.

When to use this

Use period when building an archive or back-issue browser where users navigate by year or month. The list of periods is calculated dynamically from actual issue publication dates.

Basic Example

{
  "type": "period",
  "contextKey": "archiveYears",
  "interval": "YEAR",
  "issueFilter": {
    "publication": {
      "id": { "value": ":publicationId" }
    }
  }
}

Configuration

Type-specific properties

Property	Type	Default	Description
interval	'YEAR' \| 'MONTH'	'YEAR'	Granularity of the generated periods
issueFilter	object	—	Filters which issues are used to derive the periods
order	'ASC' \| 'DESC'	'DESC'	Order in which periods are returned
startOffset	number	0	Subtract this many intervals from the current date to define the start of the range
format	object	—	Customize display labels — { formatText, translateWithKeys? }

For common properties (contextKey, limit, batchSize, etc.) see Data Sources OverviewDa

issueFilter properties

Scopes which issues are considered when generating periods. Uses StorefrontIssueFilter.

Deprecated type. StorefrontIssueFilter is deprecated in favour of ContentFilter. The issueFilter property will be migrated to use contentFilter (same shape as the content data source) in a future release.

Filter key	Type	Description
publication	PublicationFilter	Scope to a specific publication — use publication.id
publicationDate	DateFilter	Restrict to issues published within a date range
age	{ amount, unit, operation? }	Restrict to issues of a certain age relative to now
properties	MapFilter	Filter by custom issue properties
purchasable	{ value: boolean }	Filter to purchasable or non-purchasable issues
purchased	{ value: boolean }	Filter to purchased or non-purchased issues
id	StringFilter	Filter by specific issue ID

Supports AND, OR, and condition.

Item structure

Each generated item contains:

Field	Type	Description
year	number	The year of the period
month	number	The month (1–12), only present when interval is MONTH
label	string	Human-readable label (e.g. "2024" or "January 2024")

Testing Notes / Edge Cases

No issues = no periods: If a publication has no published issues the list is empty.

interval default is YEAR: Omitting it generates year-level periods, not months.

order default is DESC: Periods are newest-first. Set "ASC" to reverse.

Gaps in publishing: Months/years without published issues do not appear in the list.

Data Sources Overviewdata

Content Data Sourceco