Características del editor de esquemas

El Editor de esquemas proporciona funcionalidad para incrustar información de metadatos semánticos en el esquema OpenAPI/JSON de la API. Dos funciones clave son la posibilidad de configurar el punto final SPARQL, que luego es útil para consultar recursos de tipo RDF, y la activación de la finalización automática de términos y clases.

Configurar el punto final de SPARQL

El Editor de esquemas consulta recursos externos utilizando SPARQL, un lenguaje diseñado para consultar conjuntos de datos RDF.
De forma predeterminada, el editor utiliza el punto final SPARQL del Catálogo. Sin embargo, puede cambiarlo para conectarse a un servidor SPARQL diferente, útil, por ejemplo, cuando se trabaja con conjuntos de datos personalizados o infraestructuras RDF distribuidas. Para ello, haga clic en el icono de la hamburguesa (≡) situado en la esquina superior izquierda de la interfaz.

Para cambiar el punto final de SPARQL:

  • Haga clic en el icono de la hamburguesa (≡) en la esquina superior izquierda de la interfaz.
  • Seleccione el elemento Configuración en el menú lateral.
  • Introduzca la URL del nuevo punto final SPARQL en el campo dedicado.

Una vez guardada la configuración, el editor utilizará el nuevo punto final para todas las consultas.

Imagen descriptiva que finaliza la configuración del punto final de SparQL.

Usar autocompletar

El editor de esquemas puede sugerir automáticamente términos y clases al escribir, según un conjunto seleccionado de vocabularios disponibles en el catálogo de schema.gov.it. Para usar la autocompletación:

  • Presionando la combinación CTRL + ESPACIO Se abrirá una menú desplegable con una lista de sugerencias compatibles;
  • Al escribir en texto, la lista se filtrará dinámicamente;
  • Prensado ENVIAR en una sugerencia, el editor completará automáticamente el campo con elURI correcto para la clase o propiedad seleccionada.

Esta funcionalidad simplifica enormemente la inserción de referencias correctas y reduce el riesgo de errores de sintaxis o URI no válidos.

Imagen descriptiva de la operación de auto-completación.

La sección Modelos de datos del Editor de esquemas proporciona una visión general estructurada de todas las clases RDF definidas en el esquema. Está diseñado para facilitar el análisis de las propiedades asociadas a cada clase y sus vínculos semánticos.

Principales funcionalidades

  1. Visualización automática de las clases RDF El editor recupera automáticamente todas las clases RDF del esquema. Para cada clase, se enumeran los siguientes:
    • Las propiedades asociadas;
    • Enlaces semánticos resultantes de mapeos con clases de referencia.
  2. Detalles de cada propiedad Cada propiedad mostrada se enriquece con información útil para entender el modelo:
    • Tipo sintáctico (por ejemplo, cadena, número, objeto);
    • Tipo semántico (URI RDF asociado);
    • Descripción textual;
    • Ejemplo de uso, generado de acuerdo con las definiciones de esquema.
  3. OntoScore Calculation – Semantic Coverage Indicator El editor de esquemas calcula un indicador llamado OntoScore, que mide el nivel de mapeo semántico del esquema. Se define como la relación entre el número total de propiedades presentes en el esquema JSON y el número de propiedades correctamente asignadas con un rdf:Property. Esta puntuación ayuda a evaluar cuán semánticamente alineado está el esquema con los vocabularios RDF.
  4. Cuando una clase está vinculada a un vocabulario controlado, aparece el botón "Mostrar valores". Al hacer clic en él, va directamente a la sección correspondiente en schema.gov.it, donde se enumeran todos los valores permitidos para esa propiedad.

 

Imagen descriptiva de la sección Modelos de datos con sus características.

 

Navegación de herramientas de análisis

Esta sección del Editor de esquemas recopila un conjunto de herramientas diseñadas para el análisis semántico, la visualización RDF y la validación de compatibilidad JSON-LD. A través de diferentes paneles interactivos, es posible explorar la estructura del esquema, comprender su significado semántico y verificar su comportamiento en contextos reales de RDF.

Usar JSON-LD Playground

El Editor de esquemas le permite generar automáticamente un ejemplo y abrirlo en la herramienta externa JSON-LD Playground. Esta función le permite:

  • Mostrar la entrada JSON producida por el esquema;
  • Examinar el contexto JSON-LD y su @type;
  • Obtenga una serialización RDF en los formatos Turtle, RDF/XML y N-Quads.

Esta herramienta es útil para probar la exactitud de la representación semántica de los datos.

Imagen descriptiva del análisis semántico con JSON-LD Playground.

 

Usa trillizos de RDF

La sección RDF muestra la información del esquema en trillizos RDF (en la forma sujeto – predicado – objeto), proporcionando una representación clara de la estructura semántica. Esta vista le permite:

  • Explorar visualmente las relaciones semánticas entre entidades y propiedades;
  • Verificar la consistencia del modelo con el gráfico RDF;
  • Comprender cómo se interpretarán las instancias de esquema en los sistemas semánticos

