Guia do desenvolvedor de DSPL

DSPL é a sigla em inglês de linguagem de publicação de conjunto de dados. É um formato de representação para os metadados (informações sobre o conjunto de dados, como nome e provedor, além dos conceitos que ele contém e exibe) e dados reais de conjuntos de dados. Os conjuntos de dados descritos nesse formato podem ser importados para o Explorador de dados públicos do Google, uma ferramenta que permite uma exploração visual e avançada dos dados.

Observação: para fazer upload de dados para os dados públicos do Google usando a ferramenta de upload de dados públicos, é necessário ter uma Conta do Google.

Este documento é destinado a proprietários de dados que querem que o conteúdo deles esteja disponível no Explorador de dados públicos. Esse tópico vai além do Tutorial, examinando os detalhes do esquema da DSPL e dos recursos compatíveis. É apenas uma familiaridade básica de XML, embora o conhecimento sobre bancos de dados relacionais também seja útil.

Embora não seja um requisito, sugerimos que você leia o Tutorial, que é mais curto e fácil de entender, antes de ver este documento.

Visão geral

Um conjunto de dados DSPL é um arquivo ZIP que contém um arquivo XML e um conjunto de arquivos CSV. Os arquivos CSV são tabelas simples que contêm os dados do conjunto de dados, enquanto o arquivo XML descreve os metadados do conjunto de dados. O segundo inclui metadados informativos, como descrições de medidas, e metadados estruturais, como referências entre tabelas. Com esses metadados, os usuários que não são especialistas podem explorar e visualizar os dados.

Processo

Em geral, o processo de criação de um conjunto de dados DSPL é o seguinte (algumas etapas podem ocorrer em paralelo):

  1. Crie seu arquivo XML DSPL.
  2. Identifique as fontes de dados externas que serão usadas no conjunto de dados.
  3. Defina seus conceitos, frações e, opcionalmente, tópicos. Atualize iterativamente o conteúdo do arquivo DSPL.
  4. Exporte seus dados de origem para arquivos .csv.
  5. Criar um conjunto de dados DSPL.
  6. Envie o conjunto de dados para o Google.

Estrutura XML

Visão geral

O arquivo XML DSPL define os metadados do conjunto de dados, incluindo relações estruturais entre conceitos, frações, tópicos e tabelas. Embora seja possível criar esse arquivo manualmente, as ferramentas e os scripts de processamento de dados podem simplificar bastante o processo. Veja um arquivo DSPL de amostra em uma nova janela.

O arquivo inclui várias seções resumidas na tabela abaixo. Após a tabela, descrevemos cada uma delas com mais detalhes.

Seção Resumo Mais informações
Cabeçalho e importações O pai de todos os outros elementos do conjunto de dados. Inclui o namespace de destino (ou seja, o identificador) do conjunto de dados, além dos namespaces de todos os conjuntos de dados importados. Documentação
Informações do conjunto de dados O nome, a descrição e o URL do conjunto de dados. Documentação
Informações do provedor O nome, a descrição e o URL do provedor do conjunto de dados. Documentação
Conceitos

