Start creating libraries

There are two ways to create a new construction kit, using a .NET project template or using the compiler.

Create with project template

New construction kits can be created using the project template. The template can be installed from NuGet:

dotnet new install Meshmakers.Octo.ConstructionKit.Templates

To install a specific version of the template, use the following command:

dotnet new install Meshmakers.Octo.ConstructionKit.Templates::0.0.2312.12001

Create a new project with your favorite development environment, the template should be available as OctoMesh Construction Kit Library, alternatively you can use the following command:

dotnet new ConstructionKit -n <name of project>

Build the project, a new construction kit gets created within the folder ConstructionKit in the project root.

Create with the compiler

Install the compiler

The compiler can be installed from NuGet:

dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --global # global available
dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --local --create-manifest-if-needed # local available

You can also install a specific version of the compiler:

dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --global --version 0.0.2312.12001 # global available
dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --local --version 0.0.2312.12001 --create-manifest-if-needed # local available

Globally the tool gets available as octo-ckc, locally as dotnet octo-ckc.

Create a new construction kit with the following command:

octo-ckc -c new -p '<path of directory for construction kit>'

Edit a construction kit library

When creating a new Construction Kit library using the project template, a compilable example structure is automatically generated. The construction kit files are located in the ConstructionKit folder in the project root.

Directory Structure

The generated example follows this structure:

ConstructionKit/
├── ckModel.yaml           # Model definition with ID and dependencies
├── attributes/            # Attribute definitions
│   ├── sampleAttribute1.yaml
│   ├── sampleAttribute2.yaml
│   └── sampleAttribute3.yaml
├── associations/          # Association definitions
│   └── sampleAssociation1.yaml
├── enums/                 # Enum definitions
│   └── sampleEnum1.yaml
├── records/               # Record definitions
│   └── sampleRecord1.yaml
└── types/                 # Type definitions
    └── sampleType1.yaml

CkModel (ckModel.yaml): Defines the model ID and dependencies to other Construction Kit libraries
CkAttributes (attributes/*.yaml): Define reusable attributes with data types (strings, numbers, booleans, etc.)
CkAssociations (associations/*.yaml): Define relationships between types with cardinality
CkEnums (enums/*.yaml): Define enumeration types with their possible values
CkRecords (records/*.yaml): Define complex data structures with assigned attributes
CkTypes (types/*.yaml): Define the main entity types combining attributes and associations

note

Attributes cannot be assigned multiple times to the same type, because each attribute carries its own metadata and semantics Example: GrossPrice and NetPrice must be defined as two separate attributes, not a single Price attribute assigned twice with different names

File Organization

The template creates a best-practice structure with:

Separate directories for each element type (attributes, associations, enums, records, types)
Individual YAML files for each definition, making the model modular and maintainable
Sample definitions that demonstrate proper syntax and are immediately compilable

Developing an Object Model

The first step is to adapt the model ID and define dependencies in the ckModel.yaml file. There are already several existing Construction Kit libraries that you can build upon instead of reinventing everything from scratch. These libraries are documented under Libraries section.

Entity Design

Start by identifying the entities (types) in your domain. Each entity represents a business object with its own lifecycle and identity. Define these as separate type files in the types/ directory.

Relationships and Associations

Define how entities relate to each other through associations:

Create association definitions in the associations/ directory
Specify cardinality (1:1, 1:n, n:m) and navigation properties
For hierarchical structures, use the built-in System/ParentChild association for parent-child relationships

Semantic Values with Enums

Enums add semantic meaning to value ranges. Instead of using plain strings or numbers, enums provide:

Controlled vocabularies with defined possible values
Type safety and validation
Clear business semantics

Example: Define a Status enum with values like Active, Pending, Completed rather than using arbitrary strings.

Embedded Documents with Records

Records represent embedded documents containing structured information that doesn't require its own identity. Use records for complex attributes such as:

Address: Combining street, postal code, and city attributes
Contact Information: Grouping phone, email, and social media handles
Measurements: Bundling value, unit, and precision

Records are defined in the records/ directory and can be reused across multiple types as complex attribute types.

Schema Validation

All YAML files follow JSON schemas available at https://schemas.meshmakers.cloud/. For example:

Construction Kit elements schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json

These schemas ensure consistency and validity of your Construction Kit definitions during compilation.

Compile a construction kit

When using the project template, the construction kit gets compiled automatically when building the project.

When using the compiler, the construction kit can be compiled with the following command:

octo-ckc -c compile -p '<path of directory for construction kit>'

The compiler checks conformity of the construction kit files to the json schema files and consistency of the model to the dependencies and within the model. If the construction kit files are not valid, the compiler will throw an error.

In the ConstructionKit folder, a new file with the model id name gets created.

Import to OctoMesh

OctoMesh can import construction kits. The import can be done with the octo-cli tool. octo-cli is a command line utility to manage OctoMesh as an admin.

To install the tool, use chocolatey or Windows Package Manager with the following command:

winget install -e --id meshmakers.octo-cli
# or
choco install octo-cli

octo-cli can also be downloaded from the Download Center.

Depending on the installation method of OctoMesh, the tool needs to be configured to use the correct endpoints. The following command configures the tool to use the default endpoints of OctoMesh:

octo-cli -c Config -asu "https://localhost:5001/" -isu "https://localhost:5003/" -bsu "https://localhost:5009/" -csu "https://localhost:5015" -tid "meshtest"

Hint: The parameter -tid defines the used tenant.

Next, the tool needs to be logged in to OctoMesh. The following command logs in to OctoMesh using an administrator account:

octo-cli -c Login -i

Optional: Create a new tenant in OctoMesh:

octo-cli -c Create -tid meshtest -db meshtest

Hint: To delete tenants, use the following command:

octo-cli -c delete -tid meshtest

After the tenant is created, the API of Asset Repository can be used to access data of the tenant. https://localhost:5001/tenants/meshtest/graphql/playground

To import a construction kit, use the following command:

octo-cli -c importck -f ./ck-sample2.yaml -w

Hint: The parameter -f defines the path to the construction kit file that has been created by the octo-ckc compiler.