Automatización de convenciones y propuesta de ontologías DCAT-AP-ES

[mjanez]

Objetivo

Note

Rama de trabajo: feature/dcatapes-consolidated-context

Automatización de convenciones y propuesta de ontologías DCAT-AP-ES

Publicar formalmente las ontologías RDF que describen el perfil DCAT-AP-ES y sus convenciones, estableciendo un pipeline de automatización que garantice la alineación entre todos los artefactos del proyecto:

• Automatización de alineación: Establecer docs/conventions.md como fuente única de verdad, generando automáticamente:
  • Contexto JSON-LD (context.jsonld)
  • Documentación AsciiDoc para PDF (docs/adoc/)
  • Reglas SHACL (shacl/1.0.0/)
  • Documentación MkDocs (sincronizada)
• URIs dereferenciables con negociación de contenido (RDF/HTML)
• Ontologías formales para DCAT-AP-ES y sus convenciones
• Alineación completa de namespaces en todo el proyecto

Dependencias

• Cerrar Issue Convención - Definir convenciones sobre esquema de URIs #26: Definición de esquema de URIs para DCAT-AP-ES

---

Fase 1: Definición de URIs (Prerequisito)

1.1 Decisión de namespaces definitivos

Actualmente existen tres namespaces inconsistentes:

Ubicación	Namespace actual	Problema
SHACL (12 archivos)	https://datosgobes.github.io/DCAT-AP-ES/#	URI de desarrollo, no persistente
Ontologías (TTL)	https://datos.gob.es/def/dcat-ap-es#	Usa https
JSON-LD Context	http://datos.gob.es/def/dcat-ap-es#	Usa http

Propuesta según NTI-RISP:

# Ontología base DCAT-AP-ES (vocabulario)
@prefix dcatapes: <http://datos.gob.es/def/dcat-ap-es#> .

# Ontología de convenciones (subdominio del vocabulario)
@prefix dcatapesconv: <http://datos.gob.es/def/dcat-ap-es/convenciones#> .

Justificación:

• http:// según práctica común de URIs semánticos (redirección a HTTPS transparente)
• def/ indica vocabulario/ontología (NTI-RISP 6.1.2.2)
• dcat-ap-es como dominio específico
• # para identificadores de fragmento

Tareas:

• Confirmar uso de http:// vs https:// para URIs semánticos
• Decidir si usar / o # para conceptos
• Documentar decisión en Issue Convención - Definir convenciones sobre esquema de URIs #26 y cerrar

---

Fase 2: Diseño de Ontologías

2.1 Ontología base DCAT-AP-ES

Archivo: context/ontology/dcatapes.ttl

Tareas:

• Completar modelo de propiedades del perfil
• Añadir metadatos de ontología (owl:imports, dct:license, etc.)
• Definir alineamientos con DCAT-AP y DCAT
• Validar sintaxis con herramienta RDF

2.2 Ontología de Convenciones

Archivo: context/ontology/dcatapesconv.ttl

Tareas:

• Completar todas las convenciones como individuos RDF (actualmente en borrador solo 11, 12)
• Añadir foaf:page con enlace a documentación
• Añadir skos:example con ejemplos de uso
• Vincular con formas SHACL correspondientes

---

Fase 3: Contexto JSON-LD

Archivo: context/dcat-ap-es-context.jsonld

Tareas:

• Actualizar namespace dcatapes a URI definitivo
• Añadir namespace dcatapesconv
• Añadir términos de las ontologías al contexto
• Validar contexto con JSON-LD Playground
• Crear contexto separado para convenciones

---

Fase 4: Alineación de Namespaces

4.1 Archivos SHACL (12 archivos)

Cambio requerido en todos los archivos:

# Antes
@prefix dcatapes: <https://datosgobes.github.io/DCAT-AP-ES/#> .

# Después  
@prefix dcatapes: <http://datos.gob.es/def/dcat-ap-es#> .

Archivos:

• shacl/1.0.0/shacl_catalog_shape.ttl
• shacl/1.0.0/shacl_common_shapes.ttl
• shacl/1.0.0/shacl_dataservice_shape.ttl
• shacl/1.0.0/shacl_dataset_shape.ttl
• shacl/1.0.0/shacl_distribution_shape.ttl
• shacl/1.0.0/shacl_imports.ttl
• shacl/1.0.0/shacl_mdr_imports.ttl
• shacl/1.0.0/shacl_mdr-vocabularies.shape.ttl
• shacl/1.0.0/hvd/shacl_common_hvd_shapes.ttl
• shacl/1.0.0/hvd/shacl_dataservice_hvd_shape.ttl
• shacl/1.0.0/hvd/shacl_dataset_hvd_shape.ttl
• shacl/1.0.0/hvd/shacl_distribution_hvd_shape.ttl

4.2 Otros archivos

