Skip to main content

Project Module

The source we are porting​

The contract we create is a direct port of the full-example.odcs.yaml from the ODCS project. It is helpful to read that file first since it is a few hundred lines of deeply nested YAML without types or reuse. Our goal is to represent the same contract as typed KCL, but in a shorter, simpler way at every level.

Two deliberate differences are worth calling out before we start:

  • Deprecated declarations are removed. This is Enkinex ODCS v3.1.0, which follows the standard ODCS v3.1.0. It does not include outdated parts from the standard (for example, dataProduct or slaDefaultElement), so those are simply missing from the port.
  • Default values are omitted. The main schema defines apiVersion = "v3.1.0" and kind = "DataContract" as default values, so we never write them manually. KCL adds them when exporting. The same applies to any other field whose default already matches the example.

Creating the contract project module​

A contract project is a KCL module: a directory with a kcl.mod manifest that declares the module's identity and its dependencies.

Initialize the module​

Use kcl mod init to scaffold it. This creates the kcl.mod manifest, a kcl.mod.lock lockfile, and an initial main.k:

kcl mod init enkinex-odcs-tutorial --version 3.1.0

Running it without a name initializes the current directory as a module; passing a name creates a subdirectory for it.

Add the enkinex-odcs dependency​

Use kcl mod add to pull the library straight from its GitHub repository. Pin it to a branch, tag, or commit so builds stay reproducible:

kcl mod add --git https://github.com/enkinex/enkinex-odcs --tag 'v3.1.0'

That records the dependency under [dependencies] in your kcl.mod. Whenever you later change kcl.mod resync the lockfile with kcl mod update:

kcl mod update

The finished manifest — the one in enkinex-odcs-tutorial/kcl.mod — is exactly what those commands produce:

[package]
name = "enkinex-odcs-tutorial"
edition = "0.12.7"
version = "3.1.0"
description = "Enkinex ODCS Tutorial"

[dependencies]
enkinex_odcs = { git = "https://github.com/enkinex/enkinex-odcs", tag = "v3.1.0" }

The project structure we are building​

The point of authoring in KCL is modularity, so we do not pack everything into one file. The project follows the same layout as the enkinex-odcs library — one directory per logical group of the standard — and a root file composes the pieces into the final DataContract:

enkinex-odcs-tutorial/
├── kcl.mod                 # module manifest + enkinex-odcs dependency
├── kcl.mod.lock            # resolved dependency lockfile
├── contract.k              # root: composes every part into a DataContract
├── contract.yaml           # exported ODCS YAML (generated)
├── catalog/                # dataset shape: schema objects & properties
│   ├── payment.k
│   └── receiver.k
├── contract/               # contract-level metadata
│   ├── authoritative.k
│   ├── description.k
│   ├── price.k
│   ├── properties.k
│   ├── sla.k
│   └── support.k
├── iam/                    # access & ownership
│   ├── member.k
│   └── role.k
└── server/                 # connection details
    └── postgres.k

We build it bottom-up: the leaf files in contract/, iam/, server/, and catalog/ each declare a named, typed value, and the root contract.k references those values by name. The sections that follow cover one group at a time, starting with the contract/ metadata group and the first version of contract.k.

note

The finished project lives under enkinex-odcs-tutorial repository.