View source for Help:Tabular data/zh

<languages />
{{tocright}}
{{PD Help Page}}
<div lang="en" dir="ltr" class="mw-content-ltr">
Tabular data allows users to create CSV-like tables of data, and use them from other wikis to create automatic tables, lists, and graphs.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">To create a new table, go to [[Commons:|Wikimedia Commons]], and create a new page in the '''Data''' namespace with a <code>.tab</code> suffix, such as <code>Data:Sandbox/Name/Example.tab</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Feel free to experiment by creating pages with the {{tmpl|0=<code>Sandbox/&lt;$1>/</code>|username}} prefix.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For now, page content can only be edited in the raw [[w:JSON|JSON format]] and with a basic table editor, but [[commons:MediaWiki talk:Gadget-TabularImportExport.js|a gadget]] allows import/export from/to CSV and Excel files.</span>
[[c:User:Tomastvivlaren/graphDataImport|Another script]] allows import from existing [[w:Template:Graph:Chart|graph]] wikitext. Generative AI can be prompted to import data from existing graph and table wikitext, and to update with new data.
<span lang="en" dir="ltr" class="mw-content-ltr">Eventually (written 21 November 2016), we hope there will be a spreadsheet-like editor to simplify data editing.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The underlying data format largely matches the [https://specs.frictionlessdata.io/tabular-data-resource/ Frictionless Data standard for a tabular data resource].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Data licensing ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">All data in the <code>Data:</code> namespace must explicitly indicate the license of the data.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The recommended license is Public Domain, licensed under [https://creativecommons.org/publicdomain/zero/1.0/{{cclang}} Creative Commons Zero (CC0)] license.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To indicate this, every data page must have <code>"license": "CC0-1.0"</code>, which means the data can be used under the CC0 version 1.0, or (at your option) any later version.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">By editing the data, you [[foundation:Policy:Terms of Use|agree to the Terms of Use]], and you irrevocably agree to release your contribution to the public domain under CC0.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
If it isn't possible to release the data under CC0, the following licenses are also supported:
</div>

* CC-BY:
** CC-BY-1.0: [https://creativecommons.org/licenses/by/1.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 1.0</span>]
** CC-BY-2.0: [https://creativecommons.org/licenses/by/2.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 2.0</span>]
** CC-BY-2.5: [https://creativecommons.org/licenses/by/2.5/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 2.5</span>]
** CC-BY-3.0: [https://creativecommons.org/licenses/by/3.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 3.0</span>]
** CC-BY-4.0: [https://creativecommons.org/licenses/by/4.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 4.0</span>]
** CC-BY-4.0+: [https://creativecommons.org/licenses/by/4.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution 4.0 or later version</span>]
* CC-BY-SA
** CC-BY-SA-1.0: [https://creativecommons.org/licenses/by-sa/1.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 1.0</span>]
** CC-BY-SA-2.0: [https://creativecommons.org/licenses/by-sa/2.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 2.0</span>]
** CC-BY-SA-2.5: [https://creativecommons.org/licenses/by-sa/2.5/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 2.5</span>]
** CC-BY-SA-3.0: [https://creativecommons.org/licenses/by-sa/3.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 3.0</span>]
** CC-BY-SA-4.0: [https://creativecommons.org/licenses/by-sa/4.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 4.0</span>]
** CC-BY-SA-4.0+: [https://creativecommons.org/licenses/by-sa/4.0/{{cclang}} <span lang="en" dir="ltr" class="mw-content-ltr">Creative Commons Attribution-Share Alike 4.0  or later version</span>]
* ODbL-1.0
** ODbL-1.0: [https://opendatacommons.org/licenses/odbl/summary/ <span lang="en" dir="ltr" class="mw-content-ltr">ODC Open Database License v1.0</span>]

<div lang="en" dir="ltr" class="mw-content-ltr">
Any templates that pull data from non-CC0 licensed datasets need to comply with the relevant attribution terms, hence it is highly encouraged to prefer CC0 whenever possible.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
At some future time, the list of licenses supported by the Data namespace may be expanded.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Data types ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Tabular JSON data supports several basic value types.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You may also use <code>null</code> instead of the value to mark it as missing.</span>

* <code>number</code> – <span lang="en" dir="ltr" class="mw-content-ltr">A numeric value with an optional fractional part and may use exponential [[w:E notation|E notation]], but cannot include non-numbers like [[w:NaN|NaN]].</span>
* <code>boolean</code> – <span lang="en" dir="ltr" class="mw-content-ltr">only allows <code>true</code> and <code>false</code> values.</span>
* <code>string</code> – <span lang="en" dir="ltr" class="mw-content-ltr">a text string no longer than 400 characters long.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Special characters like new lines <code>\n</code> and tabs <code>\t</code> are not allowed.</span>
* <code>localized</code> – <span lang="en" dir="ltr" class="mw-content-ltr">A multilingual string, represented as an object with keys being language codes (e.g. "en"), and values being a string with above limitations of 400 max chars.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, <code>{"en":"string in English", "fr":"chaîne de texte en français", ...}</code> has string values for both English and French.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Top-level fields ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Tabular data has several required and optional top-level elements:
</div>

{| class="wikitable"
! <span lang="en" dir="ltr" class="mw-content-ltr">Name</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Required?</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Description</span>
|-
| <code>license</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must always be set to <code>"CC0-1.0"</code> string value.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For now, tabular data only supports [[w:Creative_Commons_license#Zero_.2F_public_domain|CC0]] (Public Domain dedication) license version 1.0 or later.</span> <span lang="en" dir="ltr" class="mw-content-ltr">More license support may be available in the future.</span>
|-
| <code>schema: {"fields": [{...}, {...}, ...]}</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must set to an object that contains a list.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Each field describes a column of the tabular data.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Each field must be an object with mandatory <code>"name"</code> and <code>"type"</code> values.</span>

{| class="wikitable"
! <span lang="en" dir="ltr" class="mw-content-ltr">Name</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Required?</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Description</span>
|-
| <code>name</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">the name of the column.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The value must begin with a letter or an underscore <code>"_"</code>, and must only contain letters, underscores, or digits.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is done so that each header can be easily used from a coding environment like Lua or Vega graphs.</span>
|-
| <code>type</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must be set to one of these values: <code>"number"</code>, <code>"boolean"</code>, <code>"string"</code>, or <code>"localized"</code>.</span>
|-
| <code>title</code> || {{optional}}
| <span lang="en" dir="ltr" class="mw-content-ltr">an optional translation for the column's header.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If set, it must be a localized string object.</span>
|}

|-
| <code>data</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must always be set to a list of lists.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Each sub-list must have the same number of elements as headers, and must match the value types.</span>
|-
| <code>description</code> || {{optional}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must be set to a localized string value - an object with at least one key-value, where the key is a language code (e.g. "en"), and the value is a description string.</span>
|-
| <code>sources</code> || {{optional}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must be a Wiki markup string value that describes the source of the data.</span>
|-
| <code>mediawikiCategories</code> || {{optional}}
| <span lang="en" dir="ltr" class="mw-content-ltr">must be set to a list that contains objects. Each object can have two values:</span>

{| class="wikitable"
! <span lang="en" dir="ltr" class="mw-content-ltr">Name</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Required?</span> !! <span lang="en" dir="ltr" class="mw-content-ltr">Description</span>
|-
| <code>name</code> || {{required}}
| <span lang="en" dir="ltr" class="mw-content-ltr">name of a category the tabular data page itself should be added to.</span>
|-
| <code>sort</code> || {{optional}}
| <span lang="en" dir="ltr" class="mw-content-ltr">what sort key to use for the page in the category.</span>
|}

|}

<div lang="en" dir="ltr" class="mw-content-ltr">
== Usage ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
There are two ways to use this data on-wiki:
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">A Lua script on any wiki can get this data by calling <code>mw.ext.data.get("Example.tab")</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The function returns tabular data in almost the same format as the original JSON, except that all localized strings will be converted to regular strings, and the license field will also include a localized license name.</span> <span lang="en" dir="ltr" class="mw-content-ltr">To get the data in another language, pass language code as the second parameter.</span> <span lang="en" dir="ltr" class="mw-content-ltr">To get the data in the original, unmodified form, use "_" as the language code.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">{{ll|Extension:Chart|Chart}} renderings are backed by tabular data, either using the page referenced in the <code>Data:Example.chart</code> format page's <code>"source": "Example.tab"</code> field or overridden on the invocation as with <code><nowiki>{{#chart:Example.chart|source=Example.tab}}</nowiki></code>.</span> (<span lang="en" dir="ltr" class="mw-content-ltr">This replaces the older Vega graph system which could get tabular data by using <code>"tabular:///Example.tab"</code> as the data source url.</span>)

<span lang="en" dir="ltr" class="mw-content-ltr">On Commons, transcluding a page from the Data namespace, i.e. <code><nowiki>{{Data:Example.tab}}</nowiki></code>, will render it as an HTML table.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To access data directly on a wiki page, you can import (if you don't already have them) the [[w:Module:Tabular data|tabular data module]] (requires the [[w:Module:Navbar|navbar module]]) and optionally the [[w:Template:Tabular query|tabular query]] template (requires the before mentioned tabular data module).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">With these tools you can easily get the value of a single cell.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Example ==
</div>
<syntaxhighlight lang="json">
{
    "license": "CC0-1.0",
    "description": {
        "en": "Some good fruits for you",
        "es": "Algunas buenas frutas para ti"
    },
    "sources": "http://example.com and [[a wiki page]]",
    "schema": {
        "fields": [
            { "name": "id", "type": "string", "title": { "en": "Fruit ID", "fr": "ID de fruit" }},
            { "name": "name", "type": "localized", "title": { "en": "Fruit name", "fr": "Nom de fruit" }},
            { "name": "count", "type": "number", "title": { "en": "Count", "fr": "Décompte" }},
            { "name": "like", "type": "boolean", "title": { "en": "Do I like it?", "fr": "L’aimes-tu ?" }},
            { "name": "description", "type": "localized", "title": { "en": "Fruit description", "fr": "Description du fruit" }}
        ]
    },
    "data": [
        [
            "peaches",
            {
                "en": "Peaches",
                "es": "Melocotones",
                "fr": "Pêches"
            },
            100,
            true,
            {
                "en": "Magnificent but a bit sweet",
                "es": "Magníficos pero un poco dulces",
                "fr": "Magnifiques mais un peu sucrées"
            }
        ],
        [
            "apples",
            {
                "en": "Apples",
                "es": "Manzanas",
                "fr": "Pommes"
            },
            150,
            true,
            {
                "en": "Red, not green",
                "es": "Rojas, no verdes",
                "fr": "Rouges, pas vertes"
            }
        ]
    ],
    "mediawikiCategories": [
        {
            "name": "Example category",
            "sort": "Its sortkey"
        },
        {
            "name": "Example category 2"
        }
    ]
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
See [[c:Data:COVID-19 cases in Santa Clara County, California.tab]] for an example of how JSON data renders on Commons.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Restrictions and gotchas ==
</div>
* <span lang="en" dir="ltr" class="mw-content-ltr">Each string value except the <code>"sources"</code> must be no more than 400 symbols long.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Special characters like new lines <code>\n</code> and tabs <code>\t</code> are not allowed.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The overall size of the page may not exceed 2MB.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr"><code>null</code> values are passed by the validator but are likely to cause trouble with processing by Lua modules, as JSON <code>null</code> maps to Lua <code>nil</code> and these entries end up missing from the data row tables, causing common iteration patterns to break early.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Admin notes ==
</div>
* <span lang="en" dir="ltr" class="mw-content-ltr">Site administrators may customize error messages, such as <code>[[Commons:MediaWiki:Jsonconfig-err-license|jsonconfig-err-license]]</code> to make sure editors know about the CC0-only limitation.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Converting data to JSON ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
There are several tools available for converting other formats to JSON
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Considerations around Extension:Chart and Excel/Libreoffice Calc ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Many Excel sheets have many more columns than it makes sense to show in a diagram.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Since June 2025, {{ll|Extension:Chart}} supports graphing only ''{{ll|Extension:Chart/Transforms|select}}'' columns (curves).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Before that, to conveniently graph a subset of the curves, a version of the .tab page had to be produced with the corresponding subset of the columns.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The data can be exported from Commons as a CSV file, modified in a spreadsheet program, and then converted back to tabular JSON using [[c:MediaWiki talk:Gadget-TabularImportExport.js]].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
===CSV and TSV===
</div>
* [https://www.convertcsv.com/csv-to-json.htm convertcsv.com] – <span lang="en" dir="ltr" class="mw-content-ltr">(select "CSV to JSON Array") Generate output as JSON Array, under 'output options' select option 'if to JSON Array, create array for column names with name'.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You will still need to manually add ''name:'' and ''type:'' to each entry in ''fields'' (see example above for formatting)</span>

===XLS===
* [https://www.npmjs.com/package/xls-to-json xls-to-json] – <span lang="en" dir="ltr" class="mw-content-ltr">Convert xls files to JSON in NodeJS</span>

<span id="See_also"></span>
== 参见 ==
* {{ll|Help:Map Data}} – <span lang="en" dir="ltr" class="mw-content-ltr">similarly structured map data in the <code>Data:</code> namespace on Commons.</span>
* {{ll|Extension:Chart}}
* {{ll|Extension:Scribunto/Lua reference manual#mw.loadData|2=<span lang="en" dir="ltr" class="mw-content-ltr">Lua data modules</span>}}
* {{ll|Extension:JsonConfig/Tabular|Tabular data}} – <span lang="en" dir="ltr" class="mw-content-ltr">some implementation details</span>
* {{ll|Category:Graph Template Collection}} – <span lang="en" dir="ltr" class="mw-content-ltr">templates to do graphs with the Commons Datasets</span>
* [[commons:MediaWiki:Gadget-TabularImportExport|Gadget-TabularImportExport]] – <span lang="en" dir="ltr" class="mw-content-ltr">A gadget to import from and export to CSV and Excel files, by [[User:TheDJ]].</span>
* [[commons:user:Tomastvivlaren/graphDataImport|Tomastvivlaren/graphDataImport]] – <span lang="en" dir="ltr" class="mw-content-ltr">A script to import tabular data from Graph:Chart wikitext.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">[[commons:module:Json2table]] and [[commons:template:Json2table]] – module and template that allow automatic exporting of tabular data, stored at commons, to tables in Wikipedia pages (if installed on the local Wikipedia)</span>
* [[phab:T154071]] – <span lang="en" dir="ltr" class="mw-content-ltr">Allow non-CC0 licensed data for datasets</span>
* [[meta:DataNamespace|DataNamespace]] – <span lang="en" dir="ltr" class="mw-content-ltr">previous proposal</span>

[[Category:Help{{#translation:}}]]
[[Category:Extension help{{#translation:}}]]