Metadata-Version: 2.4
Name: xsd2rdf
Version: 1.5.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
- `-n, --namespaced-concepts`: Use namespaced IRIs for SKOS concepts
- `-u, --namespace`: Override the XSD targetNamespace for generated SHACL, OWL and SKOS resources
- `-p, --has-prefix-for-properties`: Add `has` as a prefix for generated property IRIs
- `-s, --skip-shacl-validation`: Skip SHACL-SHACL validation
- `-k, --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.

### abbreviations-file

Provide a custom abbreviations file to preserve domain-specific acronyms when labels are generated from camelCase or PascalCase names.

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

Effect on output:

- Labels and human-readable names keep the listed abbreviations in uppercase.
- Generated SHACL, OWL, and SKOS resources use the same IRIs as before, but the textual labels become more accurate.

### debug

Enable verbose logging while converting schemas.

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

Effect on output:

- Prints additional conversion details to the console.
- Does not change the generated SHACL, OWL, or SKOS files.

### namespaced-concepts

Generate SKOS concept IRIs in a hierarchical structure instead of a flat one.

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

Effect on output:

- SKOS concepts become `targetnamespace/concepts/conceptschemename/conceptname` instead of `targetnamespace/concepts/conceptschemename_conceptname`.
- The generated SKOS files still represent the same concepts, but the IRIs are easier to group by concept scheme.

### namespace

Override the XSD target namespace used for generated RDF resources.

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

Effect on output:

- SHACL, OWL, and SKOS IRIs are emitted under the provided namespace instead of the schema target namespace.
- This is useful when generated resources must align with an existing vocabulary namespace.

### has-prefix-for-properties

Add `has` as a prefix to generated property IRIs.

```bash
python -m xsd2rdf -x path/to/schema.xsd --has-prefix-for-properties
```

Effect on output:

- Property IRIs are prefixed with `has` where applicable.
- The change applies to generated SHACL paths and OWL property IRIs, making property names more explicit.

### skip-shacl-validation

Skip the SHACL-SHACL validation step during generation.

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

Effect on output:

- The SHACL validation phase is not run.
- Generation completes faster, but invalid SHACL output is not checked before files are written.

### property-kind-qualified-iris

Append a property-kind suffix to every generated property IRI so datatype and object properties remain distinct.

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

Effect on output:

- Datatype properties receive the `DP` suffix and object properties receive the `OP` suffix.
- SHACL paths and OWL property IRIs no longer collide when the same local name is used for different property kinds.

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 .
```

## 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.

## 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)

