Guía de diseño del modelo de datos

Usar PublicSchema como referencia al diseñar el modelo de datos de un nuevo sistema, para lograr la interoperabilidad desde el inicio.

Esta guía es para equipos que construyen un nuevo sistema (un registro social, SIG, herramienta de gestión de casos o cualquier plataforma de prestación de servicios públicos) y desean que sea interoperable desde el inicio. En lugar de adaptar la compatibilidad después, diseñe su modelo de datos usando PublicSchema como referencia.

Contenido

Cuándo usar este enfoque

Este enfoque funciona bien cuando:

  • Está construyendo un nuevo sistema y desea que intercambie datos con plataformas existentes
  • Está redactando una solicitud de propuesta y necesita requisitos concretos de interoperabilidad
  • Está diseñando un modelo de datos para un programa multinacional o multisectorial
  • Está reemplazando un sistema existente y desea que el nuevo sea más fácil de integrar

No se trata de importar PublicSchema en su sistema como dependencia. Se trata de usarlo como referencia para que sus decisiones de diseño sean compatibles con el vocabulario compartido.

Qué significa "compatible"

Un modelo de datos compatible con PublicSchema:

  1. Usa los mismos conceptos. Su tabla "beneficiario" se corresponde claramente con el concepto Persona (Person) de PublicSchema, aunque internamente lo llame de otra forma.
  2. Almacena las mismas propiedades. Sus campos cubren las propiedades de PublicSchema que necesita, con tipos compatibles. Puede tener campos adicionales; eso está bien.
  3. Usa los mismos códigos de vocabulario. Donde PublicSchema define un conjunto de valores controlados (estado de inscripción, género, canal de entrega), su sistema usa los mismos códigos o puede traducirlos de forma trivial.
  4. Puede exportar en formato canónico. Dado lo anterior, su sistema puede producir exportaciones o respuestas de API que se alineen con los nombres de propiedad y los códigos de vocabulario de PublicSchema.

No necesita usar los nombres de campo exactos de PublicSchema internamente, adoptar JSON-LD ni cambiar su motor de base de datos. La compatibilidad se refiere a la alineación semántica, no a la conformidad estructural.

Paso 1: Identifique los conceptos que necesita

Explore la página de conceptos e identifique cuáles aplican a su sistema. No todos los sistemas necesitan todos los conceptos.

Un registro social típicamente necesita: Person, Household, GroupMembership, Identifier, Address, Location.

Un sistema de gestión de prestaciones podría añadir: Program, Enrollment, Entitlement, EligibilityDecision, PaymentEvent.

Un sistema de quejas añade: Grievance.

Descargue el Excel de definición para cada concepto que planee implementar. El libro de trabajo de definición incluye:

  • Metadatos del concepto (URI, dominio, nivel de madurez, definiciones en EN/FR/ES)
  • Lista completa de propiedades con tipos, cardinalidad y definiciones
  • Vocabularios de referencia con todos los códigos

Esto le proporciona un documento de referencia autocontenido para cada concepto.

Paso 2: Revise las propiedades de cada concepto

Para cada concepto, revise la lista de propiedades y decida cuáles necesita su sistema. PublicSchema es descriptivo, no normativo: todo es opcional. Adopte las propiedades que sean relevantes para su caso de uso.

Para cada propiedad que adopte, alinee en:

  • Nombre. Su nombre de campo interno puede diferir, pero documente la correspondencia. Si puede usar el nombre de PublicSchema directamente (p. ej., given_name, enrollment_status), la correspondencia es trivial.
  • Tipo. Coincida con el tipo esperado. Si PublicSchema dice date, almacene una fecha, no una cadena de texto. Si dice integer, almacene un entero.
  • Cardinalidad. PublicSchema marca las propiedades como de valor único o de valores múltiples. Si una propiedad tiene valores múltiples (p. ej., una persona puede tener varios identificadores), diseñe su esquema para soportarlo (por ejemplo, una tabla separada o un campo de tipo arreglo).

El CSV del concepto es útil como lista de verificación durante este paso.

Paso 3: Adopte los vocabularios canónicos

Para cualquier propiedad respaldada por un vocabulario (códigos de estado, género, tipos de documento, etc.), use los códigos canónicos directamente si puede. Esta es la decisión de diseño de mayor valor porque elimina la necesidad de traducción de códigos en cada integración futura.

Si debe usar códigos internos diferentes (p. ej., su base de datos usa claves numéricas enteras), mantenga una tabla de correspondencia que vincule sus códigos a los canónicos. Diseñe esta correspondencia en su sistema desde el inicio, no como algo posterior.

Consulte la Guía de adopción de vocabulario para detalles sobre cómo trabajar con los vocabularios.

Paso 4: Añada sus propios campos

