Aide:Données tabulaires

From mediawiki.org
This page is a translated version of the page Help:Tabular Data and the translation is 100% complete.
PD Note : si vous modifiez cette page, vous acceptez de placer votre contribution sous licence CC0. Plus d’informations sont disponibles sur le projet Aide dans le domaine public. PD

Les données tabulaires permettent aux utilisateurs de créer des tableaux de données au format CSV, et de les utiliser depuis d'autres wikis pour créer automatiquement des tableaux, des listes, ou des graphiques.

Pour créer une nouvelle table, allez sur Wikimedia Commons, et créez une nouvelle page dans l'espace de noms Data avec un suffixe .tab tel que Data:Sandbox/Name/Example.tab. N'hésitez pas à expérimenter en créant des pages avec le préfixe Sandbox/<username>/. Pour l'instant, le contenu de la page ne peut être édité que dans le format JSON brut et avec un éditeur de table de base, mais un gadget permet d'importer et d'exporter des fichiers CSV et Excel. À terme (écrit le 21 novembre 2016), nous espérons qu'il y aura un éditeur de type tableur pour simplifier l'édition des données.

Le format de données sous-jacent correspond largement à la norme Frictionless Data standard pour une ressource de données tabulaires.

Licence des données

Toutes les données de l'espace de noms Data: doivent indiquer explicitement la licence des données. La licence recommandée est du domaine public, sous licence Creative Commons Zero (CC0). Pour indiquer cela, chaque page de données doit avoir "license": "CC0-1.0", ce qui signifie que les données peuvent être utilisées sous la CC0 version 1.0, ou (à votre choix) n'importe quelle version ultérieure. En éditant les données, vous reconnaissez les conditions d'utilisation et vous acceptez irrévocablement de publier votre contribution dans le domaine public sous licence CC0.

S'il n'est pas possible de publier les données sous la licence CC0, les licences suivantes sont également supportées :

Tout modèle important des données de sources hors licence CC0 doit se conformer aux modalités d'attributions pertinentes, il est donc fortement recommandé de préférer la licence CC0 dans la mesure du possible.

Dans le futur, la liste des licences supportées par les données pourra être étendue.

Types de données

Les données JSON tabulaires prennent en charge plusieurs types de valeurs de base. Vous pouvez également utiliser null au lieu de la valeur pour la marquer comme manquante.

  • number — valeur numérique avec une partie fractionnelle optionnelle et pouvant utiliser une notation exponentielle, mais qui n'inclut pas les nombres non numériques comme NaN.
  • boolean — ne permet que les valeurs true et false.
  • string — une chaîne de caractères ne dépassant pas 400 caractères. Les caractères spéciaux comme les nouvelles lignes \n et les tabulations \t ne sont pas autorisés.
  • localized — chaîne multilingue, représentée comme un objet avec des clés qui sont les codes des langues (par exemple "en"), et des valeurs qui sont des chaînes limitées à 400 caractères. Par exemple, {"en":"string in English", "fr":"chaîne de texte en français", ...} a des valeurs chaînes de caractères à la fois pour l'anglais et pour le français.

Champs de niveaux supérieurs

Les données tabulaires possèdent plusieurs éléments de niveau supérieur, obligatoires et optionnels :

  • license — champ obligatoire, doit toujours être initialisé avec la chaîne "CC0-1.0" . Pour l'instant, les données tabulaires ne prennent en charge que la version 1.0 ou toute version ultérieure de la licence CC0 (dédicace au domaine public) Il se peut que d'autres licences de support soient disponible à l'avenir.
  • schema: {"fields": [{...}, {...}, ...]} — champ obligatoire, doit être défini sur un objet qui contient une liste. Chaque champ décrit une colonne des données du tableau. Chaque champ doit être un objet avec des valeurs obligatoires de "name" et de "type".
    • name — champ obligatoire, c'est le nom de la colonne. La valeur doit commencer par une lettre ou le caractère souligné "_", et ne doit contenir que des lettres, des soulignés ou des chiffres. Ceci est fait pour que chaque entête puisse être facilement utilisé dans un environnement de codage comme Lua ou les graphiques Vega.
    • type — champ obligatoire, doit être initialisé à l'une des valeurs suivantes : "number", "boolean", "string", ou "localized".
    • title — champ optionnel, c'est une traduction optionnelle de l'entête de la colonne. Si elle est définie, elle doit être un objet chaîne de caractères localisée.
  • data — champ obligatoire, doit toujours être initialisé avec une liste de listes. Chaque sous-liste doit avoir le même nombre d'éléments que les entêtes et correspondre aux types des valeurs.
  • description — champ optionnel, doit être défini comme une valeur de chaîne localisée - un objet avec au moins une valeur de clé, où la clé est un code de langue (par exemple en), et la valeur est une chaîne de description.
  • sources — champ optionnel, doit être une chaîne de marquage wiki décrivant la source des données.

