Import a message model

Semantic Treehouse offers an import feature for message model versions. Instead of building a message tree element by element using the Wizard, maintainers can prepare a message model externally and import it in one step. This is useful when a message specification already exists in a structured format outside of Semantic Treehouse.

Two import formats are supported:

LinkML — an open standard for defining data models. LinkML schemas can be authored in any text editor and describe a message tree using classes and attributes.
Semantic Treehouse YAML — a flat YAML format specific to Semantic Treehouse, produced by the excel-to-content-yaml tool.

Where to import

There are two places to start an import:

The Create message model wizard (LinkML only). Pick LinkML as the message basis to create a new specification and its first version from a LinkML schema in one go. See Create a specification from a LinkML schema.
The Import message model version screen (both formats). Use this to add a new version to an existing message model specification. See Import a version into an existing specification.

Prerequisites

Before importing, you need:

Maintainer rights on the project or specification you import into.
A .yaml file in one of the two supported formats.
For LinkML: every local schema file your schema imports (see Imported schemas).

If your import file references business rules by their human-readable IDs (e.g. BR-01), those business rules should already exist in Semantic Treehouse. The import will succeed without them, but a warning will tell you how many business rules could not be linked.

Create a specification from a LinkML schema

Open the Create message model wizard (see Wizard step 1).
Fill in the Specification name, Project and Model version.
Under Message basis, select LinkML.
Choose your schema under LinkML schema. If it imports other local schemas, choose those under Extra / imported schemas.
Click Create message model.

The specification and its version are created, the schema is imported into that version, and the new message model opens in the Wizard. If the import fails, the error is shown and the specification is removed again, so you can correct the schema and submit the form once more.

Import a version into an existing specification

Open the edit screen of the message model specification and click Import next to the button for adding a version. The Import message model version screen opens in a new tab.
Enter a Version label (e.g. 1.0.0). This must be a new version label within the specification: you cannot import into a version that already contains a message.
Select the Format of your file: LinkML or Semantic Treehouse YAML.
Choose your file. For LinkML, also choose any imported schemas under Extra / imported schemas.
Click Import.

On success, a new version is created with the full message tree. You can view and further edit it through the Wizard.

Importing from LinkML

LinkML (Linked Data Modeling Language) is a YAML-based language for defining data models. A LinkML schema defines classes (types of objects) and their attributes (properties). Semantic Treehouse interprets a LinkML schema as a message tree by walking the class hierarchy starting from the root class.

Errors and warnings

Before importing, Semantic Treehouse checks your schema with the official LinkML linter. If the schema contains errors, the import stops and lists them, so you can correct the schema and try again.

After a successful import, a message shows how many elements were imported. It can be accompanied by warnings:

Business rules not found: the number of referenced business rules that do not exist in Semantic Treehouse (see Business rules).
Recursive references not expanded: the paths of the elements where a recursive class reference was cut off (see Recursive class references).

How LinkML maps to a message tree

The schema must have exactly one class with tree_root: true. The import fails if there is none, or more than one.

The table below shows how LinkML constructs translate to message model elements in Semantic Treehouse.

LinkML construct	Message element property
Class with `tree_root: true`	Root element (the message), always with cardinality 1..1
Root class name, or attribute name	Element name
`title`	Element label (defaults to the element name)
`description`	Definition
`comments` and `notes`	Usage notes
`examples`	Example values
`class_uri` / `slot_uri`	Class URI
Attribute with `range: <ClassName>`	Child aggregate element (recurses into that class)
Attribute with `range: string`, `integer`, a custom type, etc.	Leaf element with datatype
Attribute with `range: <EnumName>`	Leaf element with allowed values
`minimum_value` / `maximum_value` (numbers only)	Minimum / maximum inclusive value
`equals_string`	Fixed value
`pattern`	Regex pattern (leading `^` and trailing `$` are removed)
`required: true`	Minimum cardinality 1, maximum cardinality 1
`required: false` (default)	Minimum cardinality 0, maximum cardinality 1
`multivalued: true`	Uses `minimum_cardinality` and `maximum_cardinality` (unbounded if no max)
Annotation `business_rules`	Links to existing business rules by human ID
Schema `description`	Specification description, if the specification has none yet

LinkML properties not listed here are not imported.

Attributes, slots and inheritance

LinkML offers several ways to give a class its attributes, and all of them are supported:

inline attributes defined directly on the class;
top-level slots that a class refers to with its slots key, optionally refined with slot_usage;
attributes and slots inherited from a parent class (is_a) or from mixins.