Su sistema casi con certeza necesitará campos que PublicSchema no define. Eso es perfectamente normal. PublicSchema cubre el terreno común entre sistemas, no todos los campos posibles.

Al añadir campos personalizados:

  • No colisione con los nombres de propiedad de PublicSchema. Consulte la página de propiedades para asegurarse de que su nombre de campo personalizado no esté ya definido con semántica diferente.
  • Considere si el campo podría ser útil para otros. Si representa un concepto común que PublicSchema aún no cubre, podría ser candidato para una contribución. Consulte el Mecanismo de extensión para saber cómo definir propiedades personalizadas en su propio espacio de nombres.
  • Documente sus extensiones. Los futuros socios de integración necesitarán saber qué campos son canónicos y cuáles son personalizados.

Paso 5: Valide su diseño

Use los siguientes artefactos para verificar su diseño frente a PublicSchema:

  • Esquema JSON: Valide registros de muestra frente al esquema JSON del concepto. Si sus datos exportados pasan la validación, su esquema es compatible.
  • Formas SHACL: Si trabaja con RDF, los perfiles SHACL permiten la validación de restricciones para todos los conceptos.
  • Plantilla Excel: Ingrese datos de muestra en la Plantilla Excel para cada concepto. Si los datos de su sistema llenan la plantilla de forma limpia, la correspondencia es sólida. Si las columnas están vacías o los valores no encajan en las listas desplegables, investigue las brechas.

Uso de PublicSchema en la adquisición

Si está redactando una solicitud de propuesta para un nuevo sistema, PublicSchema le provee lenguaje concreto para los requisitos de interoperabilidad en lugar de aspiraciones vagas.

Ejemplo de lenguaje de requisito:

El sistema debe ser capaz de exportar registros de Persona (Person) con las siguientes propiedades según la definición de PublicSchema (publicschema.org): given_name, family_name, date_of_birth, sex, national_id. El estado de inscripción debe usar códigos del vocabulario enrollment-status de PublicSchema. El sistema debe soportar la exportación en formato CSV con los nombres de propiedad de PublicSchema como encabezados de columna.

Esto es verificable. Durante la evaluación, puede entregar a los proveedores una Plantilla Excel y pedirles que demuestren que su sistema puede producir una exportación compatible.

También puede referenciar directamente los libros de trabajo del Excel de definición en la solicitud de propuesta como especificación autorizada para cada entidad que el sistema debe soportar.

Patrones de diseño a tener en cuenta

Persona-a-Grupo es de muchos a muchos

PublicSchema modela la relación entre personas y grupos (hogares, familias, etc.) mediante un concepto GroupMembership que lleva un rol (cabeza de hogar, cónyuge, hijo, dependiente). No modele esto como una simple lista de miembros en el grupo. Una persona puede pertenecer a múltiples grupos, y el rol importa.

Los identificadores son separados de Persona

PublicSchema modela los identificadores (cédula nacional, número de pasaporte, ID de programa) como un concepto Identificador (Identifier) separado vinculado a Persona (Person), no como campos directamente sobre Persona. Esto soporta múltiples identificadores por persona y captura metadatos como la autoridad emisora y el período de validez.

La acotación temporal es un elemento central

Muchos conceptos llevan start_date y end_date. Una inscripción no es solo un estado; es una relación acotada en el tiempo. Diseñe su esquema para soportar este patrón en lugar de almacenar solo el estado actual.

Espacio de nombres de dominio

Algunos conceptos son universales (Person, Location) y otros son específicos de dominio (Enrollment está bajo protección social, /sp/Enrollment). Si está construyendo para un sector específico, verifique a qué dominio pertenecen sus conceptos. Esto afecta a los URIs pero no a cómo usa las propiedades.

Descargas disponibles

Por concepto:

Formato Qué es Mejor para
Excel de definición Libro de trabajo de múltiples hojas con metadatos, propiedades y vocabularios de referencia en EN/FR/ES Referencia principal durante el diseño del modelo de datos
Plantilla Excel Libro de trabajo de entrada de datos con validación de listas desplegables Probar compatibilidad, prototipar formularios, evaluación de adquisición
CSV Propiedades con tipos y definiciones Lista de verificación para revisión de diseño campo a campo
JSON-LD Concepto como datos enlazados Acceso legible por máquina

Por vocabulario:

Formato Qué es Mejor para
CSV Códigos con etiquetas y definiciones multilingües Carga inicial de tablas de búsqueda en su base de datos
JSON-LD Vocabulario como SKOS ConceptScheme Acceso programático

Validación:

Formato Qué es Mejor para
Esquema JSON (por concepto) Esquema JSON Draft 2020-12 Validación de registros exportados
Formas SHACL Restricciones de validación RDF Validación de datos RDF

Pasos siguientes