Utilisation

Il y a deux façons d'utiliser ces données :

  • un script Lua de n'importe quel wiki peut obtenir ces données en appelant mw.ext.data.get("Example.tab"). La fonction renvoie les données tabulaires dans presque le même format que le JSON original, sauf que toutes les chaînes localisées sont converties en chaînes régulières, et le champ de licence comprend aussi un nom de licence localisé. Pour obtenir les données dans une autre langue, il suffit de passer le code de cette langue dans le second paramètre. Pour obtenir les données dans la forme originale et non modifiée, utilisez le souligné '_' comme code de langue.
  • un graphique Vega peut obtenir des données tabulaire en utilisant "tabular:///Example.tab" comme URL de la source de données.

Sur Commons, la transclusion d'une page de l'espace de noms Data, telle {{Data:Example.tab}}, la représentera sous la forme d'un tableau HTML. Pour accéder directement aux données sur une page wiki, vous pouvez importer (si vous ne les avez pas déjà fait) le module de données tabulaires (nécessite le module de la barre de navigation) et optionnellement le modèle de requête tabulaire (nécessite le module de données tabulaires mentionné ci-dessus). Avec ces outils, il est facile d'obtenir la valeur d'une seule cellule.

Exemple

{
    "license": "CC0-1.0",
    "description": {
        "en": "Some good fruits for you",
        "es": "Algunas buenas frutas para ti"
    },
    "sources": "http://example.com and [[Data]] page",
    "schema": {
        "fields": [
            { "name": "id", "type": "string", "title": { "en": "Fruit ID", "fr": "ID de fruit" }},
            { "name": "count", "type": "number", "title": { "en": "Count", "fr": "Décompte" }},
            { "name": "liked", "type": "boolean", "title": { "en": "Do I like it?", "fr": "L’aimes-tu ?" }},
            { "name": "description", "type": "localized", "title": { "en": "Fruit name", "fr": "Nom du fruit" }}
        ]
    },
    "data": [
        [
            "peaches",
            100,
            true,
            {
                "en": "Magnificent but a bit artificial sweet peaches",
                "es": "esto puede estar en español",
                "fr": "Magnifiques mais ce sont des pêches un tantinet sucrées"
            }
        ],
        
    ]
}

Voir c:Data:COVID-19 cases in Santa Clara County, California.tab pour un exemple de la manière dont les données JSON sont rendues sur Commons.

Restrictions et pièges

  • Chaque valeur de chaîne de caractères, à l'exception de "sources", ne doit pas dépasser 400 symboles. Les caractères spéciaux comme les nouvelles lignes \n et les tabulations \t ne sont pas autorisés.
  • La taille globale de la page ne peut pas dépasser 2 Mo.

Notes aux administrateurs

  • Les administrateurs de sites peuvent personnaliser les messages d'erreur, tels que jsonconfig-err-license pour s'assurer que les éditeurs connaissent la limitation dûe à CC0 seule.

Conversion des données en JSON

Il existe plusieurs outils disponibles pour convertir d'autres formats en JSON

CSV et TSV

  • convertcsv.com — sélectionner CSV vers tableau JSON pour générer la sortie sous forme de tableau JSON : sous 'output options' sélectionner l'option 'if to JSON Array, create array for column names with name'. Vous devrez encore ajouter manuellement "name:" et "type:" à chaque entrée dans "fields" (voir l'exemple ci-dessus pour le formatage)

XLS

  • xls-to-json — convertit les fichiers xls en JSON dans NodeJS

Voir aussi