Saltar a contenido

Guía para la identificación y uso de entidades interoperables

Indice

Introducción

Esta guía busca ayudar a los organismos de la Administración Centralizada y Descentralizada y a las Entidades Autárquicas del Gobierno de la Ciudad Autónoma de Buenos Aires a instrumentar los lineamientos en materia de apertura de datos públicos establecidos en los Decretos N°156/2012 y N° 478/2013 y a mejorar la calidad y la gestión de los datos generados por estas entidades. Está basada en la Guía para la identificación y uso de entidades interoperables elaborada por el equipo de la Dirección Nacional de Datos e Información Pública de la Secretaría de Gobierno de Modernización de la Jefatura de Gabinete de Ministros de la Nación.

Objetivo de esta guía

Esta es una guía de buenas prácticas para el uso de entidades interoperables para datos del Gobierno de la Ciudad Autónoma de Buenos Aires (GCABA). Se trata de datos básicos y fundamentales cuyo uso se repite frecuentemente entre datasets de temáticas y fuentes distintas.

Para hacer estas recomendaciones, nos basamos en la guía del Gobierno Nacional, en estándares usados a nivel nacional e internacional y en la experiencia de trabajo del equipo de la Dirección General de Calidad Institucional y Gobierno Abierto, de la Subsecretaría de Gestión Estratégica y Calidad Institucional, Secretaría General y Relaciones Institucionales del Gobierno de la Ciudad Autónoma de Buenos Aires.

Esta es una guía colaborativa y en progreso. Valoramos, y alentamos, a organizaciones y ciudadanos a plantear ideas, sugerencias, y comentarios que nos ayuden a crear un mejor documento.

Para una discusión sobre la estandarización de datos, recomendamos consultar la Guía para la publicación de datos en formatos abiertos de la Ciudad de Buenos Aires. Este documento se complementa con esa guía y la Guía para el uso y la publicación de metadatos de la Ciudad de Buenos Aires.

Datos de entidades interoperables

¿Qué son?

Las entidades interoperables son aquellas que se repiten y usan frecuentemente dentro de datasets de:

  • Temáticas diversas entre sí.

  • Una misma temática (ej.: Salud), pero no de otras (como Educación, Economía, Transporte, etc).

La mayoría de los datasets incluyen campos que responden al dónde, quién, cuándo y qué. Estos campos permiten que los datasets sean interoperables entre sí.

Veamos un ejemplo. Una matriz origen-destino de pasajeros de transporte urbano que dice cuántos viajes se hacen desde la fracción censal A a la fracción censal B, puede interoperar con datos del Censo Nacional sobre las personas que viven en A o en B (desocupación, edad, condiciones de la vivienda, actividad laboral, etc.). Decimos entonces, que la fracción censal es una entidad interoperable.

Algunos ejemplos de entidades interoperables pueden ser:

  • Transversales (afectan a la mayoría de las áreas temáticas)

    • ¿Dónde?: geografía (países, provincias, departamentos, fracciones censales, barrios, comunas, direcciones, códigos postales, plazas).

    • ¿Quién?: personas (físicas, jurídicas). Entidades (niveles gubernamentales, organismos internacionales, otros países, sociedad civil).

    • ¿Qué?: categorías presupuesto. Clasificación de bienes transables.

  • Específicas (afectan a alguna/s área/s temática/s específica/s)

    • ¿Qué?: actividades económicas. Clasificación de enfermedades. Clasificación de términos clínicos. Clasificación de unidades educativas.

¿Por qué es importante estandarizarlos?

