Repository navigation
Bidirectional OO-LD <-> k-type converter #113
Description
Convert between OO-LD schemas and k-type specifications.
A k-type is the template defining structure, semantics and relations of Knowledge Items (k-items). The specs live in https://github.com/semantic-dataspace/knowledge-types as self-contained YAML, and are referenced from https://github.com/semantic-dataspace/semantic-schemas via x-ktype.
cc @yoavnash @Kirankumaraswamy @durmaz07
Mapping
k-type spec to OO-LD schema:
ontology_classes[].irito the semantic type, i.e. the@contexttype entry and thetypeconstcustom_properties.sections[].inputs[]to schema properties;relation_mapping.iriandrelation_mapping.type(data_propertyorobject_property) to the@contextterm definitionwidgetto the corresponding UI annotationid,versionand$idto$idand the OO-LD version keywordskv_propertiesto free-form key-value handling, where semantic mapping is enabledsynonymsandtagsto the matching OO-LD annotation keywords, where they exist
Open questions
- The k-type notation is a separate format with its own
format_version, its own UI model (sections/inputs/widget) andrelation_mappingin place of a JSON-LD@context. Which parts should round-trip and which are DSMS-specific and out of scope? - Convergence is still being negotiated in
x-kitemvs OO-LDx-oold-rangekeyword semantic-dataspace/semantic-schemas#4 (x-kitemvs OO-LDx-oold-range). If that lands, a k-type reference could resolve to a schema and part of this converter becomes unnecessary. Worth settling the direction before implementing x-ktypecurrently names opaque k-type IDs rather than resolvable schemas, so the converter needs a resolution strategy against the knowledge-types registry- Which direction is authoritative, and whether a full round trip is a goal at all
Activity
Kirankumaraswamy commentedon Nov 2, 2026
Based on my assessment, I want to clarify how k-types and OO-LD schemas relate, because I think a converter is not the right direction here.
A k-type is the registry entry for a Knowledge Item class — it defines the name, version, ontology class, and tags. It is not a schema. Schemas are optional payloads attached to a k-type via semantic_schemas[]. A single k-type can carry zero, one, or multiple schemas.
Custom properties are a transitional mechanism
Custom properties (the sections/inputs/widget block in the k-type spec) were the original way to attach a structured form and RDF mapping to a KItem. They work, but the data model is flat and semantic expressivity is limited.
OO-LD schemas in the semantic-schemas repository are the replacement: they support nested graph patterns, reuse via allOf/$ref, vocabulary-backed selects, array groups, and proper JSON-LD context for rich RDF output. DSMS already loads these schemas, renders the webform from the schema structure, and generates the knowledge graph when the user submits data.
The migration path — not a round-trip converter
The plan is not to convert custom properties into OO-LD schemas mechanically. It is to replace custom properties gradually by authoring proper OO-LD schemas in semantic-schemas and referencing them from the k-type spec. The authoring workflow is: write the schema in semantic-schemas, reference it from the k-type — not derive one from the other. A round-trip converter between the two is not needed and not meaningful, because the two representations are not isomorphic — custom properties carry DSMS-specific UI concepts (hints, widget types, section layout) that have no place in a standards-compliant OO-LD schema.
Where a converter is useful: standard OO-LD → DSMS-extended OO-LD
The real conversion need is narrower: transforming a standards-compliant OO-LD schema into a DSMS-augmented variant that the frontend can fully render. Specifically two DSMS-specific extensions are needed on top of vanilla OO-LD:
x-kitem — declares which k-type(s) are valid targets for a property so the frontend renders a Knowledge item picker instead of a plain URI input. Without this, entity-to-entity linking cannot be resolved in the webform.
Vocabulary loading — properties backed by a controlled vocabulary need a x-vocabulary URL so the frontend fetches and renders the term list as a searchable dropdown.
A lightweight converter or annotation tool that takes a standard OO-LD schema and injects these DSMS-specific extensions — driven by the k-type spec as the source of truth for kitem targets and vocabulary endpoints — would be genuinely useful and a reasonable scope for this issue.
In short: no converter between custom properties/k-types and OO-LD schemas. But a converter from standard OO-LD to DSMS-extended OO-LD, handling x-kitem and vocabulary annotations, is a real need worth pursuing.
SimonStier commentedon Nov 2, 2026
Sounds good to me - agreeing is always better than converting!
Should be move this to a "OO-LD compliance in DSMS" tracking issue? Do you have DSMS issues to link here?
Kirankumaraswamy commentedon Nov 3, 2026
There are no DSMS issues at the moment. We can create a new one here. @yoavnash , what do you think?