jkrhb / sdf-wot-converter-py

Python-based converter between WoT TD and SDF (including protocol bindings).

SDF-WoT-Converter

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 provides conversion functions between WoT Thing Descriptions, WoT Thing Models and SDF Models (one for each combination). You can find a number of examples for the usage of the converter down below as well as overviews for the conversion between SDF and WoT TMs.

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 and one of the six available subcommands:

• sdf-to-tm
• sdf-to-td
• td-to-tm
• td-to-sdf
• tm-to-td
• tm-to-sdf

You can display available parameters by typing sdf-wot-converter --help. A usage example for each subcommand can be found below.

Examples

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

# Convert an SDF model to a WoT Thing Description
sdf-wot-converter sdf-to-td -i examples/sdf/example.sdf.json --mapping-files examples/sdf/example.sdf-mapping.json -o converted-example.td.jsonld

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

# Convert a WoT Thing Model to a WoT Thing Description
sdf-wot-converter tm-to-td -i examples/wot/example-with-bindings.tm.jsonld -o converted-example.td.jsonld

# Convert a WoT Thing Description to an SDF model and a mapping file
sdf-wot-converter td-to-sdf -i examples/wot/example.td.jsonld -o converted-example.sdf.json --mapping-file-output converted-example.sdf-mapping.json

# Convert a WoT Thing Description to a WoT Thing Model
sdf-wot-converter td-to-tm -i examples/wot/example.td.jsonld -o converted-example.tm.jsonld

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 are prefixed with the respective object or thing names.

from sdf_wot_converter import (
    convert_sdf_to_wot_tm,
    convert_wot_tm_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",
                    "observable": False,
                }
            },
            "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 = 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",
            "observable": False,
        }
    },
    "sdf:objectKey": "Switch",
}

assert thing_model == expected_thing_model

sdf_roundtrip_model = convert_wot_tm_to_sdf(thing_model)

assert sdf_model == sdf_roundtrip_model

Mappings Overview

SDF to WoT

Below you can find a mapping of the most important keywords of SDF to WoT. We use Thing Models (TMs) as a reference here, as they are most similar to SDF models. When converting from SDF to WoT TD, the SDF model (and a mapping file which must provide the necessary instance-specific information) is first converted to a TM, which is in turn converted to a TD.

SDF Keyword	WoT Class/Keyword
sdfThing	TM with tm:submodel links
sdfObject	TM without tm:submodel links
sdfProperty	PropertyAffordance
writable	readOnly (negated)
readable	writeOnly (negated)
sdfAction	ActionAffordance
sdfInputData	input
sdfOutputData	output
sdfEvent	EventAffordance
sdfOutputData	output
sdfData	schemaDefinitions (at the Thing level)
sdfRef	tm:ref
sdfChoice	Enum of JSON objects with an (additional) sdf:choiceName
sdfRequired	tm:required
namespaces	@context
defaultNamespace	sdf:defaultNamespace
Info Block	Multiple targets
version	model field in the Version class
title	sdf:title
copyright	sdf:copyright
license	link with relation-type license (if license value is a URL) or sdf:license

WoT to SDF

Below you can find a mapping of some of the most important classes and keywords from WoT to SDF. Note that there are still some definitions missing in the table that are already covered by the converter implementation.

WoT TD definitions which are not covered by the core SDF vocabulary are mapped to a so-called SDF mapping file (see draft-bormann-asdf-sdf-mapping).

WoT Class/Keyword	SDF Keyword
Thing	sdfThing (if TM has tm:submodel links), sdfObject
title	label
description	description
schemaDefinitions	sdfData
@context	namespaces of the SDF model (with exceptions)
DataSchema	dataqualities
readOnly	Mapping File
writeOnly	Mapping File
InteractionAffordance	(Common Qualities)
title	label
description	description
PropertyAffordance	sdfProperty
readOnly	writable (negated)
writeOnly	readable (negated)
observable	observable (negated)
ActionAffordance	sdfAction
input	sdfInputData
output	sdfOutputData
EventAffordance	sdfEvent
output	sdfOutputData
subscription	Mapping File
cancellation	Mapping File
dataResponse	Mapping File
tm:ref	sdfRef
tm:required	sdfRequired
Link	Mapping File, except for special link types (license, tm:extends, tm:submodel)

License

This project is licensed under the MIT license.

SPDX-License-Identifier: MIT

sdf-wot-converter-py's Issues

Fix mapping of `sdfInputData` and `sdfOutputData`

Add option for suppressing SDF roundtripping definitions in TMs/TDs

Fix mapping of exclusiveMinimum/exclusiveMaximum to SDF

In SDF, the two qualities can be boolean, in WoT, however, this is not allowed.

Apply updates to TM schema

At the moment, the TM schema is broken in a couple of aspects. Once a new schema has been published, the current version should be updated.

Move observable from dataqualities to properties

Since the merge of ietf-wg-asdf/SDF#55, mapping observable from dataqualities is no longer necessary.

sdf-wot-converter-py/sdf_wot_converter/converters/sdf_to_wot.py

Lines 267 to 271 in 759d389

	def map_observable(data_qualities, data_schema, is_property):
	if is_property:
	map_field(data_qualities, data_schema, "observable", "observable")
	else:
	map_field(data_qualities, data_schema, "observable", "sdf:observable")

Update WoT TD @context

Make mapping files mandatory for SDF to TD conversion?

As WoT TDs have a number of mandatory fields (like forms on the affordance level or securityDefinitions), it should be considered turning mapping files into a mandatory argument for the respective conversion function.

Update playground conversion workflow for PRs

At the moment, the conversion workflow seems to use the latest package version for conversions of onedm playground models instead of the current codebase. This should be addressed to actually see the effects of changes to the converter.

Support Top-Level Detection in TM Thing Collections

Make it possible to detect top-level TMs/TDs in Thing Collections

• #49
• Add TD Thing Collection as a feature
• Support Top-Level Detection in TD Thing Collections

Refactor mapping of writeOnly and readOnly

This conversion could be moved to its own function:

sdf-wot-converter-py/sdf_wot_converter/converters/sdf_to_wot.py

Lines 217 to 219 in 759d389

	for sdf_field, wot_field in [("writable", "readOnly"), ("readable", "writeOnly")]:
	if sdf_field in data_qualities:
	data_schema[wot_field] = not data_qualities[sdf_field]

Fix mapping of @type field

WoT's @type is currently not mapped correctly.

Map `contentEncoding` field

contentEncoding currently does not seem mappable from WoT to SDF, therefore a workaround has to be found for this field.

Add mapping file support