Imagen descriptiva de trillizos RDF.

Usar el contexto JSON-LD

El contenido de la sección JSON-LD Context se genera automáticamente a partir de los metadatos (x-jsonld-type y x-jsonld-context) en el esquema. Entre las principales características:

  • Respeta la jerarquía del régimen, manteniendo un contexto coherente;
  • Aplicar la herencia de contexto automática a los niveles de hijos, a menos que se especifique lo contrario;
  • Genera salidas que cumplen con las especificaciones JSON-LD, listas para ser integradas en sistemas basados en ontologías RDF.

Este panel es clave para garantizar la integración semántica efectiva y la publicación de datos interoperables.

Imagen descriptiva de la sección Contexto JSON-LD.

 

Usar el menú de acción

El menú de acción del editor de esquemas proporciona acceso rápido a varias funciones útiles para administrar, exportar y compartir esquemas semánticos.
Se puede acceder a través de un botón dedicado ubicado en la interfaz principal del editor.

Principales funcionalidades

  1. Crear una nueva plantilla Puede generar una plantilla básica que contenga una sola clase de ejemplo: Persona, con las propiedades givenName y familyName. Este modelo básico se puede utilizar para:
    • Explorar la estructura y la lógica del sistema;
    • Añadir fácilmente nuevas clases y propiedades;
    • Empezar a definir un esquema personalizado, por ejemplo, un modelo semántico de «Persona» con clases ontológicas relacionadas.
  2. El esquema actualmente en uso se puede descargar en varios formatos:
    • Formato nativo («tal cual»), útil para la reutilización directa en el editor de esquemas;
    • Formato JSON, adecuado para su integración en sistemas externos o procesamiento posterior. 
  3. Compartiendo el esquema
    Una opción está disponible para copiar el esquema como una URL, lo que permite compartir rápida y fácilmente con otros usuarios o herramientas. Este enlace muestra una representación persistente del esquema, listo para ser abierto en el mismo editor o en entornos compatibles.
  4. Abrir el esquema en una instancia remota
    El mismo esquema se puede abrir dentro de una instancia remota previamente configurada del Editor de esquemas (por ejemplo, en una aplicación de terceros o un entorno personalizado). Esta función es particularmente útil en contextos donde el editor está integrado en un sistema de gestión, un portal de documentos o un entorno de desarrollo semántico dedicado.

Imagen descriptiva del menú Acción.

 

Consulte al ayudante de RDF

El RDF Ontological Class Helper es una herramienta integrada en el Editor de esquemas diseñada para apoyar a los usuarios en el diseño semántico avanzado de esquemas.
Esta característica ayuda a explorar las propiedades RDF asociadas con una clase semántica específica, facilitando el mapeo adecuado de las propiedades y mejorando la calidad semántica general del esquema.

  1. La herramienta realiza automáticamente una consulta SPARQL en la clase semántica indicada en el campo de tipo x-jsonld del esquema.
  2. Se recuperan todos los rdf:Properties asociados con la clase, con detalles útiles para cada propiedad, incluyendo:
    • rdfs:rango: indica el tipo de valor esperado (p. ej. Literal, URI, etc.);
    • rdfs:comentario: proporcionar una descripción textual de la propiedad;
    • Ejemplo de uso: ayuda a entender cómo integrar correctamente la propiedad en el esquema.

Las propiedades identificadas se insertan en un panel interactivo, desde el cual el usuario puede analizarlas y decidir si las integra o no en su modelo.
Esta herramienta es particularmente útil para ampliar la cobertura semántica del esquema, garantizar la alineación adecuada con los vocabularios RDF estándar, reutilizar las propiedades existentes, reducir la redundancia y fomentar la interoperabilidad semántica.

Imagen descriptiva del uso de RDF Helper

Preguntas frecuentes

Para guardar el esquema de datos creado, debe ir a la sección Modelos de datos, hacer clic en el Menú de acción y elegir si desea guardar el enlace mediante Copiar como URL y guardar el enlace en un documento de texto; o guarde el esquema de datos en formato .yaml.

Hay dos posibilidades:

  • Abra el archivo en formato .yaml, copie el texto y péguelo en el Editor de esquemas.
  • Recupera la URL previamente guardada y cópiala en el navegador;

Para asociar el valor de la propiedad JSON Schema con el vocabulario controlado, precede al valor de @base, como se indica en el código de ejemplo que se puede consultar en la ventana que se abre haciendo clic en (?) desde el Ayudante RDF.

Si después de hacer una búsqueda exhaustiva en todas las propiedades de la clase y sus superclases no puede encontrar una propiedad, es posible que no esté presente en el Catálogo. Haga una búsqueda más detallada directamente en el Catálogo accediendo a la máscara de búsqueda schema.gov.it. Si no encuentra el recurso semántico correspondiente a la variable de esquema, puede escribirlo sin mejorarlo con el URI, pero se recomienda describirlo en detalle con la propiedad description. Esto bajará el OntoScore.