Definições de "coisas" que aparecem no conjunto de dados (por exemplo, países, taxa de desemprego, gênero etc.

Cada conceito tem um identificador exclusivo, que pode ser referenciado por fatias e tabelas.

 Documentação
Fatias

Combinações de conceitos para os quais há dados estatísticos no conjunto de dados. Cada fatia contém dimensões e métricas.

Fatias de referência de conceitos e também tabelas, que contêm os dados reais. Cada fatia tem um identificador exclusivo que pode ser referenciado pelas tabelas que contêm os dados reais.

 Documentação
Tabelas Defina os dados para conceitos e frações. As tabelas de conceito contêm enumerações, e as de fatia têm dados estatísticos. As tabelas são definidas no arquivo XML e apontam para arquivos .csv que contêm os dados reais. Documentação
Tópicos Categorias para organizar conceitos do conjunto de dados. Embora não sejam obrigatórias, elas podem ser muito úteis para os usuários navegarem pelos seus dados. Documentação

Cabeçalho e importações

Declarar o namespace de dados públicos

Um conjunto de dados DSPL começa com um elemento <dspl> de nível superior. Ele é usado para incluir todas as informações do conjunto de dados e indicar os namespaces que serão usados no arquivo. Veja um exemplo:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.example.com/mystats"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://schemas.google.com/dspl/2010" >
    ...
</dspl>

Um namespace é um identificador exclusivo que pode ser associado a um esquema XML (um conjunto de elementos e atributos XML). O targetNamespace fornece um URI que identifica seu conjunto de dados. Esse URI não é necessário para apontar para um recurso real, mas é recomendável fazer com que ele seja resolvido para um documento que descreva o conteúdo ou conjunto de dados.

Não é necessário fornecer um targetNamespace. Se não fizer isso, ele será gerado automaticamente no momento da importação.

O atributo targetNamespace é seguido por uma série de atributos xmlns especificando outros esquemas XML que serão usados no arquivo. Cada arquivo DSPL precisa incluir o esquema de dados públicos do Google, que tem o URI "http://schemas.google.com/dspl/2010", e usá-lo como o namespace padrão. Ele também precisa incluir o esquema XML padrão W3 identificado por "http://www.w3.org/2001/XMLSchema-instance". Conforme descrito na próxima seção, outros namespaces podem ser adicionados para incluir informações de outros conjuntos de dados.

Como importar outros namespaces do conjunto de dados

Conjuntos de dados podem reutilizar definições e dados de outros conjuntos de dados. O Google, por exemplo, disponibiliza vários conjuntos de dados básicos que definem conceitos que aparecem com frequência nos dados do usuário. Por exemplo, a maioria dos conjuntos de dados precisa de um conceito para representar anos. Em vez de definir um novo conceito, use o conceito de ano do conjunto de dados "http://www.google.com/publicdata/dataset/time". Consulte a página Conceitos canônicos para mais informações.

Para usar um conjunto de dados externo, adicione o elemento <import> ao arquivo DSPL logo após a declaração de namespace e indique o espaço de dados que você está importando, desta maneira:

<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Em seguida, adicione o namespace importado (neste caso, time="http://www.google.com/publicdata/dataset/google/time") à declaração de namespace na parte superior do arquivo, desta forma:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.stats-bureau.com/mystats"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://schemas.google.com/dspl/2010"
    xmlns:time="http://www.google.com/publicdata/dataset/google/time" >
<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Seu arquivo DSPL agora pode referenciar elementos do conjunto de dados temporais dos dados públicos do Google. Repita esse processo para cada conjunto de dados que você quer referenciar.

Como fazer referência a conteúdo em conjuntos de dados externos

Depois de importar outro conjunto de dados, você precisa ser capaz de referenciar conceitos, frações e dados desse conjunto de dados. Para fazer isso, use referências do formato prefix:other_id, em que prefix é o prefixo usado para o namespace do conjunto de dados externo.

Veja um exemplo de uma referência ao conceito year do conjunto de dados time (descrito acima):

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Informações do conjunto de dados

O elemento <info> inclui informações descritivas sobre o conjunto de dados. Veja abaixo um exemplo e detalhes sobre os elementos XML relevantes.

Exemplo

<info>
  <name>
    <value>Unemployment Rates</value>
  </name>
  <description>
    <value>Worldwide unemployment rates by region</value>
  </description>
  <url>
    <value>http://www.example.com/mystats/info.html</value>
  </url>
</info>

Elementos

Elemento Obrigatório? Descrição
<info> Sim Inclui todas as informações descritivas sobre o conjunto de dados. Inclui os elementos filhos <name>, <description> e <url>.
<name> Sim Filho de <info>. Inclui o elemento filho <value>, que identifica o nome do conjunto de dados.
<description> Opcional Filho de <info>. Inclui o elemento filho <value>, que inclui uma descrição de texto do conjunto de dados.
<url> Sim Filho de <info>. Um link para um URL com mais informações sobre o conjunto de dados.

Informações do provedor

O elemento <provider> lista informações sobre o provedor do conjunto de dados. Veja abaixo um exemplo e detalhes sobre os elementos XML relevantes.

Exemplo

<provider>
  <name>
    <value>Bureau of Statistics</value>
  </name>
  <url>
    <value>http://www.example.com</value>
  </url>
</provider>

Elementos

Elemento Obrigatório? Descrição
<provider> Sim Inclui todas as informações descritivas sobre o provedor do conjunto de dados. Inclui os elementos filhos <name> e <url>.
<name> Opcional Filho de <provider>. Inclui o elemento filho <value>, que identifica o nome do provedor de conjunto de dados.
<url> Opcional Filho de <info>. Um link para um URL com mais informações sobre o provedor do conjunto de dados.

conceitos

Descrição

Cada conjunto de dados contém um ou mais conceitos. Um conceito é uma definição de um tipo de dados que aparece em um conjunto de dados. Um conjunto de dados com dados demográficos de população, por exemplo, pode ter os conceitos país, estado, população e ano. Os valores de dados correspondentes a um determinado conceito são chamados de instâncias desse conceito. Geralmente, os conceitos são descritos no conjunto de dados, mas alguns podem ser descritos em conjuntos de dados externos, como hora ou ano.

Cada conceito pode ter uma ou mais propriedades. Uma propriedade é uma característica de uma instância de conceito estável ao longo do tempo. Por exemplo, o conceito de país pode ter as propriedades name, population e capital.

Os conceitos também podem ter um ou mais atributos. Os atributos fornecem informações no nível do conceito, e não as instâncias individuais dele. Por exemplo, se tivéssemos um conjunto de dados com um conceito de taxa de desemprego, poderíamos usar um atributo para designar que esse conceito é uma porcentagem. Outro exemplo de uso comum de atributos é fornecer informações de unidade.

Exemplo

Veja um exemplo de um conceito de país com o ID exclusivo country e a propriedade name. O ID do conceito pode ser usado para referenciar o conceito de frações e tabelas.

<concept id="country" extends="geo:location">
  <info>
    <name><value>Country</value></name>
    <description>
      <value>My list of countries.</value>
    </description>
  </info>
  <type ref="string"/>
  <property id="name">
    <info>
      <name><value>Name</value></name>
      <description>
        <value>The official name of the country</value>
      </description>
    </info>
    <type ref="string" />
  </property>
  <property concept="geo:continent" isParent="true"/>
  <property id="capital" concept="geo:city" />
  <table ref="countries_table" />
</concept>

Veja como esse exemplo funciona.

  • Esse código descreve o país do conceito, que tem o ID country e as propriedades name, continent e capital.
  • O conceito estende geo:location, o conceito canônico para locais. Ao estender geo:location, country herda todas as propriedades e atributos definidos pelo conceito estendido: nome, descrição, URL, latitude e longitude das propriedades. Não há problema para country redefinir alguns desses atributos e propriedades, desde que a definição seja consistente com a fornecida pelo conceito estendido.
  • O elemento <info> do conceito descreve as principais informações sobre ele. Ele é exibido na página de destino do conjunto de dados no Explorador de dados públicos.
  • O elemento <type> do conceito se refere ao tipo de conteúdo. Neste caso, é string, mas pode variar. O conceito População teria o tipo integer. O conceito Eurovision winner poderia ter o tipo booleano.
  • Um elemento <property> descreve cada propriedade do conceito, incluindo o ID exclusivo (id), info e type. As propriedades também podem fazer referência a conceitos para indicar que os valores são instâncias válidas desses conceitos.

  • O conceito faz referência a uma tabela de dados que aponta para o arquivo CSV que contém os dados reais. A tabela de dados é referenciada desta forma: <table ref="countries_table"/>.

    Se o conceito fizer referência a uma tabela, o arquivo de dados associado precisará listar todas as instâncias do conceito. Por exemplo, não é possível criar uma tabela que liste apenas alguns dos países incluídos no conjunto de dados. Se houver um subconjunto de países importantes para você, crie um conceito separado para descrevê-los. Por exemplo, mycountries.

Elementos

Elemento Obrigatório? Descrição
<concepts> Sim Elemento de nível superior. Inclui todos os elementos <concept>.
<concept> Sim Identifica o conceito. O valor do atributo obrigatório id precisa ser exclusivo para o conceito no conjunto de dados. Se o conceito fizer referência a uma tabela de dados do conceito, o valor de id precisará corresponder ao cabeçalho da coluna que descreve o conceito na tabela de dados. Um atributo extends pode ser usado para indicar que esse conceito estende outro. O valor de extends precisa corresponder ao ID de um conceito definido no mesmo conjunto de dados ou ter o formato prefix:concept_id, em que concept_id é o ID de um conceito definido no conjunto de dados externo importado associado a prefix.
<info> Opcional Inclui informações descritivas sobre o conceito.
<name> Sim Filho de <info>. Nome do conceito. O elemento filho <value> contém o texto, por exemplo, Country.
<description> Opcional Filho de <info>. Inclui o elemento filho <value>, que inclui uma descrição em texto do conceito.
<url> Opcional Filho de <info>. Inclui o elemento filho <value>, que inclui um URL para o conceito.
<pluralName> Opcional Filho de <info>. O nome plural do conceito. O elemento filho <value> contém o texto, por exemplo, Countries.
<totalName> Opcional Filho de <info>. Nome da combinação de todas as instâncias do conceito. O elemento filho <value> contém o texto. No caso de um conceito country, por exemplo, pode ser World.
<type> Opcional Identifica o tipo de conteúdo descrito pelo conceito. O atributo obrigatório ref tem os seguintes valores permitidos:
  • string
  • float
  • integer
  • date
  • boolean
O tipo pode ser omitido se o conceito estender outro conceito. Nesse caso, ele será herdado do conceito estendido.
<property> Opcional

Uma propriedade do conceito, como capital. O valor do atributo obrigatório id precisa ser exclusivo do conceito. Um atributo concept opcional pode ser usado para indicar que os valores dessa propriedade são instâncias de um determinado conceito. Se concept for especificado, id poderá ser omitido. O valor dele é definido implicitamente como o ID do conceito referenciado (por exemplo, <property concept="geo:country"/> é equivalente a <property id="country" concept="geo:country"/>).

Uma propriedade pode conter um atributo booleano isParent para indicar que a relação entre uma instância do conceito e o valor dessa propriedade é hierárquica.

Uma propriedade pode conter um atributo booleano isMapping para indicar que há um mapeamento de 1 a 1 entre as instâncias do conceito e os valores da propriedade.

Uma propriedade pode especificar uma info e um type aninhados, que são definidos da mesma forma que são para um conceito. type será necessário se a propriedade não especificar um atributo concept e precisará corresponder ao tipo do conceito referenciado, se for.
<attribute> Opcional

Um atributo do conceito. Os atributos representam informações adicionais sobre o conceito (por exemplo, PIB é uma porcentagem). O valor do atributo obrigatório id precisa ser exclusivo do conceito. Um atributo concept opcional pode ser usado para indicar que os valores desse atributo são instâncias de um determinado conceito. Se concept for especificado, id pode ser omitido. O valor dele é definido implicitamente como o ID do conceito referenciado. (ex., <attribute concept="unit:unit"/> é equivalente a <attribute id="unit" concept="unit:unit"/>.

Um atributo pode especificar um info e um type aninhados, que são definidos assim como para um conceito. type será necessário se o atributo não especificar um concept e precisará corresponder ao tipo do conceito referenciado, se for.
<table> Opcional Identifica a tabela de dados que contém os dados do conceito. O valor do atributo ref obrigatório precisa corresponder ao ID da tabela especificado no elemento <table> relacionado.

Fatias

Descrição

Fatia é uma combinação de conceitos que contêm dados. Uma fração contém dois tipos de referências de conceitos: dimensões e métricas. Uma dimensão é um conceito usado para segmentar ou filtrar seus dados. Uma métrica, por outro lado, descreve o valor observado ou os valores associados a cada ponto de dados.

Geralmente, as dimensões são categóricas, enquanto as métricas são não numéricas, variáveis e variáveis. Veja alguns exemplos protótipos de cada um:

  • Dimensões: país, estado, condado, região, ano, mês, sexo, categoria de idade, segmento do setor
  • Métricas: população, PIB, taxa de desemprego, conhecimento, receita, custo e preço

Exemplo

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Veja como esse exemplo funciona.

  • Essa parcela representa a população por país.
  • Ele tem a métrica population e as dimensões country e year. Cada dimensão é um conceito já definido em outro lugar. O conceito country e a métrica population existem no mesmo conjunto de dados que a fatia atual e são referenciados assim: concept="country"
  • O conceito year existe no tempo de conjunto de dados importado, identificado pelo prefixo usado antes do nome do conceito (year), como este: concept="time:year"
  • A fração faz referência a uma tabela de dados que aponta para o arquivo CSV que contém os dados reais. A tabela de dados é referenciada desta forma: <table ref="country_slice_table"/>. Veja acima informações sobre como importar conjuntos de dados.

Observação: em geral, o conjunto de dados será mais flexível se você reduzir as métricas e criar dimensões significativas. Por exemplo, em vez de criar as métricas Female Unemployment e Male Unemployment, crie a única métrica Unemployment e adicione a dimensão Gender que tem as instâncias Female e Male.

Elementos

Elemento Obrigatório? Descrição
<slices> Sim Elemento de nível superior. Inclui todos os elementos <slice>.
<slice> Opcional Identifica a fatia. O valor do atributo obrigatório id precisa ser exclusivo para a fatia.
<dimension> Opcional Define uma dimensão da fatia, referenciando um conceito. O valor do atributo obrigatório concept precisa corresponder exatamente ao ID exclusivo do conceito e usar um prefixo válido se o conceito pertencer a um conjunto de dados importado externo.
<metric> Opcional Define uma métrica da fatia, fazendo referência a um conceito. O valor do atributo obrigatório concept precisa corresponder exatamente ao ID exclusivo do conceito e usar um prefixo válido se o conceito pertencer a um conjunto de dados importado externo.
<table> Sim Identifica a tabela de dados que contém dados para a fatia. O valor do atributo ref obrigatório precisa corresponder ao ID da tabela especificado no elemento <table> relacionado.
<mapDimension> Opcional Filho de <table>. Contém os atributos concept e toColumn. O valor do primeiro é uma dimensão na fatia, e o valor do segundo é a coluna da tabela correspondente ao primeiro.
<mapMetric> Opcional Filho de <table>. Contém os atributos concept e toColumn. O valor do primeiro é uma métrica na fatia, e o valor do segundo é a coluna da tabela correspondente ao primeiro.

Tabelas

Descrição

A seção tables do arquivo DSPL identifica as tabelas de dados incluídas no conjunto de dados. Essas tabelas podem ser referenciadas por conceitos ou por frações. Cada elemento <table> especifica as colunas das tabelas e os tipos delas e aponta para um arquivo CSV contendo os dados da tabela.

Exemplo

<tables>
  <table id="country_slice_table">
    <column id="country" type="string"/>
    <column id="year" type="date" format="yyyy"/>
    <column id="population" type="integer"/>
    <data>
      <file format="csv" encoding="utf-8">country_slice.csv</file>
    </data>
  </table>
  ...
</tables>

Veja como esse exemplo funciona.

  • Este exemplo descreve a tabela country_slice_table. A tabela tem as colunas country, year e population.
  • Cada coluna na tabela tem um ID exclusivo, definido pelo atributo id. Esse ID precisa corresponder exatamente ao cabeçalho da coluna apropriado no arquivo de dados associado.
  • O valor do atributo opcional type define o tipo de dados de cada coluna.
  • O elemento <data> descreve o arquivo .csv real (country_slice.csv) que contém os dados da tabela. O formato do arquivo é sempre csv.

Elementos

Elemento Obrigatório? Descrição
<tables> Sim Elemento de nível superior. Inclui todos os elementos <table>.
<table> Sim Identifica a tabela. O valor do atributo obrigatório id precisa ser exclusivo para a tabela.
<column> Opcional Filho de <table>. São informações sobre uma coluna incluída na tabela. Inclui os seguintes atributos:
  • id (obrigatório): o ID da coluna.
  • type (opcional): o tipo de dados das informações na coluna especificada. Os valores permitidos são: string, float, integer, date ou boolean.
<data> Opcional Filho de <table>. O arquivo de dados referenciado pela tabela. Se o nome do arquivo estiver na forma de um URL (por exemplo, http://...), o arquivo será buscado por meio do protocolo apropriado (HTTP, HTTPS ou FTP). Caso contrário, um arquivo com esse nome precisará ser empacotado com o conjunto de dados. O valor do atributo obrigatório format é sempre csv. Embora o atributo encoding seja opcional, seus arquivos .csv precisam ser codificados em UTF-8.

Tópicos

Descrição

Os temas classificam os conceitos hierarquicamente, permitindo que os usuários naveguem pelo conjunto de dados com mais facilidade.

O elemento <topics> precisa aparecer logo antes do elemento <concepts> no arquivo DSPL. A ordem dos elementos é importante, e talvez não seja possível fazer o upload do conjunto de dados se eles estiverem na ordem errada. Para usar tópicos, faça referência a eles na definição do conceito.

Exemplo

Veja um exemplo de definição de tópico:

<topics>
  <topic id="population_indicators">
    <info>
      <name>
        <value>Population indicators</value>
      </name>
    </info>
  </topic>
  ...
</topics>

...e veja um exemplo de referência a esse tópico de um conceito:

<concept id="population">
  <info>
    <name>
      <value>Population</value>
    </name>
    <description>
      <value>Size of the resident population.</value>
    </description>
  <topic ref="population_indicators"/>
  <type ref="integer"/>
</concept>

Os temas podem ser aninhados, e um conceito pode fazer referência a mais de um tópico.

Definição do elemento

Elemento Obrigatório? Descrição
<topics> Sim Elemento de nível superior. Inclui todos os elementos <topic>.
<topic> Sim Identifica o tópico. O valor do atributo obrigatório id precisa ser exclusivo para o conjunto de dados.
<info> Opcional Filho de <topic>. Inclui informações sobre um tópico.
<name> Opcional Filho de <info>. O elemento filho <value> especifica o nome do tópico.

Arquivos de dados DSPL

Além do arquivo metadata XML, um conjunto de dados DSPL também pode incluir um ou mais arquivos de dados no formato CSV. Cada arquivo de dados é compatível com uma tabela no conjunto de dados e é mencionado no primeiro arquivo na seção <data>...</data>. Conceitualmente, esses arquivos e as tabelas associadas são usados para representar definições de conceito ou dados de fatias. Cada um desses tipos de arquivo de dados é descrito com mais detalhes abaixo.

Independentemente da finalidade, todos os arquivos de dados precisam ser arquivos de texto UTF-8 delimitados por vírgulas (CSV). Os arquivos precisam conter apenas texto simples, sem HTML. Você pode criar os arquivos de dados manualmente, mas na realidade vai precisar mascarar os dados na ferramenta que contém a fonte de dados original (por exemplo, uma planilha) ou no próprio arquivo exportado.

Os arquivos podem ser agrupados com o conjunto de dados ou, se o nome estiver na forma de um URL, buscado via HTTP, HTTPS ou FTP com base em uma fonte remota.

Arquivos de dados conceituais

Os arquivos de dados conceituais contêm informações relevantes para cada conceito. A definição do conceito usa o elemento <table> para se referir a esse arquivo.

Exemplo

Veja um exemplo de tabela para o conceito country definido acima:

country, name
AD, Andorra
AF, Afghanistan
AI, Anguilla
AL, Albania
AO, Angola
AQ, Antarctica
AS, American Samoa

Veja como este exemplo funciona:

  • A menos que os mapeamentos sejam especificados, a primeira linha do arquivo de dados (cabeçalhos da coluna) precisa corresponder exatamente ao ID do conceito e aos IDs de propriedade apropriados do conceito ao qual os dados estão associados. No entanto, a ordem das colunas não precisa ser a mesma no arquivo de dados e na tabela de conceito. Nesse caso, a primeira coluna está associada ao conceito country e a segunda coluna está associada à propriedade name.
  • As colunas de propriedade são opcionais. Se uma propriedade não tiver uma coluna na tabela, o valor dela será definido como indefinido para cada linha. Por exemplo, a tabela acima omite colunas para as propriedades latitude e longitude, portanto, os países não poderão ser mapeados.
  • Cada valor do campo de ID do conceito (neste caso, country) precisa ser exclusivo e não vazio (um campo vazio é aquele com zero ou apenas caracteres de espaço em branco).
  • Os valores de propriedades que fazem referência a outros conceitos precisam estar vazios ou ser um valor válido do conceito referenciado.
  • A inclusão de valores entre aspas duplas é opcional, exceto quando contém vírgulas, aspas duplas ou caracteres de nova linha.
  • Faz o escape de uma aspa dupla literal que aparece em um valor antes de outra aspa dupla.

Arquivos de dados do Slice

Os arquivos de dados Slices contêm dados relevantes para cada fatia. A definição da fatia usa o elemento <table ref="..."> para se referir à definição de <table>, que, por sua vez, identifica esse arquivo.

Exemplo

Veja um exemplo de um arquivo .csv contendo os dados da fração de population_by_country descrita acima:

country, year, population
AF, 1960, 9616353
AF, 1961, 9799379
AF, 1962, 9989846
AF, 1963, 10188299

Veja como o exemplo funciona:

  • O campo de métrica é population. Os campos country e year são campos de dimensão.
  • Cada valor de um campo de dimensão precisa ser preenchido. Isso inclui dimensões de tempo. Os valores dos campos de métrica podem estar vazios. Um valor vazio é representado por nenhum caractere.
  • Cada cabeçalho de coluna que faz referência a um conceito (por exemplo, o primeiro campo do exemplo acima faz referência ao conceito country) precisa corresponder exatamente ao ID exclusivo do conceito na definição.
  • Uma combinação exclusiva de valores de dimensão, por exemplo, AF, 2000, pode ocorrer apenas uma vez.
  • As linhas da mesma série temporal (ou seja, linhas que têm a mesma combinação de todos os valores de dimensão, exceto tempo) precisam ser agrupadas, mas não precisam ser classificadas de outra forma.

Recursos avançados

Conjuntos de dados multilíngues

Valores XML traduzidos

Você pode usar o atributo xml:lang com cada elemento <value> no seu arquivo DSPL. Esse atributo especifica o idioma do conteúdo do elemento usando as tags de idioma padrão do W3C. O uso desse recurso é opcional. Se nenhum atributo xml:lang for incluído, o conteúdo será considerado em inglês.

O exemplo a seguir mostra partes de um conjunto de dados em inglês, búlgaro, catalão e chinês simplificado:

<dspl ...>
  <info>
    <name>
      <value xml:lang="en">World Bank, World Development Indicators</value>
      <value xml:lang="bg">Световна банка, Индикатори за световно развитие</value>
      <value xml:lang="ca">Banc Mundial, Indicadors del desenvolupament mundial</value>
      <value xml:lang="zh-CN">国家/地区</value>
    </name>
    ...
  </info>

  <concepts>
    <concept id="country">
      <info>
        <name>
          <value xml:lang="en">Country</value>
          <value xml:lang="bg">Страна</value>
          <value xml:lang="ca">País</value>
          <value xml:lang="zh-CN">国家/地区</value>
        </name>
        ...
      </info>
      ...
    </concept>
    ...
  </concepts>

  ...
</dspl>

Propriedades traduzidas

Em alguns casos, é possível fornecer traduções que vão além dos metadados no nível do conceito, aplicando, além disso, instâncias individuais do conceito. Isso é particularmente útil quando os valores de uma propriedade de conceito (por exemplo, nome) variam de acordo com o idioma.

Para fornecer esses valores em vários idiomas, crie uma coluna na tabela de definição correspondente para cada combinação de propriedade/idioma. Em seguida, vincule essas colunas às propriedades e aos idiomas associados, adicionando um conjunto de elementos <mapProperty xml:lang="..." ref="..." toColumn="..."> à tag de referência da tabela para o conceito.

Veja um exemplo que define um conceito de país com nomes em inglês, espanhol e francês:

<concepts>
  ...
  <concept id="country" extends="geo:location">
    ...
    <property id="name">
      <info>
        <name>
          <value>Name</value>
        </name>
        <description>
          <value>The official name of the country</value>
        </description>
      </info>
      <type ref="string" />
    </property>
    ...
    <table ref="countries_table">
      <mapProperty xml:lang="en" ref="name" toColumn="name_en"/>
      <mapProperty xml:lang="es" ref="name" toColumn="name_es"/>
      <mapProperty xml:lang="fr" ref="name" toColumn="name_fr"/>
    </table>
  </concept>
  ...
</concepts>

...

<tables>
  ...
  <table id="countries_table">
    <column id="country" type="string"/>
    <column id="name_en" type="string"/>
    <column id="name_es" type="string"/>
    <column id="name_fr" type="string"/>
    ...
  </table>
</tables>

O arquivo CSV do countries_table teria o seguinte formato:

country,name_en,name_es,name_fr,...
...
US,United States of America,Estados Unidos de América,États-Unis d'Amérique,...
...

Conceitos que podem ser mapeados

Muitos conceitos (por exemplo: condado, estado e cidade) têm instâncias correspondentes a localizações geográficas. A DSPL é compatível com a geocodificação dessas instâncias para que elas possam ser visualizadas no gráfico de mapas animados dos dados públicos do Google.

Se o conceito for equivalente a países, estados ou condados dos EUA, você poderá apenas vincular ao conceito canônico do Google correspondente, sem necessidade de geocodificação explícita. Para mais detalhes, consulte o Guia de conceitos canônicos.

Caso contrário, é necessário permitir que o conceito seja mapeado. A primeira etapa é estender a função de geo:location:

<concept id="..." extends="geo:location">
  ...
</concept>

Em seguida, adicione explicitamente a latitude e a longitude como propriedades:

<concept id="..." extends="geo:location">
  ...
  <property id="latitude"/>
  <property id="longitude"/>
</concept>

Os valores são especificados como colunas na tabela de dados de definição de conceito correspondente.

Relacionamentos de conceito

Os conceitos geralmente estão relacionados a outros conceitos de maneira estruturada. Por exemplo, uma instância de continente pode incluir várias instâncias de país, que por sua vez podem conter várias instâncias de estado ou província. A codificação dessas relações nos metadados do conjunto de dados possibilita recursos de visualização mais detalhados do que seria possível, por exemplo, mostrar uma árvore de locais recolhíveis para escolher.

Nas seções abaixo, descrevemos as relações de conceito aceitas no esquema DSPL.

hierarquias

Hierarquias de conceitos são representadas no DSPL pelo uso de um atributo isParent="true" em uma tag <property> do conceito filho, que contém identificadores de instâncias do conceito pai.

Por exemplo, o conceito de condado dos EUA do Google tem o seguinte formato:

<concept id="us_county" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">County</value>
    </name>
    ...
  </info>
  ...
  <property id="state" concept="us_state" isParent="true"/>
  ...
  <data>
    <table ref="reference_us_counties"/>
  </data>
</concept>

A tabela de dados compatível tem uma coluna state com o código de estado de duas letras para cada país. Esse tipo de metadados permite que o Explorador de dados públicos mostre estados e condados como uma hierarquia, um recurso que facilita muito a exploração dos usuários.

Um conceito pode ter muitos filhos, mas não mais que um pai.

Mapeamentos

Os mapeamentos de conceitos (ou seja, conceitos que representam, basicamente, a mesma coisa) são representados por um atributo isMapping="true" em uma tag property do conceito mapeado.

Especificar que um conceito é mapeado para outro permite que o primeiro herde todas as propriedades e atributos do segundo. Entre outros aplicativos, isso é útil para "vincular" conceitos geográficos pessoais aos definidos no conjunto de dados geográficos canônicos do Google:

<concept id="my_country" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">Country</value>
    </name>
    ...
  </info>
  ...
  <property id="google_country_code" concept="geo:country" isMapping="true"/>
  <data>
    <table ref="countries_concept"/>
  </data>
</concept>

Extensões

As extensões de conceito são designadas por um elemento extends na definição de conceito correspondente. As extensões são úteis para indicar que um conceito específico é uma subclasse de outro conceito mais amplo. O conceito estendido herda todos os atributos e propriedades do pai e também pode adicionar outros.

Por exemplo, o conceito currency do Google estende unit:

<concept id="unit">
  ...
</concept>

<concept id="currency" extends="unit">
  <info>
    <name>
      <value xml:lang="en">Currency unit</value>
    </name>
    ...
  </info>
  ...
  <table ref="currency_table"/>
</concept>

Consulte a discussão sobre extensões de conceito no tutorial para mais explicações e exemplos.

Como enviar seu conjunto de dados

Para enviar seu conjunto de dados para o Explorador de dados públicos do Google, siga estas instruções:

  1. Crie um diretório.
  2. Salve o arquivo dspl do conjunto de dados no diretório que você criou. Use a extensão .xml.
  3. Salve todos os arquivos .csv locais no mesmo diretório. Os arquivos de dados referenciados por URLs podem ser omitidos.
  4. Compacte o diretório.
  5. Faça o upload do conjunto de dados para o Explorador de dados públicos do Google.

Depois de fazer upload e validar o conjunto de dados, faça o teste com sua Conta do Google para testá-lo. Ela não será publicada até que você a verifique e diga que está pronta.