In the message tree, a class's own attributes come first, followed by the inherited ones.

default_range: string

slots:
  id:
    description: "Unique identifier"
    required: true
  name:
    description: "Display name"

classes:
  NamedThing:
    slots:
      - id
      - name
  Invoice:
    is_a: NamedThing
    tree_root: true
    attributes:
      total:
        range: decimal

This creates an Invoice message with the elements total, id and name.

Attributes that refer to a class

When an attribute's range is another class, that class is expanded as a child element. The attribute determines how the child appears in the message tree:

The element is named after the attribute, not the class. Its label is the attribute's title, if present.
The attribute's description and slot_uri take precedence over the class's description and class_uri.
Usage notes, example values and business rules of both the attribute and the class are added to the element.

classes:
  Order:
    tree_root: true
    attributes:
      Supplier:
        range: Party
        title: "Supplying party"
        description: "The party that supplies the goods"

  Party:
    description: "A generic party"
    attributes:
      Name:
        range: string

This creates a Supplier element with the label 'Supplying party', the definition "The party that supplies the goods", and a Name child element.

Cardinality

For single-valued attributes (the default):

required: true results in cardinality 1..1
required: false (or omitted) results in cardinality 0..1

For multi-valued attributes (multivalued: true):

minimum_cardinality sets the minimum (defaults to 0, or 1 if required: true)
maximum_cardinality sets the maximum (defaults to unbounded)

The root element always has cardinality 1..1.

Datatypes

The LinkML built-in types map to their XML Schema (XSD) equivalents, for example:

LinkML type	XSD datatype
`string`	`xsd:string`
`integer`	`xsd:integer`
`boolean`	`xsd:boolean`
`decimal`	`xsd:decimal`
`float`	`xsd:float`
`double`	`xsd:double`
`date`	`xsd:date`
`datetime`	`xsd:dateTime`
`time`	`xsd:time`
`uri`	`xsd:anyURI`

You can also define your own types. A type with a uri uses that URI as its datatype; a type with typeof takes the datatype of the type it extends.

prefixes:
  xsd: http://www.w3.org/2001/XMLSchema#

types:
  PositiveInteger:
    typeof: integer
  IsoDate:
    uri: xsd:date

If an attribute has no range, the schema's default_range is used, or string if the schema has none.

Enumerations (allowed values)

When an attribute's range points to an enum defined in the enums section, the names of the enum's permissible_values are imported as the element's allowed values.

enums:
  StatusCode:
    permissible_values:
      draft:
        description: "In draft"
      published:
        description: "Published"

classes:
  Document:
    tree_root: true
    attributes:
      Status:
        range: StatusCode

This creates a Status element with allowed values draft and published. The descriptions of the permissible values are not imported.

Value restrictions

Some LinkML slot constraints are imported as value constraints:

minimum_value and maximum_value become the inclusive minimum and maximum. Only numeric bounds are imported; other bounds, such as dates, are ignored.
equals_string becomes the element's fixed value.
pattern becomes the element's regex pattern. A leading ^ and trailing $ are removed.

classes:
  Order:
    tree_root: true
    attributes:
      Quantity:
        range: integer
        minimum_value: 1
        maximum_value: 100
      Currency:
        range: string
        equals_string: "EUR"
      PostalCode:
        range: string
        pattern: "^[0-9]{4}[A-Z]{2}$"

Example values

LinkML's examples field can be used to provide example data for a class or an attribute. Each example has a value and an optional description. The values are imported as example values on the element; the descriptions are not imported.

classes:
  Order:
    tree_root: true
    attributes:
      OrderNumber:
        range: string
        required: true
        examples:
          - value: "ORD-2026-001234"
          - value: "PO-NL-00042"
      UnitPrice:
        range: decimal
        examples:
          - value: "29.95"
            description: "A typical unit price"

Semantic URIs

LinkML supports linking classes and attributes to ontology concepts via class_uri and slot_uri. These are stored in the element's Class URI field. CURIEs such as saref:Device are expanded to full URIs using the schema's prefixes.

prefixes:
  saref: https://saref.etsi.org/core/

classes:
  Device:
    class_uri: saref:Device
    tree_root: true
    attributes:
      hasFunction:
        slot_uri: saref:hasFunction
        range: string

Business rules

Business rules can be referenced from attributes or classes using an annotation. The value is a comma-separated list of human-readable business rule IDs that must already exist in Semantic Treehouse.

