Guía de Publicadores

Esta página es para los publicadores de datos OCDS. Proporciona:

  • Una introducción a las extensiones y las necesidades que satisfacen
  • Guías prácticas para usar y crear extensiones
  • Documentación de referencia para creadores de extensiones

Introducción

Para implementar OCDS, debes identificar los campos y códigos en OCDS que coinciden con los elementos de datos en tus fuentes de datos. Es posible que algunos elementos de datos no coincidan con ningún campo o código en OCDS. Para cubrir estos casos, puedes agregar campos y códigos a OCDS mediante "extensiones".

Las extensiones sirven para documentar el significado y la estructura de campos y códigos adicionales. Los beneficios son:

  • Al reutilizar extensiones, tus datos son consistentes con los datos de otros publicadores, lo que hace posible que tu y otros reutilicen las herramientas y metodologías de OCDS.
  • Los analistas pueden acceder a las definiciones de tus campos y códigos adicionales para ayudarlos a interpretar tus datos.
  • Los desarrolladores pueden leer la estructura de tus campos y códigos adicionales para ayudar a escribir software para procesarlos.

Cómo utilizar una extensión

  1. Busca una extensión que describa los elementos de datos que deseas publicar. Si no puedes encontrar una extensión adecuada, es posible que debas crear una extensión.
  2. Estructura tus datos de acuerdo con el esquema y la documentación de la extensión.
  3. Declara la extensión en la lista de extensions del paquete , utilizando la URL de la documentación de la extensión. Por ejemplo, para declarar la extensión Ofertas y expresiones de interés:
    {"extensions": ["https://raw.githubusercontent.com/open-contracting-extensions/ocds_bid_extension/master/extension.json"]}
  4. Verifica tus datos utilizando la herramienta de revisión de datos OCDS.

Cómo crear una extensión

Si no puedes encontrar una extensión adecuada para describir los elementos de datos que deseas publicar, puedes crear una extensión.

Las extensiones pueden agregar nuevos campos, agregar códigos a listas de códigos abiertas o agregar reglas de validación a campos existentes. Sin embargo, las extensiones no pueden eliminar campos, cambiar los títulos o descripciones de los campos ni agregar códigos a listas de códigos cerradas. Para sugerir dichos cambios, abre un issue en el tracker de issues del estándar.

Considera si los datos que deseas publicar pertenecen al proceso de contratación o si existen de forma independiente. Los datos que existen de forma independiente del proceso de contratación suelen publicarse mejor en un conjunto de datos separado. Por ejemplo, los datos sobre los beneficiarios finales de los proveedores suelen recolectarse fuera de los sistemas de contratación.

Para crear una extensión que agregue un nuevo campo o regla de validación, debes comprender el esquema JSON y la estructura del esquema OCDS .

Hay seis pasos para crear una extensión:

1. Discutir

Antes de crear una extensión, busca discusiones relacionadas en el issue tracker del estándar.

Si no encuentras ninguna discusión relacionada, abre un issue en GitHub para describir la extensión que planeas crear. Incluye en la descripción del issue:

  • Casos de uso de la extensión. Describe el motivo por el que agregas campos o códigos y qué harán los usuarios con los datos.
  • El concepto o proceso que se deseas representar. Se pueden incluir referencias legislativas u otra documentación.
  • Ejemplos de datos existentes. Proporciona ejemplos de tus fuentes de datos de los elementos de datos que cubrirá la extensión.
  • Para fomentar la colaboración, mantén este issue actualizado durante todo el desarrollo de tu extensión.

2. Modelado

Una vez que tengas claros tus conceptos y casos de uso, deberás decidir el nombre, la estructura y el formato de cualquier campo adicional en tu extensión, y el nombre de cualquier código adicional.

Puedes comenzar creando un ejemplo de los datos para los que estás creando una extensión, como JSON. Considera lo siguiente:

  • ¿Cómo encajarían los diferentes datos en esta estructura?
  • ¿Los nombres de los campos y códigos son intuitivos para los usuarios?
  • ¿La estructura es fácil de consumir para las aplicaciones?

También puedes consultar otros estándares para encontrar modelos potenciales. Cuanto más consideres diferentes ejemplos de datos de origen y diferentes usos de los datos OCDS, mejor.

Antes de continuar, solicita comentarios sobre tu mockup, utilizando el issue de GitHub que creaste en el paso anterior.

3. Crear

Una vez que te decidas por un modelo, deberás crear (según corresponda) los metadatos, la documentación, el esquema y las listas de códigos. Puedes utilizar la plantilla de extensión . Para obtener más información, consulta Referencia.

4. Publicar

Debes publicar tu extensión en línea en una URL estable. Los archivos de esquema y lista de códigos de tu extensión deben ser accesibles reemplazando extension.json en la URL de la extensión con la ruta de un archivo: por ejemplo, release-schema.json o codelists/codelist.csv.

Crear un repositorio en GitHub, GitLab o Bitbucket para tu extensión es una buena opción porque ofrece control de versiones, seguimiento de problemas y URL apropiadas. Por ejemplo: https://raw.githubusercontent.com/open-contracting-extensions/ocds_bid_extension/master/extension.json

Al nombrar tu repositorio, sigue el patrón para nombres de repositorio.

5. Probar

Prueba tu extensión siguiendo los pasos 2 a 4 de Cómo usar una extensión. Verifica que la herramienta de revisión de datos de OCDS no informe errores estructurales, campos adicionales o códigos adicionales.

6. Registrar

Te animamos a que registres tu extensión, para que otros puedan descubrirla en este sitio web.

No es necesario registrar las extensiones que son relevantes para un solo publicador.

