SDF-WoT-Converter (Python Edition)

This repository provides a Python-based converter from SDF to WoT TD including Thing Models.

The converter is both usable as a library and a command line tool. It is based on my Rust implementation but is (when it comes to the conversion from SDF to Thing Models) already more mature as development in Python turned out to be much faster. The final version of this converter, however, will be reimplemented in Rust once it is finished to also support more constrained environments.

The CI pipeline is set up to automatically convert all (valid) models from the oneDM playground to WoT Thing Models and upload to the results to this repository.

Installation

You can install the converter using pip:

pip install sdf-wot-converter

Afterwards, it can be used both as a command line tool and a library.

Using the command line tool

After installing the libary you should be able to call the converter in your terminal using sdf-wot-converter. You can display available parameters by typing sdf-wot-converter --help. So far, you can convert from SDF to WoT Thing Models and vice versa. Thing Descriptions are supposed to be added soon.

Example

# Convert an SDF model to a WoT Thing Model
sdf-wot-converter --from-sdf examples/sdf/example.sdf.json --to-tm converted-example.tm.jsonld

# Convert a WoT Thing Model to an SDF model
sdf-wot-converter --from-tm examples/wot/example.tm.jsonld --to-sdf converted-example.sdf.json

Using the library

With the converter installed, you can use also use it as a library in your own projects. Below you can see examples for how to convert an SDF model to a WoT Thing Model and back again. As you can see, nested definitions from sdfObjects or sdfThings a prefixed with the respective object or thing names. Moreover, an sdf:jsonPointer field is added to each affordance to enable roundtripping. More detailed mapping tables will be added to this readme soon.

from sdf_wot_converter.converters import (
    sdf_to_wot,
    wot_to_sdf,
)

sdf_model = {
    "info": {
        "title": "Example file for OneDM Semantic Definition Format",
        "version": "2019-04-24",
        "copyright": "Copyright 2019 Example Corp. All rights reserved.",
        "license": "https://example.com/license",
    },
    "namespace": {"cap": "https://example.com/capability/cap"},
    "defaultNamespace": "cap",
    "sdfObject": {
        "Switch": {
            "sdfProperty": {
                "value": {
                    "description": "The state of the switch; false for off and true for on.",
                    "type": "boolean",
                }
            },
            "sdfAction": {
                "on": {
                    "description": "Turn the switch on; equivalent to setting value to true."
                },
                "off": {
                    "description": "Turn the switch off; equivalent to setting value to false."
                },
                "toggle": {
                    "description": "Toggle the switch; equivalent to setting value to its complement."
                },
            },
        }
    },
}

thing_model = sdf_to_wot.convert_sdf_to_wot_tm(sdf_model)

expected_thing_model = {
    "@context": [
        "https://www.w3.org/2022/wot/td/v1.1",
        {
            "cap": "https://example.com/capability/cap",
            "sdf": "https://example.com/sdf",
        },
    ],
    "@type": "tm:ThingModel",
    "sdf:title": "Example file for OneDM Semantic Definition Format",
    "sdf:copyright": "Copyright 2019 Example Corp. All rights reserved.",
    "links": [{"href": "https://example.com/license", "rel": "license"}],
    "version": {"model": "2019-04-24"},
    "sdf:defaultNamespace": "cap",
    "actions": {
        "on": {
            "description": "Turn the switch on; equivalent to setting value to true.",
        },
        "off": {
            "description": "Turn the switch off; equivalent to setting value to false.",
        },
        "toggle": {
            "description": "Toggle the switch; equivalent to setting value to its complement.",
        },
    },
    "properties": {
        "value": {
            "description": "The state of the switch; false for off and true for on.",
            "type": "boolean",
        }
    },
    "sdf:objectKey": "Switch",
}

assert thing_model == expected_thing_model

sdf_roundtrip_model = wot_to_sdf.convert_wot_tm_to_sdf(thing_model)

assert sdf_model == sdf_roundtrip_model

License

This project is licensed under the MIT license.

SPDX-License-Identifier: MIT