Metadata-Version: 2.4
Name: xsd2rdf
Version: 1.3.0
Summary: Generates OWL, SHACL shapes and SKOS concepts from XML Schema (XSD) files
License: EUPL-1.2
License-File: LICENSE
Author: Mathias Vanden Auweele
Author-email: mathias@matdata.eu
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: File Formats
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pyshacl (>0.30.0)
Requires-Dist: rdflib (>7.1.0)
Project-URL: Repository, https://gitlab.com/era-europa-eu/public/interoperable-data-programme/era-ontology/xsd2rdf
Description-Content-Type: text/markdown

# XSD2RDF

[![License](https://img.shields.io/badge/license-EUPL_1.2-blue)](http://data.europa.eu/eli/dec_impl/2017/863/oj)

A tool to convert XML Schema (XSD) files into various RDF formats (SHACL, OWL, SKOS) with integrated validation capabilities.

## Overview

XSD2RDF allows you to convert XML Schema definitions into:

- **SHACL** (Shapes Constraint Language) for RDF data validation
- **OWL** (Web Ontology Language) for ontology representation
- **SKOS** (Simple Knowledge Organization System) for concept schemes and taxonomies

## Features

- Convert XSD to SHACL, OWL, and SKOS based on integrated principles
- SHACL shape constraints are linked to SKOS concept schemes when applicable
- Handle complex XSD structures (choices, unions, complex types, enumerations, etc.)
- SHACL shapes are validated according to SHACL-SHACL

This repository also includes a validation script to check RDF data against the generated SHACL shapes and SKOS concepts.

## Current usage

This tool is currently used by [ERA](https://www.era.europa.eu/) for the purpose of generating the [telematics ontology](https://gitlab.com/era-europa-eu/public/interoperable-data-programme/era-ontology/era-telematics-ontology-pipeline) in preparation to be merged with [ERA ontology](https://gitlab.com/era-europa-eu/public/interoperable-data-programme/era-ontology/era-ontology). 

## Installation

### From PyPI

```bash
pip install xsd2rdf
```

### From Source

```bash
git clone https://github.com/YourUsername/xsd2rdf.git
cd xsd2rdf
python -m pip install poetry
poetry install
```

## Basic Usage

Convert an XSD file to all RDF formats (SHACL, OWL, SKOS):

```bash
python -m xsd2rdf -x path/to/schema.xsd
```

This generates the following files:

- `schema.xsd.shape.ttl` (SHACL shapes)
- `schema.xsd.owl.ttl` (OWL ontology)
- `schema.xsd.*.skos.ttl` (SKOS concept schemes, one file per enumeration)

## Command Line Parameters

- `-x, --XSD_FILE`: XSD file to be converted
- `-f, --FOLDER`: Folder containing non-related XSD files to be converted
- `-o, --OUTPUT_DIR`: Output directory for generated files (default: same as XSD file)
- `-a, --ABBREVIATIONS_FILE`: File containing custom abbreviations, one per line
- `-d, --debug`: Enable debug output
- `-nc, --namespaced-concepts`: Use namespaced IRIs for SKOS concepts
- `-un, --use-namespace`: Override the XSD targetNamespace for generated SHACL, OWL and SKOS resources
- `-ssv, --skipShaclValidation`: Skip SHACL-SHACL validation
- `-pkqi, --property-kind-qualified-iris`: Append `DP` or `OP` to every property IRI according to its OWL property kind

Either -x or -f must be specified, but not both. If both are specified, -x takes precedence.

### SKOS IRI Options

By default, SKOS concept IRIs are created using a flat structure:

```
targetnamespace/concepts/conceptschemename_conceptname
```

With the `--namespaced-concepts` flag, concepts use a hierarchical structure:

```
targetnamespace/concepts/conceptschemename/conceptname
```

## Release new version CI/CD

The CI/CD script will automatically push a new version of the library to PyPi when a new Gitlab tag is created. As the tag name, use semantic versioning with 3 digits, examples: `v1.2.3`. 

For user's convenience, best also add human readable release notes.

## Examples

With custom output directory:

```bash
python -m xsd2rdf  -x path/to/schema.xsd -o output/directory
```

With folder containing multiple unrelated XSD files:

```bash
python -m xsd2rdf -f path/to/folder
```

Using a custom abbreviations file:

```bash
python -m xsd2rdf -x path/to/schema.xsd -a path/to/abbreviations.txt
```

A practical way to generate a list of abbreviations on a Windows machine using Powershell is with this command:

```powershell
 Select-String -Path "c:\Users\mathi\Git\era\xsd2rdf\debug\SFERA_v3.00.xsd" -Pattern "\b[A-Z]{2,}\b" -AllMatches | ForEach-Object { $_.Matches } | ForEach-Object { $_.Value } | Where-Object { $_ -cmatch "^[A-Z]{2,}$" } | Sort-Object -Unique | Where-Object { $_.Length -ge 2 -and $_.Length -le 10 }
```

Using namespaced concept IRIs:

```bash
python -m xsd2rdf -x path/to/schema.xsd --namespaced-concepts
```

The abbreviations file should contain one abbreviation per line. These abbreviations will be preserved as uppercase when creating human-readable labels from camelCase or PascalCase strings.

Using a custom namespace instead of the XSD targetNamespace:

```bash
python -m xsd2rdf -x path/to/schema.xsd --use-namespace http://data.europa.eu/949/
```

Skipping SHACL-SHACL validation:

```bash
python -m xsd2rdf -x path/to/schema.xsd -ssv
```

### Property-kind-qualified IRIs

Use `--property-kind-qualified-iris` to give every generated property IRI an
explicit suffix based on its OWL property kind:

- datatype properties receive the `DP` suffix;
- object properties receive the `OP` suffix.

This is a global opt-in mode. It changes all generated property IRIs, not only
IRIs that would otherwise be used as both datatype and object properties. The
default mode remains unchanged for backwards compatibility.

For example, consider two complex types that both use an `author` element in 
the same xsd file, but with a different structure. A `Book` has an author name 
(simple string), while an `Article` references an author as a complete person object:

```xml
<xsd:complexType name="Book">
  <xsd:sequence>
    <xsd:element name="title" type="xsd:string"/>
    <xsd:element name="author" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="Article">
  <xsd:sequence>
    <xsd:element name="title" type="xsd:string"/>
    <xsd:element name="author" type="PersonType"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="PersonType">
  <xsd:sequence>
    <xsd:element name="firstName" type="xsd:string"/>
    <xsd:element name="lastName" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>
```

With property-kind qualification enabled, their SHACL paths and OWL property
IRIs are distinct:

```turtle
sh:path ex:authorDP .
ex:authorDP a owl:DatatypeProperty .

sh:path ex:authorOP .
ex:authorOP a owl:ObjectProperty .
```

Enable the mode with:

```bash
python -m xsd2rdf \
  -x path/to/schema.xsd \
  --property-kind-qualified-iris
```

## Development validation

This feature is only available from source as it is meant for development purposes.

Prerequisites:

- Create sample data for validation `schema.xsd.shape.ttl` in the same directory as the xsd file

To validate RDF data against SHACL shapes with SKOS concepts:

```bash
python shacl-validation.py path/to/schema.xsd
```

This result will:

1. Load the data from `schema.xsd.sample.ttl`
2. Include all related SKOS files (`schema.xsd.*.skos.ttl`)
3. Perform validation using the generated SHACL shapes (`schema.xsd.shape.ttl`)
4. Report results in the command line

## Wiki Pages

Some [wiki pages](https://gitlab.com/era-europa-eu/public/interoperable-data-programme/era-ontology/xsd2rdf/-/wikis/home) explain the inner workings of the convertor and the list of 
mapping rules implemented within the tool.

## License

[EUPL 1.2](http://data.europa.eu/eli/dec_impl/2017/863/oj)