• Ontologías en context/ontology/*.ttl
• Contexto JSON-LD
• Ejemplos en examples/ si usan dcatapes:

---

Fase 5: Documentación MkDocs

5.1 Nueva página de ontología

Crear: docs/ontology.md y docs/ontology.en.md

Note

Borrador: docs/draft-ontologies.md

Contenido:

• Introducción a la ontología DCAT-AP-ES
• Relación con el perfil de metadatos (index.md)
• Clases principales y propiedades
• Uso del contexto JSON-LD
• Ejemplos

Tareas:

• Crear docs/ontology.md
• Crear docs/ontology.en.md
• Añadir entrada en mkdocs.yml nav
• Actualizar context/README.md

5.2 Actualización de convenciones

• Añadir sección de ontología en docs/conventions.md
• Enlazar cada convención con su URI RDF

---

Fase 6: Infraestructura de Publicación

6.1 Negociación de contenido

Para URIs dereferenciables:

GET http://datos.gob.es/def/dcat-ap-es
Accept: text/turtle        → dcatapes.ttl
Accept: application/ld+json → dcat-ap-es-context.jsonld
Accept: text/html          → https://datosgobes.github.io/DCAT-AP-ES/ontology/

Tareas:

• Coordinar redirecciones
• Configurar reglas de proxy/htaccess
• Probar negociación de contenido

6.2 Registro en LOV

• Preparar metadatos para Linked Open Vocabularies
• Enviar solicitud de registro

---

Fase 7: Automatización del Pipeline

7.1 Generación automática del Contexto JSON-LD y SHACL

Evitar duplicar trabajo manual manteniendo una fuente única de conocimiento:

flowchart LR
  A["docs/conventions.md<br>(fuente primaria)"] --> B["context.jsonld<br>(auto-generado)"]
  A --> D["shacl/1.0.0/*.ttl<br>(esqueleto básico)"]
  B --> C["docs/adoc/*.adoc<br>(para PDF)"]

Loading

Enfoque propuesto:

1. Fuente primaria: docs/conventions.md con metadatos estructurados (YAML frontmatter o tablas parseables)
2. Script de sincronización: tools/sync-context.py
   • Parsea convenciones desde Markdown
   • Actualiza dcatapesconv.ttl con individuos RDF
   • Regenera dcat-ap-es-context.jsonld
   • Genera reglas SHACL básicas para cada convención (severidad, mensaje, target)
3. Hook de MkDocs: Ejecutar en on_pre_build para mantener sincronía

Generación de SHACL:

Al crear o modificar una convención que incluya warning o error, se genera automáticamente un esqueleto de regla SHACL con:

• sh:severity sh:Warning o sh:Violation según tipo
• sh:message con descripción de la convención
• sh:targetClass o sh:targetNode según aplique
• Estructura básica de sh:property o sh:node

Este esqueleto forzará fallos de validación hasta que se complete el diseño específico de la regla, garantizando que todas las convenciones tengan su contrapartida SHACL implementada.

Tareas:

• Definir formato estructurado para convenciones en Markdown (YAML/tabla con tipo severity)
• Crear script tools/sync-context.py para generar ontología, contexto y SHACL
• Implementar plantillas de esqueleto SHACL para warning/error
• Integrar en hook de MkDocs (tools/mkdocs-hooks/)
• Añadir validación automática post-generación que detecte reglas incompletas

7.2 Generación automática de AsciiDoc para PDF

Generar la documentación PDF a partir del contexto consolidado:

Flujo propuesto:

flowchart LR
  A["context.jsonld"] --> B["tools/context2adoc.py"] --> C["docs/adoc/resources/context-tables.adoc"]

Loading

Contenido generado:

• Tablas de entidades con propiedades y cardinalidades
• Listado de convenciones con descripciones
• Vocabularios controlados referenciados

Tareas:

• Crear script tools/context2adoc.py
• Definir plantillas AsciiDoc para tablas de propiedades
• Integrar en pipeline de generación de PDF
• Documentar proceso en docs/adoc/README.md

7.3 CI/CD Pipeline

Automatizar en GitHub Actions:

# .github/workflows/sync-context.yml
on:
  push:
    paths:
      - 'docs/conventions.md'
      - 'docs/conventions.en.md'

jobs:
  sync:
    steps:
      - run: python tools/sync-context.py
      - run: python tools/context2adoc.py
      - run: ./tests/validate-local.sh  # Debe fallar si hay SHACL incompleto

Validación de esqueletos SHACL:

El pipeline CI/CD debe detectar reglas SHACL generadas pero no implementadas (esqueletos) y reportar error, obligando a:

1. Completar la lógica de validación (path, constraints)
2. Añadir tests específicos con ejemplos válidos/inválidos
3. Documentar la regla en comentarios SHACL

Tareas:

• Crear workflow de sincronización
• Añadir tests de validación automática
• Implementar detección de reglas SHACL incompletas
• Configurar commit automático de artefactos generados (opcional)

---

Fase 8: Validación y Testing

• Validar sintaxis Turtle con rapper/riot
• Validar consistencia OWL
• Validar contexto en JSON-LD Playground
• Ejecutar tests/validate-local.sh tras cambios
• Verificar que ejemplos siguen siendo válidos

---

Referencias

• NTI-RISP - Esquema de URIs (PDF)
• DCAT-AP-ES Convenciones
• Issue #26 - Esquema de URIs
• W3C JSON-LD 1.1
• Linked Open Vocabularies (LOV)