Module:Music chart/doc

This module powers the chart templates: {{Single chart}}, {{Album chart}}, {{Year-end single chart}}, and {{Year-end album chart}}.

It generates table rows with chart name, reference, and peak position for music releases. Chart definitions are stored in four main JSON pages, with auxiliary lookup files for selected charts.

Architecture

JSON pages

Chart definitions

JSON page	Definitions
single.json	Weekly single chart definitions, including the formatting schema.
album.json	Weekly album chart definitions.
year-end-single.json	Year-end single chart definitions.
year-end-album.json	Year-end album chart definitions.

Auxiliary chart data

These files provide lookup data for the chart definitions above. Edit the relevant file to update IDs, issue metadata or permalink exceptions.

JSON page	Used by	Data
chartdata-canada.json	single: Canada RPM, Canada RPM AC, Canada RPM Country, Canada RPM Dance, Canada RPM Rock album: Canada RPM, Canada RPM Country	RPM chart names, volumes, issues and dates indexed by IdNumber.
chartdata-czech.json	single: Czech Republic, Czechdigital, Slovakia2, Slovakdigital2 album: Czech, Slovakia	Chart year/week keys mapped to weekId.
chartdata-india.json	single: India Int	The first supported week, the current permalink format and irregular endings.
chartdata-romania.json	single: Romania UPFR	Weekly permalink formats and exceptions. Each week of a combined issue has its own key pointing to the same page.
chartdata-south-africa.json	single: South Africa2	Historical permalink formats, leading-zero rules and irregular endings.

Template integration

Each template calls the module with a type parameter that determines which JSON page to load:

<!-- Template:Single chart -->
<includeonly>{{#invoke:Music chart|main|type=single}}</includeonly>

<!-- Template:Album chart -->
<includeonly>{{#invoke:Music chart|main|type=album}}</includeonly>

<!-- Template:Year-end single chart -->
<includeonly>{{#invoke:Music chart|main|type=year-end-single}}</includeonly>

<!-- Template:Year-end album chart -->
<includeonly>{{#invoke:Music chart|main|type=year-end-album}}</includeonly>

All arguments from template calls are passed automatically. For example:

{{Single chart|Australia|1|artist=Beyoncé|song=Halo|access-date=January 1, 2025}}

The module receives: 1=Australia, 2=1, artist=Beyoncé, song=Halo, access-date=January 1, 2025, type=single.

Output structure

The template produces two table cells and a reference:

| Chart Name (Provider)<ref name="refname">"[url url_title]". lang. ref. ref_note. Retrieved access-date.</ref>
| style="text-align:center;"| Position

With rowheader=true:

! scope="row"| Chart Name (Provider)<ref>...</ref>
| style="text-align:center;"| Position

With note parameter:

| Chart Name (Provider)<ref>...</ref><br>''<small>Note text</small>''
| style="text-align:center;"| Position

Template parameters

Parameters passed to the template are used as placeholders in URL and title templates.

Common parameters

Parameter	Description
1 (chart)	Chart key (required). Must match a key in JSON data.
2 (position)	Peak position on the chart (required). Must be a number 1–200 or dash (–) for not charted.
3	Set to M for manual reference mode.
artist	Artist name.
song / album	Song or album title (depending on chart type).
year, week	Chart week identifiers. week accepts 1–53 or combined weeks like 51+52.
date	Chart date (format depends on chart).
songid, artistid, chartid, id	Numeric IDs for some charts.
url, title	For charts requiring user-provided URL.
access-date	Date when source was accessed.
publish-date	Publication date of the source (shown in reference for year-end charts).
archive-url, archive-date	Archive link and date. Used only in manual mode (3=M) or by charts that explicitly reference these parameters in their JSON definitions. Otherwise, they are reported as unused and do not add an archive link.
refname	Custom reference name (overrides auto-generated).
rowheader	Set to true to output chart name as row header.
note	Additional note displayed below chart name in small italic text.
refgroup	Reference group name for grouping footnotes (e.g., lower-alpha).
dvd	DVD/video title (alternative to album for music video charts).

Computed placeholders

Derived automatically from the date parameter. All formats work with any input date format (YYYY-MM-DD, YYYYMMDD, YYMMDD, DD-MM-YYYY, DD.MM.YYYY):

Placeholder	Output format	Example (any input → output)
{dateDigits}	YYYYMMDD (digits only)	20240115
{dateMDY}	Month Day, Year	January 15, 2024
{dateDMY}	DD.MM.YYYY	15.01.2024
{dateYMD}	YYYY-MM-DD	2024-01-15
{dateSlash}	D/M/YYYY (no leading zeros)	15/1/2024
{dateYear}	YYYY	2024

Manual reference mode

For special cases where automatic URL generation doesn't work, use manual mode by setting the third parameter to M:

{{Single chart|Australia|1|M
|url=https://example.com/custom-source
|title=Custom Source Title
|work=Billboard
|date=January 1, 2025
|access-date=January 5, 2025
}}

Manual mode:

• Requires url and title parameters
• Generates reference using {{cite news}} format
• Supports additional params: work, location, publisher, date, archive-url, archive-date, url-status
• Uses same chart name and provider from JSON

JSON data format

Each JSON page contains chart definitions grouped by country/region. The structure is:

{
  "_schema": { ... },
  "CountryGroup1": {
    "ChartKey1": { ... },
    "ChartKey2": { ... }
  },
  "CountryGroup2": {
    "ChartKey3": { ... }
  }
}

Keys starting with _ (like _schema) are ignored by the module and can be used for documentation.

Basic chart entry

{
  "Australia": {
    "Australia": {
      "chart": "Australia",
      "provider": "[[ARIA Charts|ARIA]]",
      "url": "https://australian-charts.com/showitem.asp?interpret={artist}&titel={song}&cat=s",
      "url_title": "{artist} – {song}",
      "ref": "[[ARIA Charts|ARIA Top 50 Singles]]."
    },
    "AustraliaKent": {
      "chart": "Australia",
      "provider": "[[Kent Music Report]]",
      "ref": "{{cite Kent|page={page}}}"
    }
  }
}

Note: If chart is omitted, the country group name is used as the chart name.

Core fields

Field	Required	Description	Example
chart	No	Display name for the chart. Defaults to country group name.	"Australia"
provider	No	Provider name shown in parentheses after chart name. Supports wikilinks.	"ARIA"
url	Yes*	URL template with {placeholders}. If starts with [, treated as pre-built wikilink.	"https://example.com/{artist}"
url_title	Yes*	Link title template. Combined with URL as "[url title]".	"{artist} – {song}"
ref	Yes*	Reference text shown after URL. Supports wikilinks and templates.	"ARIA Charts."
lang	No	Language note inserted between URL and ref.	"(in German)" or "(in German)"

* At least ref is required. url and url_title are required for charts with links.

URL encoding

The encode field controls how text parameters ({artist}, {song}, {album}, {dvd}) are encoded in URLs. Other parameters (IDs, dates, numbers) are not affected. It's an array of operations applied in fixed order.

Operation	Description	Example
normalize	Remove diacritics (accents). Converts é→e, ñ→n, ü→u, etc. Use for sites like Billboard that don't support accented characters in URLs.	Céline → Celine
ansi	Latin-1 (ISO-8859-1) encoding instead of UTF-8. Encodes é as %E9 (single byte) instead of %C3%A9 (UTF-8). Required by some legacy Hung Medien sites; the network's sites migrate independently.	Céline → C%E9line
lower	Convert to lowercase	The Beatles → the beatles
remove-amp	Remove & from URL text only. Used by IRMA search; the displayed link title keeps the original text.	Simon & Garfunkel → Simon++Garfunkel with default space encoding
clean-symbols	Remove special characters. Keeps only letters (a-z, A-Z), numbers (0-9), and dashes (-). Spaces become dashes. Symbols between digits become dashes (e.g., 2.0 → 2-0).	20/20 Experience! → 20-20-experience
collapse-dash	Collapse consecutive dashes to one and remove leading or trailing dashes. Takes effect together with clean-symbols.	Snakehips--Mo → Snakehips-Mo
space-plus	Replace spaces with +, full URL encoding. This is the default — only specify explicitly in multiple entries when overriding a different chart-level space setting.	The Beatles → The+Beatles
space-dash	Replace spaces with -, encode only non-ASCII. Preserves ASCII symbols like $, '. Use for Billboard and similar sites.	A$AP Rocky → A$AP-Rocky
space-url	Replace spaces with %20 (standard URL encoding)	The Beatles → The%20Beatles

Order in array doesn't matter — operations are always applied in this sequence: normalize → lower → remove-amp → clean-symbols → collapse-dash → space replacement → URL encoding.

Entry-level encode: The encode field can also be set in multiple entries to override the chart-level setting for specific URL variants.

Examples:

encode	Input	Output
(not specified)	The Beatles	The+Beatles
(not specified)	Céline & Dion	C%C3%A9line+%26+Dion
["ansi"]	Céline Dion	C%E9line+Dion
["space-dash"]	The Beatles	The-Beatles
["space-dash"]	A$AP Rocky	A$AP-Rocky
["space-url"]	The Beatles	The%20Beatles
["normalize", "space-dash"]	Céline Dion	Celine-Dion
["normalize", "lower", "clean-symbols", "space-dash"]	20/20 Experience!	20-20-experience
["normalize", "lower", "clean-symbols", "collapse-dash"]	Snakehips & Mo	snakehips-mo
["ansi", "space-dash"]	Céline Dion	C%E9line-Dion

Date validation

The date_format field specifies expected date format. If provided, the module validates user input and shows error for invalid dates.

Invalid dates used to build URLs are also added to the existing {Type} chart with unsubstituted parameters tracking category.

Format	Pattern	Example
YYYY-MM-DD	4-2-2 digits with dashes	2024-01-15
YYYYMMDD	8 digits	20240115
DD-MM-YYYY	2-2-4 digits with dashes	15-01-2024
MM-DD-YYYY	2-2-4 digits with dashes	01-15-2024
DD.MM.YYYY	2-2-4 digits with dots	15.01.2024
YYMMDD	6 digits	240115
DD.MM.YYYY–DD.MM.YYYY	Date range with dots	15.01.2024–21.01.2024
YYYY.MM.DD–YYYY.MM.DD	Date range with dots (Korean)	2024.01.15–2024.01.21
YYYYMMDD-YYYYMMDD	Date range	20240115-20240121

Date range separators: For date range formats, the module accepts en-dash (–), hyphen (-), and tilde (~) as separators. In the params column of showCharts output, all separators are displayed as hyphen for consistency.

Use date_format_alt to accept an alternative format.

Year and week validation

The module also validates year and week parameters when provided:

• year must be exactly 4 digits (e.g., 2024)
• week must be 1–2 digits (e.g., 1, 03, 52) or combined format like 51+52

If the parameter is used in URL construction (critical), an error is shown in red and the page is added to tracking category. If only used in reference text, a warning is shown in preview mode only.

Other fields

Field	Description
defunct	Set true for inactive charts or individual multiple variants. Adds tracking category and highlights the affected row in showCharts.
alias_for	Variant to another chart key. Entry should contain ONLY this field. Should gradually be replaced with the main ones and deleted.
ref_note	Note/instruction shown AFTER ref in standard mode, or as prefix in combine mode. Can be overridden in multiple entries.
ref_suffix	Text added AFTER "Retrieved date" in reference. Useful for additional notes that should appear at the very end.
refname_format	Custom ref name format with placeholders. Supports {param|default} syntax.
url_validation	Required substring in user-provided URL. Shows error "Invalid URL. Required domain: X." if missing.
track_param	Parameter name to track. Creates category if parameter is missing.
number_one_category	Category added when position equals 1.
category_conditions	Array of conditional categories. Each element: {"when": "condition", "category": "Category name"}. See Condition syntax. All matching conditions add their category.
doc_note	Documentation note shown in showCharts table (when notes=yes). Can be set at chart level or in individual multiple entries.

Note: Punctuation (periods) between reference parts is added automatically by the module. Do not include trailing periods in ref, ref_note, or ref_suffix values in JSON.

Multiple URL variants

For charts that have different URL structures depending on available parameters, use the multiple array:

{
  "Denmark": {
    "chart": "Denmark",
    "provider": "[[Hitlisten|Tracklisten]]",
    "multiple": [
      {
        "when": "year, week",
        "url": "http://hitlisten.nu/default.asp?w={week}&y={year}&list=t40",
        "url_title": "Track Top-40 – Hitlisten.NU",
        "lang": "(in Danish)"
      },
      {
        "when": "artist, song",
        "url": "https://danishcharts.dk/showitem.asp?interpret={artist}&titel={song}&cat=s",
        "url_title": "{artist} – {song}"
      }
    ],
    "ref": "[[Hitlisten|Tracklisten]]."
  }
}

The module checks entries in order and uses the first one where when condition matches.

Condition syntax

Syntax	Meaning	Example
param	Parameter exists and is not empty	"when": "year"
!param	Parameter is missing or empty	"when": "!url"
param=value	Parameter equals specific value	"when": "type=remix"
param<value	Parameter is less than value (numeric)	"when": "year<1987"
param>value	Parameter is greater than value (numeric)	"when": "year>2000"
param<=value	Parameter is less than or equal (numeric)	"when": "year<=2002"
param>=value	Parameter is greater than or equal (numeric)	"when": "year>=2003"
date<value	Date/year is less than value	"when": "date<2021-07-01"
archivedate<value	Archive date/year is less than value	"when": "archivedate<2021-07-01"
year+week<=2016+34	Compact combined year/week or year/month comparison	"when": "year+week<=2016+34"
year..., week...	Adjacent same-operator year/week or year/month comparisons in one AND chain are also treated as one combined boundary	"when": "year>2016, week>34"
a, b	AND — all conditions must match	"when": "year, week"
a | b	OR — any condition must match	"when": "artist | song"
helper=value	Helper function returns specific value	"when": "helper=my_value"
(empty)	Default fallback — always matches	"when": ""

Notes:

• Conditions are checked in order; first match wins (for multiple)
• For category_conditions, ALL matching conditions add their categories
• Numeric comparisons convert values to numbers; non-numeric values become 0
• For date, archivedate, and archive-date, comparisons use full YYYY-MM-DD when the compared value is in ISO format; otherwise they compare by year
• Compact comparisons like year+week<=2016+34 and year+month>=2023+7 are supported directly
• Adjacent year+week and year+month comparisons inside one AND chain are also treated as combined comparisons when both parts use the same operator
• The position parameter is available in category_conditions

Examples:

{ "when": "date>2021-07-01" }
{ "when": "archivedate<=2021-12-31" }
{ "when": "year+week>2016+34" }
{ "when": "year+week>2016+34, year+week<=2016+42" }
{ "when": "year+month>=2023+7" }

These examples mean, respectively: after a full ISO date boundary, on/before an archive date boundary, after 2016 week 34, within the 2016w35-2016w42 range, and from July 2023 onward.

Entry overrides

Each entry in multiple can override these fields from the parent chart:

• url, url_title, encode
• ref, ref_note, lang
• provider, chart
• defunct
• refname_format
• date_format, date_format_alt
• doc_note (for showCharts documentation)

Example: Different chart names by year

Some charts changed names over time. Use multiple with year conditions to override chart:

{
  "Billboarddanceclubsongs": {
    "chart": "US [[Dance Club Songs]]",
    "provider": "''[[Billboard (magazine)|Billboard]]''",
    "url": "https://www.billboard.com/artist/{artist}/chart-history/dsi",
    "url_title": "{artist} Chart History (Dance Club Songs)",
    "ref": "''[[Billboard (magazine)|Billboard]]''",
    "encode": ["lower", "space-dash"],
    "multiple": [
      {"when": "year<1987", "chart": "US [[Hot Dance Club Play]]"},
      {"when": "year<2003", "chart": "US [[Hot Dance Music/Club Play]]"}
    ]
  }
}

This outputs:

• Before 1987: "US Hot Dance Club Play (Billboard)"
• 1987–2002: "US Hot Dance Music/Club Play (Billboard)"
• 2003+: "US Dance Club Songs (Billboard)" — uses default chart from parent

The module checks entries in order. If no when matches, it uses the parent chart's values.

Use ref_note in entries for conditional notes (e.g., instructions for old chart entries):

{
  "Germany": {
    "chart": "Germany",
    "provider": "[[GfK Entertainment charts|GfK]]",
    "url": "https://www.offiziellecharts.de/titel-details-{songid}",
    "url_title": "Offizielle Deutsche Charts",
    "lang": "(in German)",
    "ref": "[[GfK Entertainment charts]]",
    "multiple": [
      {"when": "year<1977", "ref_note": "To see the peak chart position, click 'TITEL VON', followed by the artist's name"}
    ]
  }
}

In showCharts table, conditional overrides are shown inline: [year<1977 → ref_note text]

Combine mode

Set "combine": true to include ALL matching entries as a bullet list in one reference:

{
  "Finland": {
    "chart": "Finland",
    "provider": "[[The Official Finnish Charts|Suomen virallinen lista]]",
    "ref_note": "The first is domestic singles, the second is foreign:",
    "multiple": [
      {
        "url": "http://www.ifpi.fi/tilastot/myydyimmat/{year}/kotimaiset/singlet",
        "url_title": "Myydyimmät kotimaiset singlet vuonna {year}",
        "lang": "(in Finnish)"
      },
      {
        "url": "http://www.ifpi.fi/tilastot/myydyimmat/{year}/ulkomaiset/singlet",
        "url_title": "Myydyimmät ulkomaiset singlet vuonna {year}",
        "lang": "(in Finnish)"
      }
    ],
    "combine": true,
    "ref": "Musiikkituottajat – IFPI Finland."
  }
}

Output reference will contain:

The first is domestic singles, the second is foreign:
* "[url1 title1]" (in Finnish). Musiikkituottajat – IFPI Finland. Retrieved January 1, 2025.
* "[url2 title2]" (in Finnish). Musiikkituottajat – IFPI Finland. Retrieved January 1, 2025.

Helper functions

Helpers are special Lua functions for dynamic URL generation. They're defined in the module and referenced by name in JSON.

Conditional categories

The category_conditions field allows adding categories based on parameter values. Unlike number_one_category (which only checks position=1), this supports complex conditions.

{
  "UKsinglesdownloads": {
    "chart": "UK [[UK Singles Downloads Chart|Singles Downloads]]",
    "provider": "[[Official Charts|OC]]",
    "category_conditions": [
      {"when": "position=1", "category": "UK Singles Downloads Chart number-one singles"}
    ],
    "url": "...",
    "ref": "..."
  }
}

Multiple conditions can be specified — all matching conditions add their categories:

"category_conditions": [
  {"when": "position=1", "category": "Number-one singles"},
  {"when": "position<=10", "category": "Top 10 singles"},
  {"when": "year>=2020", "category": "2020s chart entries"}
]

The position parameter is available in conditions even though it's not a template parameter — it's extracted from the second positional argument.

Available helpers

Helper	Charts	Required params	Description
south_africa_week_slug	single: South Africa2	year, week	Resolves the TOSAC weekly permalink using Module:Music chart/chartdata-south-africa.json. Historical URL sizes, leading zeros and irregular pages are defined in the country JSON. Accepts padded or unpadded weeks; rejects weeks before 2021w43 and combined inputs.
australia_issue	single: Australiadance, Australiapandora, Australiaurban	url	Extracts issue number from pandora.nla.gov.au URL. Matches patterns like "Issue+123" or "issue%20456".
bulgaria_date_range	single: Bulgaria	url	Extracts and formats date range from bamp-bg.org URL. Converts "01012024-07012024.html" to "01.01.2024 – 07.01.2024".
canada_rpm	single: Canada RPM, Canada RPM AC, Canada RPM Country, Canada RPM Dance, Canada RPM Rock; album: Canada RPM, Canada RPM Country	chartid	Selects the RPM data group from the chart key and type, validates the IdNumber, and returns the published chart name, volume, issue, and date. Reports IDs that do not exist or belong to another RPM chart.
czech_week_id	single: Czech Republic, Czechdigital, Slovakia2, Slovakdigital2; album: Czech, Slovakia	year, week	Returns weekId for ifpicr.cz URL. Looks up ID from Module:Music chart/chartdata-czech.json; for future weeks beyond table, calculates based on newest entry. Weeks 51+52 share same ID.
germany_timestamp	album: GermanyComp	date	Converts DD.MM.YYYY to Unix timestamp in milliseconds for URL construction.
india_week_slug	single: India Int	year, week	Generates the standard IMI permalink slug week-W-YYYY, applies exceptions from Module:Music chart/chartdata-india.json, rejects weeks before the chart launch, and automatically supports later unlisted weeks.
oricon_page	album: Oricon	position (second argument)	Selects an Oricon pagination suffix from the peak position. Positions 11–50 use p/N/ pages; positions 1–10 and 51–200 use the base URL. Positions above 200 are rejected by the module's standard position validation.
romania_week_slug	single: Romania UPFR	year, week	Resolves a UPFR airplay chart week using Module:Music chart/chartdata-romania.json. Rejects weeks before 2021w48 and combined week inputs. For articles covering several weeks, use an individual week number; all their weeks resolve to the same article. Later unlisted weeks use the current permalink format.

The india_week_slug, romania_week_slug and south_africa_week_slug helpers share one resolver. Country files use:

• _placeholders: descriptions of the internal template tokens. {week0} means a two-digit week, not a second week or a new template parameter. Chart calls still use week.
• _first: the first supported week as a zero-padded YYYY-WW key.
• _prefix: an optional common slug prefix; an omitted prefix is an empty string.
• _default: the current suffix template using {week} (without a leading zero), {week0} (two digits) and {year}.
• _formats: optional historical templates. Each record has inclusive from/to keys and a template. The first matching record replaces _default; otherwise the current default is used. Omitted bounds are open. Keep records ordered and non-overlapping.
• exceptions: a map from YYYY-WW to a literal suffix that overrides the selected template; _prefix is still added.
• slugs: an optional map from YYYY-WW to a complete slug; these entries bypass the prefix and take precedence over exceptions. Keep each key in only one map.
• _maxweek: an optional week-number limit (52 for India; otherwise 53).

Slugs exclude the domain and surrounding slashes. Without _prefix, _default and exceptions already contain complete slugs. India uses _prefix: week- and _default: {week}-{year}; its one exception without that prefix is stored in slugs. South Africa keeps historical URL sizes and week formatting in _formats, including weeks without a leading zero in 2024. A new permalink exception only requires updating the country JSON. Use the chart year and week rather than an erroneous URL year or article publication date. Combined week inputs are rejected.

Using helpers in JSON

{
  "South Africa2": {
    "chart": "South Africa",
    "provider": "[[The Official South African Charts|TOSAC]]",
    "helper": "south_africa_week_slug",
    "url": "https://example.com/charts/{helper}/",
    "url_title": "Local \u0026 International Streaming Chart: Week {week}, {year}",
    "ref": "[[The Official South African Charts]]"
  }
}

The {helper} placeholder is replaced with the helper function's return value.

showCharts marks its sample calls internally. Helpers backed by lookup data can use this marker to return stable documentation output without requiring a real lookup ID. The marker cannot be supplied through a chart template.

Adding new helpers

1. Add function in module:

function Helpers.your_helper_name(args)
    local year = tonumber(args.year) or 0
    -- your logic here
    return "result"
end

2. Register required parameters:

Helpers.params = {
    your_helper_name = {"year", "week"},  -- params won't be flagged as "unused"
    -- ...
}

3. Use in JSON:

{
  "helper": "your_helper_name",
  "url": "https://example.com/{helper}"
}

Adding new charts

Step 1: Edit JSON page. Open the appropriate JSON page and add entry under country group:

"NewCountry": {
  "NewCountry": {
    "chart": "New Country Singles",
    "provider": "[[New Chart Provider]]",
    "url": "https://example.com/chart?artist={artist}&song={song}",
    "url_title": "{artist} – {song}",
    "ref": "New Chart Provider."
  }
}

Step 2: Verify. Use showCharts to verify:

{{#invoke:Music chart|showCharts|type=single|country=NewCountry}}

Check that:

• Required params are correctly detected
• Sample output looks correct
• No errors in output

Step 3: Add testcases. Add cases to the both proper parameters section and errors section.

Common patterns

Simple chart (artist + song):

"SimpleChart": {
  "chart": "Simple Chart",
  "provider": "[[Provider]]",
  "url": "https://example.com/{artist}/{song}",
  "url_title": "{artist} – {song}",
  "ref": "Provider Name."
}

Chart with date:

"DateChart": {
  "chart": "Date Chart",
  "provider": "[[Provider]]",
  "date_format": "YYYY-MM-DD",
  "url": "https://example.com/chart/{date}",
  "url_title": "Chart for {dateMDY}",
  "ref": "Provider Name."
}

Chart with year/week:

"WeekChart": {
  "chart": "Week Chart",
  "provider": "[[Provider]]",
  "url": "https://example.com/{year}/week-{week}",
  "url_title": "Week {week}, {year}",
  "ref": "Provider Name."
}

Chart requiring user URL:

"ManualUrlChart": {
  "chart": "Manual URL Chart",
  "provider": "[[Provider]]",
  "url_validation": "example.com",
  "url": "{url}",
  "url_title": "Chart Page",
  "ref": "Provider Name."
}

Defunct chart:

"OldChart": {
  "chart": "Old Chart",
  "provider": "[[Provider]]",
  "url": "https://web.archive.org/web/20190301000000/https://example.com/chart/{year}/{week}",
  "url_title": "Old Chart: Week {week}, {year}",
  "ref": "Provider. Archived from [https://example.com/chart/{year}/{week} the original]",
  "ref_suffix": "{{dead link|date=March 2019}}",
  "defunct": true,
  "doc_note": "Data available until March 2019."
}

Here url points to the archived copy, while ref retains a link to the original page. The local dead-link template belongs in ref_suffix. The defunct flag is separate and marks the chart itself as inactive.

Module configuration

The CONFIG table at the top of the module contains all settings.

Text output

• months — month names array for {dateMDY} placeholder
• type_names — display names for chart types
• errors — error message templates
• warnings — warning templates shown in preview mode
• text — reference text templates
• categories — tracking category templates

Position validation

• max_position — maximum allowed numeric position (default: 200)
• accepted_dashes — array of accepted dash characters for "not charted" position; en-dash (–) for enwiki, em-dash (—) for ruwiki, hyphen (-) as fallback. Example: {"–", "—", "-"}

Core settings

• default_type — default chart type when not specified
• json_path — path template to JSON data files, %s replaced with type
• category_prefix — namespace prefix for categories
• date_format_mdy — format string for {dateMDY} placeholder (%M = month name, %d = day, %Y = year)
• ref_prefixes — prefixes for auto-generated refnames by type
• error_display — where errors appear: "both" (cell and ref), "cell" only, or "ref" only
• check_unknown_params — enable/disable tracking of unknown parameters (default: true)
• check_unused_params — enable/disable tracking of unused parameters (default: true)
• date_wrapper — optional template to reformat dates in references; set to nil to output as-is, or use parser function like {{#iferror:{{#time:j F Y|%s}}|%s}} to convert "2025-01-15" → "15 January 2025"
• date_patterns — Lua patterns for validating date formats
• param_aliases — alternative parameter names that map to canonical names
• params — parameter validation groups:
  • base — exempt from unused-parameter checks
  • content — checked against the chart's JSON definition in automatic mode; includes archive-url and archive-date. Manual mode (3=M) passes archive parameters directly to {{cite news}}.
  • manual — only with |3=M mode
  • Unknown parameters trigger tracking category; add new valid params here to suppress warnings

showCharts settings

• sort_order — sort order for groups and chart IDs: "abc" (alphabetical) or "keep" (preserve JSON order)
• group_wrapper — optional template for country/group names, e.g. {{Country|%s}}; to exclude specific groups from wrapping, add [no wrap] to the group name in JSON

Reference prefixes

ref_prefixes maps chart types to their reference name prefixes:

• single → "sc" (produces refs like sc_Australia_Beyoncé)
• album → "ac" (produces refs like ac_Billboard200_Taylor Swift)
• year-end-single and year-end-album → "ye" (produces refs like ye_US_2024)

Reference naming

Default reference name format: {prefix}_{chartkey}_{suffix}

• Prefix: from ref_prefixes (sc, ac, ye)
• Suffix: artist for weekly charts, year for year-end charts

Examples:

• sc_Australia_Beyoncé
• ac_Billboard200_Taylor Swift
• ye_US_2024

Custom format via refname_format in JSON:

"refname_format": "sc_Oricon2_{songid}"
"refname_format": "sc_Finland_{artist}_{song|Airplay}"

The {param|default} syntax provides fallback if param is empty.

Entry points

main

Primary function called by templates. Processes all arguments and generates table row output.

{{#invoke:Music chart|main|type=single}}

chartExists

Utility function to check if a chart key exists in the JSON data.

{{#invoke:Music chart|chartExists|chart=Australia|type=single}}

Returns 1 if chart exists, 0 otherwise. Useful for conditional logic in templates.

showCharts

Generates a table showing all charts from JSON with sample outputs.

{{#invoke:Music chart|showCharts|type=single}}

Output columns:

Column	Parameter (default)	Description
—	type (single)	Chart type: single, album, year-end-single, year-end-album
Group	country (all)	Filters to one country/region group
Chart ID	—	Chart key. Aliases in yellow, defunct in red, multiple entries show condition.
Uses	uses (yes)	Page count using this chart (links to category)
Chart	—	Display name of the chart
Provider	—	Chart provider name
Required params	params (yes)	Parameters needed, date format in brackets
#1 Category	number1 (no)	Category when position=1
Template call	template (no)	Copy-paste template call with detected parameters
Sample ref output	ref (yes)	Generated reference with sample values. Unresolved text placeholders remain visible; braces are URL-encoded only in link targets for stable rendering.
Note	notes (no)	Shows doc_note from JSON. Consecutive identical notes are merged with rowspan.
—	splitdvd (no)	When yes, charts ending with "MV" (Music DVD) are output in a separate table below the main table.

Example with all parameters:

{{#invoke:Music chart|showCharts|type=single|country=Australia|uses=yes|params=yes|number1=yes|template=1|ref=yes|notes=yes|splitdvd=yes}}

Notes column: When notes=yes, displays doc_note field from JSON for each chart. For charts with multiple entries, each entry can have its own doc_note that overrides the chart-level note. Consecutive rows with identical notes are automatically merged using rowspan.

Output includes links to JSON data page and template testcases page.

Error handling

Validation checks

The module performs these validations:

1. Missing chart key — Error if first parameter is empty
2. Missing position — Error if second parameter is empty
3. Unknown chart — Error if chart key not found in JSON
4. Invalid position — Error if position is not a number 1–200 or accepted dash
5. Missing required parameters — Error if placeholders in URL/title can't be filled
6. Invalid date format — Error if date doesn't match expected format (when date_format specified)
7. Invalid year format — Error if year is not exactly 4 digits
8. Invalid week format — Error if week is not 1–2 digits (or combined like "51+52")
9. Manual mode missing URL/title — Error if 3=M is used without both url and title
10. URL validation — Error if user URL doesn't contain required substring (when url_validation specified)
11. Helper validation — Error if a helper rejects a parameter or lookup value
12. Unsubstituted placeholders — Error if output still contains {placeholder} patterns

Error display

Errors appear as red text. The error_display config controls where:

• "both" — Show in both table cell and reference
• "cell" — Show only in table cell
• "ref" — Show only in reference

Warnings (preview only)

Some issues show orange warnings only in preview mode (not on saved pages):

Warning	When shown
Unknown parameters	Parameters provided but not recognized by the module
Unused parameters	Parameters provided but not used by chart
Invalid date (ref only)	Date format invalid, but date only used in reference text (not URL)
Invalid year/week (ref only)	Year/week format invalid, but only used in reference text (not URL)

Detection uses {{REVISIONID}} — empty in preview, has value on saved pages.

If date is used in URL, invalid format shows as red error on all pages.

Tracking categories

Categories are added for various conditions:

Category pattern	When added
{Type} chart usages for {ChartKey}	Always (for usage tracking)
{Type} chart used with missing parameters	Required params missing
{Type} chart used with unknown chart	Chart key not found
{Type} chart with invalid position	Position is not a valid number (1–200) or accepted dash
Pages using {type} chart with unknown parameters	Unknown params provided
{Type} chart with unused parameters	Params provided but not used
{Type} chart with unsubstituted parameters	Raw {{{param}}} or {placeholder} remains in output; a URL-building date, year, or week is invalid; or a helper reports an invalid parameter or lookup value
{Type} chart called without artist	Artist param missing
{Type} chart called without song	Song param missing (single charts)
{Type} chart called without album	Album or dvd param missing (album charts)
{Type} chart used with defunct chart	Chart marked as defunct
{Type} chart making named ref	Custom refname provided
{Type} chart using manual ref mode	Manual mode (3=M) used
{Type} chart with manual mode missing url or title	Manual mode used without url or title
{Type} chart {ChartKey} without {Param} parameter	Chart-specific tracked parameter missing

Categories are only added in main namespace (ns=0, articles). They are suppressed in all other namespaces including Template, User, and Talk pages.