Las entidades interoperables son las que permiten que los datasets hablen entre sí, pero esto no puede suceder cuando dos datasets nombran de forma distinta a una misma entidad interoperable (como cuando se usan distintos sistemas de ids o se nombra una misma entidad con/sin mayúsculas, usando artículos y preposiciones (o no usándolos), usando abreviaturas, siglas, tildes, forma corta o completa de un nombre, etc.

Para que los datasets puedan ser interoperables, deben identificarse todas las entidades interoperables presentes en un dataset y asegurarse de que los datos sobre ellas siguen el mismo estándar.

A continuación, proponemos una selección de estándares siguiendo los producidos por organismos de la Administración Pública Nacional y otros definidos por el Gobierno de la Ciudad Autónoma de Buenos Aires para identificación y uso de entidades interoperables presentes en un activo de datos, en algunas categorías transversales a varias áreas temáticas. Recomendamos con énfasis usarlos en todos aquellos casos en los que estén presentes esas entidades. Si por algún motivo esto fuera difícil de aplicar, sugerimos crear un diccionario que permita la traducción de estándares propios a los recomendados.

En los casos de entidades interoperables específicas sobre alguna temática, recomendamos usar el estándar más difundido entre quienes trabajan con frecuencia sobre esa temática.

Cuando no existan estándares claros para algún tipo de entidad interoperable en particular, sugerimos adoptar el mejor estándar internacional en uso, y seguirlo en forma consistente en todos los datasets que genere el organismo.

La adopción de estándares para el uso de datos de entidades interoperables está sujeto a cambios y versionados. Por eso, siempre es importante comunicarlos en forma clara y consistente.

Consideramos a los estándares que recomendamos en este documento como suficientemente estables, abarcativos, difundidos y mantenidos como para que su uso sea beneficioso para el aprovechamiento de los datos y su adopción transparente.

Tipos de entidades interoperables

Geográficas

Países o territorios internacionales

Siguiendo los lineamientos definidos para la Administración Pública Nacional, los nombres y códigos de países o territorios internacionales deben seguir el estándar ISO 3166-1. Recomendamos que el dataset contenga un campo con el código alfabético de 3 dígitos del estándar (Código alfa-3) y otro con el nombre completo del país en español. Para esto, recomendamos usar los "Nombres de uso común" de la lista de países y sus códigos alfa-3 que publica INDEC.

En esta guía, elegimos incluir los nombres de países oficiales y en castellano. Sin embargo, la denominación de los países varía de acuerdo al idioma que se utilice. Por eso, hacemos énfasis en la necesidad de incluir el código de país según el estándar ISO 3166, que es ampliamente usado por organismos internacionales.

A modo de ejemplo, en la Argentina nos referimos a uno de nuestros países vecinos coloquialmente como "Brasil", mientras que el nombre oficial en portugués es “República Federativa do Brasil” y la traducción oficial en español “República Federativa del Brasil”. El código de país según el estándar definido es “BRA” lo cual resuelve el problema de denominación.

Se recomienda también que el nombre del campo del código sea "pais_id" o, en el caso de que haya más de un campo “país” en el dataset, el nombre de cada campo finalice con “pais_id” (Ej.: “desde_pais_id”, “hasta_pais_id”), mientras que el campo con el nombre completo del país debería ser “pais_nombre”.

No recomendado

pais_origen pais_destino valor_usd
Argentina China 1405678
República Popular China argentina 2456786

Recomendado

origen_pais_id origen_pais_nombre destino_pais_id destino_pais_nombre valor_usd
ARG Argentina CHN China 1405678
CHN China ARG Argentina 2456786

Divisiones o unidades territoriales internas

En el caso de las divisiones o unidades territoriales internas, recomendamos usar el sistema de identificadores de la cartografía censal del Censo Nacional 2010 del Instituto Nacional de Estadística y Censos (listado de códigos y explicación metodológica) que incluye identificadores numéricos compuestos de una cantidad fija de dígitos (el tipo de datos debe ser textual, ya que tiene ceros a la izquierda que son significativos) para, entre otras, las siguientes entidades interoperables:

Cabe aclarar que las fracciones censales, la cobertura geográfica, los nomencladores y codificación de INDEC son referencias dinámicas, ya que pueden llegar a modificarse en los censos. Las incluidas en esta guía refieren al Censo Nacional de Población, Hogares y Viviendas 2010.

¿Cómo se relacionan estas entidades entre sí? Veremos que estas unidades pueden ordenarse jerárquicamente de modo tal que algunas contienen a las otras, aunque no en todos los casos. A continuación, explicamos los conjuntos de entidades que conforman una jerarquía internamente consistente.

A. Comunas -> Barrios -> Fracciones Censales -> Radios Censales (CBFR)

La Ciudad de Buenos Aires constituye una excepción a la regla PDL (partido- departamento- localidad), utilizada a nivel nacional, ya que es una localidad compuesta por departamentos (comunas), de manera que no puede componerse identificador compuesto de tipo provincia-departamento-localidad. Para este caso, recomendamos usar el identificador de jurisdicción de primer nivel de la Ciudad de Buenos Aires ("02").

Las comunas son las jurisdicciones de primer orden que marcan la división de la Ciudad Autónoma de Buenos Aires. El territorio municipal se divide en 15 comunas, siendo que algunos territorios pueden ser marcados como “Indeterminado” (98) o “Sin declarar-Desconocido-Ignorado” (99).

La generación de los límites de comunas se basó en la Ordenanza Nº 23.698 (11 de junio de 1968) completada por la Ordenanza Nº 26607 de 1972.

En Septiembre 2006 la modificación en base a la Ley Nº 1.777 y sus modificatorias que redefine los límites de los Barrios de la Ciudad y deroga la Ordenanza 26.607 de 1972. En Noviembre 2006 se delimitaron los nuevos límites de Barrios según Ley Nº 1.777 generados por la Dirección General Electoral. En Junio 2007 ocurrió la última modificación a la Ley Nº 1777. Fue sancionada como Ley Nº 2329 del 10/5/07, promulgada por Decreto Nº 779/07 del 01/06/2007. En Abril 2008 la última modificación a la Ley de Comunas 1.777 fue publicada en el Boletín Oficial Nº 2.910 del 16/04/2008. Fue sancionada como Ley Nº 2.560/08. En Diciembre del 2011 se ajustaron los límites de cada barrio a la última versión de la topología de las calles de CABA.

Una comuna se subdivide a su vez en jurisdicciones de segundo orden llamadas barrios.

La concepción de los límites de barrios fue digitalizada sobre los ejes de calle producto de la restitución del vuelo aerofotogramétrico de 1997 y, actualizaciones en base a los límites establecidos por Ordenanza N° 23.698 del 11 de junio de 1968, completada por la Ordenanza Nº 26607 de 1972.

Dicha Ley y sus modificatorias fueron derogadas y se redefinieron los nuevos límites por Ley Nº1777. Modificado a Abril de 2008, en base a la Ley Nº 2.650/08 que establece los nuevos límites de Barrios. En Diciembre del 2011 se ajustaron los límites de cada barrio a la última versión de la topología de las calles de CABA.

Un barrio, a su vez, se puede subdividir en fracciones censales, mientras que una fracción censal se subdivide en radios censales. Estas son unidades censales que forman parte de la estructura de relevamiento censal.

El tamaño de las fracciones y los radios en áreas urbanas se determina según la cantidad de viviendas. La fracción tiene un promedio de 5000 viviendas mientras que el radio tiene un promedio de 300 a 500, considerando que no es posible dividir una manzana aunque supere este promedio.

Respecto a las Fracciones y Radios Censales, los mismos siguen la metodología generada por INDEC, teniendo la siguiente lógica de generación considerando el código de provincia como “02” y las comunas de la siguiente tabla:

Código Comuna
007 1
014 2
021 3
028 4
035 5
042 6
049 7
056 8
063 9
070 10
077 11
084 12
091 13
098 14
105 15

Cabe aclarar que los barrios no integran la codificación de estas unidades pero tienen coincidencia geográfica.

Los identificadores de cada una de estas divisiones se componen, sucesivamente, así:

provincia
2 dígitos
"02"
CABA
comuna
5 dígitos
"02007"
Comuna 1
fracción censal
7 dígitos
"0200702"
radio censal
9 dígitos
"020070201"
  • Provincia: 2 dígitos. Ej.: "02" es la "Ciudad Autónoma de Buenos Aires".

  • Comuna: 5 dígitos. - Ej.: "02007" es la Comuna 1 de la “Ciudad Autónoma de Buenos Aires”.

  • Fracciones censales: 7 dígitos. - Ej.: "0200702" es una Fracción Censal de la Comuna 1 de la “Ciudad Autónoma de Buenos Aires”.

  • Radios censales: 9 dígitos. - Ej.: "020070201" es un Radio Censal de la Fracción Censal “0200702” de la Comuna 1 de la “Ciudad Autónoma de Buenos Aires”.

B. Villas -> Unidades Territoriales de Inclusión Urbana

A desarrollar

C. Otros nomencladores (espacios verdes, escuelas, centros de salud)

A desarrollar

D. ¿Cómo nombrar los campos?

Al igual que en el caso de los países o territorios internacionales, el dataset debe contener un campo con el código de la división o unidad territorial interna y otro con el nombre o descripción (en caso de que la tenga, anteriormente dijimos que las fracciones y radios censales no tienen nombre o descripción).

Los nombres de los campos identificadores deben ser, respectivamente:

  • "provincia_id"
  • "departamento_id"
  • "fraccion_id"
  • "radio_id"
  • "municipio_id"
  • "localidad_id"
  • "aglomerado_id"

Análogamente, debe reemplazarse "_id" por “_nombre” para nombrar los campos que contiene el nombre de cada entidad, cuando esta lo tiene.

Resaltamos la importancia de que el tipo de datos del campo de un identificador es "textual" y no “numérico”. Esto es así porque un valor de tipo numérico no podría comenzar con ceros.

No recomendado

provincia flujo_comercial_tipo valor_usd
Ciudad de Buenos Aires Exportación 44949874
CABA Importación 44040711

Recomendado

provincia_id provincia_nombre flujo_comercial_tipo valor_usd
02 CABA Exportación 44949874
02 CABA Importación 44040711

Direcciones y lugares

Siempre que sea posible, cuando un dataset contenga información que identifica a un punto en el espacio geográfico, recomendamos incluir las coordenadas de la manera establecida en la tercera tabla. Las coordenadas de un punto deben ser números decimales negativos o positivos contenidos en dos campos llamados "lat" y long.

Si el dataset contiene información sobre direcciones (especialmente en los casos en los que no sea posible proveer coordenadas), recomendamos incluir:

  • "calle_nombre"
  • "calle_altura"
  • "barrio"
  • "comuna"
  • "codigo_postal"
  • "codigo_postal_argentino"
  • "localidad_id"
  • "localidad_nombre"
  • "provincia_id"
  • "provincia_nombre"

Si el dataset incluye direcciones fuera del territorio argentino, deben además incluirse:

  • "pais_id"
  • "pais_nombre"

Para normalizar las direcciones de la CABA, recomendamos utilizar el servicio del Normalizador de direcciones CABA de la Unidad de Sistemas de Información Geográfica (USIG) del Gobierno de la Ciudad Autónoma de Buenos Aires.

No recomendado

lugar_nombre calle_nombre calle_altura ciudad
Teatro Colón Cerrito 604 Ciudad Autónoma de Buenos Aires, CABA

Aceptable 1 - sólo dirección normalizada

lugar_nombre calle_nombre calle_altura localidad_id localidad_nombre provincia_id provincia_nombre
Teatro Colón Cerrito 604 02001010 CABA 02 CABA

Aceptable 2 - sólo coordenadas

lugar_nombre lat long
Teatro Colón -34.601041 -58.383079

Aceptable 3 - dirección con esquina

lugar_nombre calle_nombre calle_cruce localidad_id localidad_nombre provincia_id provincia_nombre
Teatro Colón Cerrito Tucumán 02001010 CABA 02 CABA

Recomendado - coordenadas y dirección normalizada

lugar_nombre calle_nombre calle_altura localidad_id localidad_nombre provincia_id provincia_nombre lat long
Teatro Colón Cerrito 604 02001010 CABA 02 CABA -34.601041 -58.383079

Códigos postales

Los códigos postales deben estar contenidos en un campo llamado "codigo_postal" y seguir el formato definido por el Correo Argentino para el Código Postal Argentino (CPA) a partir de la competencia asignada por la Secretaría de Comunicaciones mediante la Resolución N° 1368/98. Cuando se haga referencia al CPA, el campo deberá llamarse "codigo_postal_argentino".

El CPA amplía la información del código postal, incorporando 4 letras que permiten identificar cada cara de manzana en las localidades de más de 500 habitantes. Las localidades de menos de 500 habitantes poseen un único CPA.

El CPA se compone de:

  • 1 letra: Identifica a la Provincia.
  • 4 números: El Código Postal tradicional.
  • 3 letras: Identifican a la Cara de la Manzana.

Ej.: C1426BMD

No recomendado

codigo_postal
1426
C 1426 BMD
c1426bmd
C1426

Recomendado

codigo_postal_argentino
C1426BMD
C1426BMD
C1426BMD
C1426BMD

Personas físicas

Las personas físicas deben identificarse por su nombre completo separado en dos campos ("nombre" y “apellido”), cuando sea posible, donde deben consignarse todos los nombres y todos los apellidos que identifican a un individuo en su documento de identidad oficial, sea el que corresponda según el individuo se presente como residente nacional o extranjero.

Así mismo, recomendamos (de ser posible) agregar dos columnas "id" y “tipo_id” que respectivamente contengan el número o cadena de caracteres que constituye el identificador del documento oficial de la persona y el tipo de documento oficial al que este identificador corresponde (Ej.: DNI, LE, LC y Pasaporte).

Esto es sencillo en el caso de residentes nacionales, pero la variedad de tipos de documentos oficiales que puede presentar un residente extranjero es mucho más amplia y difícil de abarcar. En este último caso es suficiente con consignar si el documento es un "Pasaporte" u “Otro”. Adicionalmente, si el dataset puede contener datos de individuos de diferentes nacionalidades recomendamos agregar un campo “_pais” que contenga la nacionalidad del individuo de referencia.

Tal como explicamos en el caso de países o territorios internacionales, si hubiera más de un campo relativo a "personas" o la mera nomenclatura “nombre” pudiera prestarse a confusión, los campos correspondientes serán compuestos. Ejemplo:

  • "sujeto_obligado_nombre"
  • "sujeto_obligado_apellido"
  • "sujeto_obligado_id"
  • "sujeto_obligado_tipo_id"
  • "sujeto_obligado_pais_id"
  • "sujeto_obligado_pais_nombre"
  • "representante_nombre"
  • "representante_apellido"
  • "representante_id"
  • "representante_tipo_id"

No recomendado

sujeto_obligado representante
José Pérez Carlos Gómez
josé Pérez Carlos J. Gómez
Pérez, José Gómez, Carlos
Pérez, José Gómez, Carlos J.

Aceptable

sujeto_obligado_nombre sujeto_obligado_apellido representante_nombre representante_apellido
José Pérez Carlos Jorge Gómez
José Pérez Carlos Jorge Gómez
José Pérez Carlos Jorge Gómez
José Pérez Carlos Jorge Gómez

Recomendado

sujeto_obligado_nombre sujeto_obligado_apellido sujeto_obligado_id sujeto_obligado_tipo_id sujeto_obligado_pais_id sujeto_obligado_pais_nombre
José Pérez 11111111 DNI ARG Argentina
José Pérez 11111111 DNI ARG Argentina
José Pérez 11111111 DNI ARG Argentina
José Pérez 11111111 DNI ARG Argentina

Personas jurídicas

Las entidades con personería jurídica local (Ej.: empresas argentinas, ONGs argentinas, etc.) deben registrarse con su CUIT y razón social. Por ejemplo:

  • "exportador_cuit"
  • "exportador_razon_social"

No recomendado

exportador
Los Tomates Andinos
Los Tomates
Los Tomates Andinos SRL
Tomates Andinos

Recomendado

exportador_cuit exportador_razon_social
33111111117 Los Tomates Andinos SRL
33111111117 Los Tomates Andinos SRL
33111111117 Los Tomates Andinos SRL
33111111117 Los Tomates Andinos SRL

Si el dataset sólo contiene personas jurídicas registradas en la jurisdicción argentina, el enfoque recomendado para nombrar los campos es el de agregar "_cuit" y “_razon_social” ya que es una nomenclatura específica mucho más descriptiva para el usuario que “_id” y “_desc”. Da cuenta del tipo de “_id” de que se trate y del tipo de descripción asociada.

La Administración Federal de Ingresos Públicos (AFIP) mantiene un padrón actualizado de todas las personas jurídicas que tienen un CUIT registrado en esa dependencia, que puede ser usado para normalizar o buscar la razón social.

En el caso de que el dataset pueda contener personas jurídicas fuera de la jurisdicción argentina, recomendamos un enfoque análogo al tratamiento de personas físicas:

  • "inversor_id"
  • "inversor_tipo_id" (Ej.: en el caso de una empresa argentina sería “CUIT”)
  • "inversor_desc"
  • "inversor_pais_id"
  • "inversor_pais_nombre"

Recomendado

inversor_id inversor_tipo_id inversor_desc inversor_pais_id inversor_pais_nombre
33111111117 CUIT Los Tomates Andinos SRL ARG Argentina
33111111117 CUIT Los Tomates Andinos SRL ARG Argentina
1234567890 TIN Tomatoes Inc. USA Estados Unidos
987654321 Steuer-Id Tomate DEU Alemania

Dependiendo de la forma de recolección de los datos, la temática particular del dataset y las capacidades del organismo responsable del mantenimiento del activo de datos, puede ser difícil la recolección comprehensible de "_id" y “_tipo_id” de las personas jurídicas de jurisdicción extranjera. Por eso, estos campos pueden llegar a quedar frecuentemente en blanco (valor ausente). Sin embargo, recomendamos con especial énfasis registrar el nombre (“_desc”) de la entidad en cuestión y el país bajo cuya jurisdicción se encuentra.

Entidades de Gobierno de la Ciudad Autónoma de Buenos Aires

A desarrollar

Glosario

Ver Glosario