2. Create KItems with the SDK

In this tutorial we see how to create new Kitems.

2.1. Setting up

Before you run this tutorial: make sure to have access to a DSMS-instance of your interest, alongwith with installation of this package and have establised access to the DSMS through DSMS-SDK (refer to Connecting to DSMS)

Now let us import the needed classes and functions for this tutorial.

from dsms import DSMS, KItem

Now source the environmental variables from an .env file and start the DSMS-session.

dsms = DSMS(env=".env")

2.2: Create KItems

We can make new KItems by simple class-initiation: (Make sure existing KItems are not given as input). #

item = KItem(
    name="Specimen123",
    ktype_id=dsms.ktypes.Specimen,
    custom_properties = {
        "Width": 0.5,
        "Length": [0.1, 0.2],
    }
)

item

/app/dsms/knowledge/kitem.py:406: UserWarning: A flat dictionary was provided for custom properties.
                    Will be transformed into `KItemCustomPropertiesModel`.
  warnings.warn(

kitem:
  name: Specimen123
  ktype_id: specimen
  custom_properties:
    content:
      sections:
      - id: idb424123144cdd8
        name: Untitled Section
        entries:
        - id: id6c76bbffe7ca78
          type: Number
          label: Width
          value: 0.5
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
        - id: id717d07130a7618
          type: Slider
          label: Length
          value:
          - 0.1
          - 0.2
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false

Remember: changes are only syncronized with the DSMS when you call the commit-method:

dsms.add(item)
dsms.commit()
item.url

'https://bue.materials-data.space/knowledge/specimen/specimen123-5cb3a95e'

As we can see, the object we created before running the commit-method has automatically been updated, e.g. with the creation- and update-timestamp. We can check this with the below command:

item

kitem:
  id: 5cb3a95e-4aac-434d-81ba-7c242fd245aa
  name: Specimen123
  ktype_id: specimen
  slug: specimen123-5cb3a95e
  annotations: []
  attachments:
  - name: subgraph.ttl
  linked_kitems: []
  affiliations: []
  authors:
  - user_id: 7f0e5a37-353b-4bbc-b1f1-b6ad575f562d
  avatar_exists: false
  contacts: []
  created_at: 2025-08-13 14:29:01.826691
  updated_at: 2025-08-13 14:29:01.826691
  external_links: []
  apps: []
  user_groups: []
  custom_properties:
    content:
      sections:
      - id: idb424123144cdd8
        name: Untitled Section
        entries:
        - id: id6c76bbffe7ca78
          type: Number
          label: Width
          value: 0.5
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
        - id: id717d07130a7618
          type: Slider
          label: Length
          value:
          - 0.1
          - 0.2
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
  rdf_exists: true
  contexts: []

To just get the name of the item, we can do it as follows:

item.name

'Specimen123'

As well as the id of the kitem we can do it as follows:

item.id

UUID('5cb3a95e-4aac-434d-81ba-7c242fd245aa')

To check the KType of the item newly created we can use the following:

item.ktype

ktype:
  id: specimen
  name: Specimen
  webform_schema_id: 21164fb6-cc45-4e08-8f8b-467a749df54b
  webform_schema:
    id: 21164fb6-cc45-4e08-8f8b-467a749df54b
    name: Specimen
    spec:
      semantics_enabled: true
      sections_enabled: false
      class_mapping:
      - https://w3id.org/pmd/co/Specimen
      sections:
      - id: idb424123144cdd8
        name: Untitled Section
        inputs:
        - id: id6c76bbffe7ca78
          label: Width
          widget: Number
          required: false
          hidden: false
          ignore: false
          select_options: []
          measurement_unit:
            label: Millimetre
            iri: http://qudt.org/vocab/unit/MilliM
            namespace: http://qudt.org/vocab/unit
          relation_mapping:
            iri: https://w3id.org/emmo#EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f
            type: object_property
            class_iri: https://w3id.org/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0
          multiple_selection: false
          knowledge_type:
          - null
          range_options:
            min: 0
            max: 1
            step: 0.1
            range: false
        - id: id717d07130a7618
          label: Length
          widget: Slider
          required: false
          hidden: false
          ignore: false
          select_options: []
          measurement_unit:
            label: Millimetre
            iri: http://qudt.org/vocab/unit/MilliM
            namespace: http://qudt.org/vocab/unit
          relation_mapping:
            iri: https://w3id.org/emmo#EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f
            type: object_property
            class_iri: https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac
          relation_mapping_extra:
            iri: https://w3id.org/emmo#EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f
            type: object_property
            class_iri: https://w3id.org/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0
          multiple_selection: false
          range_options:
            min: 0
            max: 1
            step: 0.1
            range: true
        hidden: false
    created_at: '2025-07-21T09:24:48.597715'
    updated_at: '2025-07-21T13:56:38.225444'
  created_at: '2025-07-21T09:20:12.746430'
  updated_at: '2025-07-21T09:24:58.495720'

… and also check the KType:

item.is_a(dsms.ktypes.Specimen)

True

We are able to print the subgraph related to the KItem:

print(item.subgraph.serialize())

@prefix ns1: <https://w3id.org/emmo#> .
@prefix ns2: <http://qudt.org/schema/qudt/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<https://bue.materials-data.space/knowledge/specimen/specimen123-5cb3a95e> a <https://w3id.org/pmd/co/Specimen> ;
    rdfs:label "Specimen123"^^xsd:string ;
    ns1:EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f <https://bue.materials-data.space/knowledge/specimen/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0_specimen123-5cb3a95e>,
        <https://bue.materials-data.space/knowledge/specimen/max_specimen123-5cb3a95e>,
        <https://bue.materials-data.space/knowledge/specimen/min_specimen123-5cb3a95e> .

<https://bue.materials-data.space/knowledge/specimen/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0_specimen123-5cb3a95e> a ns1:EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0 ;
    ns2:hasUnit "http://qudt.org/vocab/unit/MilliM"^^xsd:anyURI ;
    ns2:value "0.5"^^xsd:float .

<https://bue.materials-data.space/knowledge/specimen/max_specimen123-5cb3a95e> a ns1:EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0 ;
    ns2:hasUnit "http://qudt.org/vocab/unit/MilliM"^^xsd:anyURI ;
    ns2:value "0.2"^^xsd:float .

<https://bue.materials-data.space/knowledge/specimen/min_specimen123-5cb3a95e> a ns1:EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac ;
    ns2:hasUnit "http://qudt.org/vocab/unit/MilliM"^^xsd:anyURI ;
    ns2:value "0.1"^^xsd:float .

And we can convert the units:

item.custom_properties.Width.convert_to("m")

0.0005

item.custom_properties.Length.convert_to("m")

[0.0001, 0.0002]

You can also convert the custom_properties to a flat dict by passing the flat-parameter to the model_dump-method of the pydantic model:

item.custom_properties.model_dump(flat=True)

{'Width': 0.5, 'Length': [0.1, 0.2]}

Now you can check if the particular kitem is in the list of KItems. This can be done either by using the command: dsms.kitems or by logging into the frontend dsms instance.