classes:
  Invoice:
    tree_root: true
    attributes:
      InvoiceNumber:
        range: string
        required: true
        annotations:
          business_rules: "BR-02, BR-03"

Business rule IDs that are not found do not stop the import; a warning tells you how many could not be linked.

note

LinkML also has a native rules construct for expressing conditional logic (preconditions/postconditions) on classes. These are not imported as business rules. Create your business rules in Semantic Treehouse and link them with the business_rules annotation instead.

Comments and notes

Both the comments and notes fields in LinkML are imported as usage notes on the element. They can be specified on both classes and attributes.

classes:
  Order:
    tree_root: true
    comments:
      - "Conforms to the European e-invoicing standard EN 16931"
    attributes:
      ID:
        range: string
        comments:
          - "Must be globally unique"
        notes:
          - "Format may change in future versions"

Imported schemas

A LinkML schema can reuse definitions from other schemas with the imports key:

imports:
  - linkml:types
  - core

Imports written as a CURIE or URL, such as linkml:types, are resolved automatically. You don't need to upload them.
Local imports, such as core, refer to other files and must be uploaded under Extra / imported schemas. The file name must match the import: an import of core needs a file named core.yaml (or core.yml). This also applies to the imports of the uploaded schemas themselves.

Uploaded files are matched by their file name only, so local imports must refer to files in the same folder as the importing schema (core, not shared/core or ../core).

If an imported file is missing, the import stops and names the file to upload.

Recursive class references

If a class refers to itself, directly or through other classes, expanding it would never end. Instead, the importer stops where the class reappears: the element is created, but its children are not expanded a second time.

After the import, a warning lists the paths of the elements where this happened, such as Document/author/manager. You can then decide in the Wizard how to model these elements.

Example

Below is a minimal but complete LinkML schema ready for import:

id: https://example.org/order-message
name: order_message
title: Simple Order Message

prefixes:
  linkml: https://w3id.org/linkml/

imports:
  - linkml:types

classes:
  Order:
    tree_root: true
    description: "A purchase order"
    attributes:
      OrderNumber:
        range: string
        required: true
        description: "Unique order identifier"
      IssueDate:
        range: date
        required: true
        description: "Date the order was issued"
      BuyerName:
        range: string
        required: true
        description: "Name of the buyer"
      OrderLine:
        range: OrderLine
        multivalued: true
        minimum_cardinality: 1
        description: "Line items"

  OrderLine:
    description: "A line item within an order"
    attributes:
      ItemName:
        range: string
        required: true
        description: "Name of the ordered item"
      Quantity:
        range: integer
        required: true
        description: "Ordered quantity"
      UnitPrice:
        range: decimal
        description: "Price per unit"

This produces the following message tree:

Order (root, 1..1)
  OrderNumber (string, 1..1)
  IssueDate (date, 1..1)
  BuyerName (string, 1..1)
  OrderLine (aggregate, 1..n)
    ItemName (string, 1..1)
    Quantity (integer, 1..1)
    UnitPrice (decimal, 0..1)

Limitations

The LinkML importer covers the most common constructs for defining message trees. The following are not supported in the current version:

Imports from other folders. Local imports must refer to files in the same folder, see Imported schemas.
Alternative ranges. Only an attribute's range determines its type. Constructs such as any_of and exactly_one_of are not interpreted.
Non-numeric bounds. minimum_value and maximum_value are only imported when they are numbers.
Structured patterns and rules. LinkML's structured_pattern, rules, and classification_rules are not evaluated during import. Use pattern for text patterns. Business rules should be managed separately in Semantic Treehouse and linked via annotations.
Other metadata. Properties not listed in the mapping table, such as the descriptions and meaning of permissible values or the descriptions of examples, are not imported.

Importing Semantic Treehouse YAML

The Semantic Treehouse YAML format is a flat array of element objects. Each element specifies its position in the tree via local_id and parent_id references. This format is produced by the excel-to-content-yaml tool, which converts spreadsheet-based message specifications into the YAML format.

For documentation on this format, refer to the tool's repository.

Where to import​

Prerequisites​

Create a specification from a LinkML schema​

Import a version into an existing specification​

Importing from LinkML​

Errors and warnings​

How LinkML maps to a message tree​

Attributes, slots and inheritance​

Attributes that refer to a class​

Cardinality​

Datatypes​

Enumerations (allowed values)​

Value restrictions​

Example values​

Semantic URIs​

Business rules​

Comments and notes​

Imported schemas​

Recursive class references​

Example​

Limitations​

Importing Semantic Treehouse YAML​