Guía de Publicadores

Para implementar el OCDS, debe de identificar los campos y códigos en OCDS que empaten con los elementos de datos que quiere publicar. Puede ser que algunos elementos de datos no coincidan con ningún campo o código en OCDS. En esos casos, puede añadir campos o códigos a sus datos OCDS. Las extensiones proveen una forma de documentar esos campos y códigos adicionales.

¿Por qué usar extensiones?

Recomendamos utilizar extensiones para describir sus campos y códigos adicionales para:

  • Que los analistas pueden acceder a varias definiciones de campos y códigos para ayudarles a interpetar sus datos.
  • Que los desarrolladores pueden acceder a información sobre la estructura de sus datos para ayudarle a escribir software para procesarlos.
  • Que sus datos sean consistentes con los de otros publicadores y compatibles con herramientas y metodologías reutilizables.

Utilizar una extensión

Publicar campos o códigos adicionales utilizando una extensión:

  1. Utilizar el Explorador de Extensiones para encontrar una extensión que describa los elemento(s) de datos que quiere publicar. Si no puede encontrar una extensión adecuada, puede ser que necesite crear una extensión.
  2. Estructurar sus datos de acuerdo al esquema y documentación de la extensión.
  3. Declare la extensión en el array `extensions` del paqueteutilizando la URL de la documentación de la extensión. Por ejemplo, para declarar la extensión de estadísticas y detalles de Oferta:
    {"extensions": ["https://raw.githubusercontent.com/open-contracting-extensions/ocds_bid_extension/master/extension.json"]}
  4. Revisar sus datos utilizando la Herramienta de Revisión de Datos OCDS.

Crear una extensión

Si no puede encontrar una extensión adecuada para describir los elementos que quiere publicar, puede crear una extensión.

Las extensiones pueden introducir nuevos campos, añadir códigos a listas de código abiertas e introducir reglas de validación adicionales a campos OCDS. Sin embargo, las extensiones no pueden quitar campos, cambiar el título o descripción de campos o añadir código a listas de código cerradas. Para sugerir esos cambios, abra un issue en el rastreador de issues del estándar.

También debe considerar si los datos que publica son del proceso de contrataciones o si existen independientemente del proceso. Generalmente es mejor publicar los datos que existen independientemente del proceso de contrataciones en una base de datos separada. Por ejemplo, los datos en campos sobre beneficiarios finalesde los proveedores, que usualmente se almacenan fuera de los sistemas de compras públicas.

Para crear una extensión, necesita entender el Esquema JSON y la estructura del esquema OCDS. Las extensiones son fragmentos de esquema JSON que pueden fusionarse al esquema OCDS para crear un esquema extendido.

La plantilla de extensión estándar describe la estructura y componentes de una extensión y los pasos técnicos para documentar una extensión.

Hay cinco pasos para crear una extensión:

Discusión

Antes de crear una extensión, busque las discusiones relacionadas en el rastreador de issues del estándar.

Si no puede encontrar ninguna discusión relacionada, abra un issue para describir la extensión que planea crear. La descripción del issue debe incluir:

  • El caso(s) de uso de la extensión. Describir la razón por la cuál cree que se deben añadir campos y/o código adicionales y que van a hacer los usuarios con los datos.
  • Los conceptos o procesos que quiere representar. Explicar los conceptos subyacentes descritos por la extensión y el proceso con el cuál se recolectan los datos. Incluir referencias a la legislación y otra documentación y considere proveer un diagrama.
  • Ejemplos de datos existentes. Dar ejemplos de como los datos cubiertos por la extensión se representan en sus fuentes de datos.
  • Para promover la colaboración, actualice este issue mientras desarrolla su extensión.

Desarrollo

Primero debe decidir el nombre, estructura y formato de los campos en su extensión.

Puede empezar simulando un ejemplo de los datos para los que esta creando una extensión en formato JSON. Considere:

  • ¿Cómo entran diferentes tipos de datos en esta estructura?
  • ¿Los nombres de los campos son intuitivos para los usuarios?
  • ¿Es fácil para aplicaciones consumir esta estructura?
  • Puede revisar otros estándarespara modelos potenciales. Mientras más ejemplos de fuentes de datos considere, así como diferentes casos de uso, mejor.

Antes de continuar, debe pedir retroalimentación a su simulación utilizando el issue de Github que creo en el paso anterior.

Una vez que se haya decidido en un modelo, debe de documentar el esquema para su extensión. Las siguientes herramientas están disponibles para ayudarle:

Su esquema debe seguir la guía de estilo de esquemas.

Documentar

Debe de encontrar donde alojar su extensión en línea con una URL estable. Crear un repositorio de Github para su extensión es una buena opción porque ofrece control de versiones y rastreador de issues.

También de escribir un archivo README y/o otra documentación para su extensión.

Su documentación debe incluir una descripción de la extensión y sus casos de uso, y ejemplos de datos estructurados de acuerdo a su extensión.

Prueba

Pruebe su extensión siguiendo los pasos 2-4 en Utilizar una extensión.

Registre

Lo alentamos a registrar su extensión para que otras personas puedan descubrirla utilizando el Explorador de Extensiones.

Las extensiones que solo sirven para un publicador no necesitan ser registradas.

Para regisrtar una extensión, se deben de cumplir los siguientes criterios:

  • La documentación esta en inglés. De acuerdo a la política de traducción y localización, el idioma autorizado para el estándar es inglés." De esa manera, todas las extensiones en el Explorador de Extensiones – como parte de la documentación del estándar – deben estar en inglés.
  • La documentación, incluyendo ejemplos, es más larga que 200 cáracteres. La documentación con menos de 200 caracteres no puede describir una extensión, su propósito y los detalles técnicos adecuadamente.
  • Los archivos extension.json y README.md no son exclusivos a un solo publicador. Si el nombre de la extensión o la descripción sugiere que solo es relevante para un solo publicador, es poco probable que se utilice por otros publicadores, aunque el parche del esquema sea relevante.
  • Ninguna otra extensión expresa los mismos conceptos. Tener varias maneras de expresar el mismo concepto sería contraproducente a la estandarización.
  • La extensión sigue la guía de estilo de esquemas.

Versionamiento

Las extensiones de OCDS deben de utilizar versionamiento semántico.