Una extensión registrada debe cumplir los siguientes criterios:

  • La documentación está en inglés. Según la política de traducción y localización, “el idioma oficial para el estándar es el inglés”.
  • La documentación, sin incluir los ejemplos, tiene más de 200 caracteres. Una documentación de menos de 200 caracteres no puede describir adecuadamente una extensión, su propósito y sus detalles técnicos.
  • Los archivos extension.json y README.md no son específicos de un publicador. Si el nombre o la descripción de la extensión sugieren que es relevante solo para un único publicador, es poco probable que la utilicen otros publicadores, incluso si sus campos y códigos son relevantes.
  • Ninguna otra extensión expresa los mismos conceptos. Tener múltiples formas de expresar el mismo concepto sería contraproducente para la estandarización.
  • La extensión sigue la guía de estilo de esquema.

Referencia

Esta sección proporciona documentación de referencia para los creadores de extensiones.

Las extensiones constan de:

Para ver visualmente la estructura de la extensión, visita la plantilla de extensión .

Metadatos (requerido)

Los metadatos de la extensión se expresan como un archivo extension.json.

El contenido del archivo debe cumplir con el esquema de extensión (visor de esquemas ).

Guía

Usa el archivo extension.json de la plantilla de extensión como punto de partida.

Puedes editar y validar tu archivo extension.json, mientras lees el esquema de extensión, utilizando el Visor de esquemas JSON de Atlassian.

Para escribir una buena descripción:

  • Describe los cambios realizados por la extensión, en un nivel alto.
  • Aunque no hay una extensión máxima, se conciso. Dicho esto, no sacrifiques la claridad en aras de la brevedad.
  • No te limites a duplicar o parafrasear el nombre de la extensión.
  • No incluyas el estado de desarrollo de la extensión (como “borrador”). Si es necesario, describa el estado en la documentación.

Por ejemplo, para Errores de rendimiento, una descripción incorrecta sería:

Una extensión que cubre fallas de rendimiento en OCDS.

Una buena descripción es:

Agrega campos a la sección de implementación para permitir la divulgación de una serie de fallas en el desempeño de la contratación. Basado en la tabla de informes de fallas en el desempeño definida en el Marco del Banco Mundial para la Divulgación de Información en las APP.

El campo description se muestra en este sitio web.

Documentación (requerida)

La documentación de la extensión se expresa como un archivo README.md.

El archivo README.md debe estar en formato Markdown.

El archivo README.md debe incluir una descripción de la extensión y sus casos de uso, y ejemplos de datos OCDS que utilizan los campos y/o códigos de la extensión.

Puedes proporcionar documentación adicionalmente al archivo README.md.

Esquema (opcional)

Los campos nuevos y modificados de la extensión se expresan como un archivo release-schema.json. Este archivo tiene la misma estructura que el esquema de release de OCDS.

El archivo contiene un fragmento del esquema JSON , conocido como JSON Merge Patch, que se puede combinar con el esquema de release de OCDS para producir un "esquema extendido".

El archivo debe describir solamente campos nuevos o campos modificados.

El contenido del archivo debe cumplir con el JSON Schema Draft 4.

El archivo debe seguir la guía de estilo de esquema .

Guía

Por ejemplo, este esquema agrega un campo statusDetails al subesquema Contract: 

{
  "definitions": {
    "Contract": {
      "properties": {
        "statusDetails": {
          "title": "Status Details",
          "description": "Additional detail on the status of the contract. This field can be used to provide the local name of the status",
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        }
      }
    }
  }
}

Si no estás familiarizado con el esquema JSON, puedes usar Transform para generar un esquema inicial a partir de una muestra o maqueta de tus datos OCDS. Luego, agrega title y description y sigue la guía de estilo de esquema, en particular la sección de palabras clave de validación.

Listas de códigos (opcional)

Las nuevas listas de códigos y los nuevos códigos de la extensión se expresan como archivos CSV en un directorio codelists. Estos archivos tienen la misma estructura que las listas de códigos de OCDS.

Un archivo de lista de códigos debe describir solamente nuevas listas de códigos o nuevos códigos.

El nombre de un archivo de lista de códigos debe estar en mayúsculas y minúsculas, como tenderStatus.csv.

El contenido de un archivo de lista de códigos debe cumplir con el esquema de lista de códigos (en el visor de esquemas , expande el acordeón Definiciones raíz y haz clic en el ítem Fila ).

Un archivo de lista de códigos debe seguir las guías de estilo para nombres de código, títulos de código y descripciones de código.

Guía

Para agregar una nueva lista de códigos, asegúrate de que su nombre de archivo no sea el mismo que el nombre de archivo de una lista de códigos existente. Agrega y completa las columnas Code, Title y Description.

Para agregar nuevos códigos a una lista de códigos abierta, crea un archivo que anteponga un signo más (+) al nombre de archivo de la lista de códigos y asegúrate de que los nuevos códigos no coincidan con ningún código existente. Utiliza las mismas columnas que la lista de códigos original.

Por ejemplo, para agregar un código de 'subcontractor' a la lista de códigos partyRole.csv, crea un archivo +partyRole.csv en el directorio codelists de tu extensión y establece su contenido como: 

Code,Title,Description
subcontractor,Subcontractor,An organization that will perform part of a contract on behalf of a supplier.

Nombre del repositorio

Los nombres de los repositorios deben seguir el patrón: ocds_{name}_extension. Por ejemplo: ocds_bidOpening_extension

El nombre debe indicar el dominio (como medicine) o el campo que se va a agregar (como coveredBy). Si el campo que se va a agregar es ambiguo, el objeto padre debe anteponer el nombre del campo (como document_publisher).