What's the "standard" for a types template + import?

[adriangalilea]

I was skimming through the docs and went back and forth with claude and I could not find this apparently simple answer.

The way I made it work was:

❯ tree
.
├── cue.mod
│   └── module.cue
├── main.cue
└── types
    └── person.cue

main.cue

package main

import "example.com/types"

alice: types.#Person & {
	name: "Alice"
	age:  30
}

bob: types.#Person & {
	name: "Bob"
	age:  25
}

cue.mod/module.cue

module: "example.com"
language: {
	version: "v0.9.2"
}

types/person.cue

package types

#Person: {
	name: string
	age:  int & >=0 & <=120
}

Is there a simpler/better way to organise it?

Do I need the cue.mod/module.cue for this?

[hansbogert]

I don't think there's anything wrong with this. If you want to import a package which resides the working dir itself, then I think you have to define a module as you did.

What about the example are you hesitant about?

[adriangalilea]

1. Are there standards/patterns? such as, where to store types/templates.
2. Are there any naming conventions? Such as how to call what I'm referring to as "types/templates" document.
3. Should I store stuff under the cue.mod directory?
4. Are there any other ways to import local files without having to use the cue.mod directory? (I prefer not needing an extra dir + file to avoid clutter)
5. If not locally, what's the common way of importing files? Where do people store those?

[hansbogert]

I think it depends on how large your config will be eventually. If you want to start out small, it's fine to just have the types definitions in your main.cue as well. You could then remove the module related stuff and the types folder if you deem it too much overhead at at this point. If you want a bit more grouping, you can create other files with the same package name and place them besides main.cue. cue eval and other cue commands will just pick it up then. There's no hard rules here, cue is not overly opinionated, at least that's my experience (this answers point 1., 3. and 4.)

I used this simple approach for months now for validation of yaml. However, I'm now at the stage that I'm having duplicate definitions for multiple projects so I'm migrating to these to packages in a module that I can reuse in said multiple projects.
I will use an OCI registry save this module. You can read more about this in 1. (this answers point 5.)

Having said all this, I think I'd advise you to think about where you want CUE to help you at this point. For example, is it purely validation of existing yaml config? Build it out slowly, you can get benefit pretty fast before you need think about the 'perfect' setup. Let us know how you want to leverage CUE.

HTH

[adriangalilea]

You could then remove the module related stuff and the types folder if you deem it too much overhead at at this point.

I want a separate type definition file, to re-use said types on different implementations.

The moment I want to have 1 type definition file and 1 implementation, I'm forced to add +2 folders(cue.mod+types) + 1 file(module.cue) so it feels odd, or so I thought, after trying without cue init + cue.mod + defining a domain, seems too much a overhead for the simple cases.

you can create other files with the same package name and place them besides main.cue.

You mean I could have then, 1 type file and 1 implementation as long as they are in the same folder with the same package name, I tried that and I didn't manage to make it work, may try again.

Would it work if I decide to have it like this?

❯ tree
.
├── main.cue
└── types
    └── person.cue

Is there any reason why relative imports are not an option?

I didn't find documentation that covers imports, is there any?

Let us know how you want to leverage CUE.

Specifically at this point I'm using it to define steps for my custom installer system for my various linux/mac machines. This is the template for the steps, and this is the implementation for the raspberry pi.

Would you say my use-case is unexpected?

Am I wrong for using it this way?

I wanted to pick a config language that I could use in a variety of projects, across many languages, through time, that had types. I see that some of the main appeal is validating YAML or something else, but this is not my intention.

I find every config language problematic in one way or another, there are pain-points with all of the ones I used. So between TOML/YAML + CUE for validation, I rather just use CUE, both for validation and the config itself.

It's often overlooked how annoying, apparently benign formats like TOML/YAML(specially) can be, and is not without it's learning curve and regrets.

So I was researching a config language to use for the foreseeable future in my personal projects and else. After a deep dive, HOCON, PKL and CUE stood out, but I selected CUE. I must say I found the tutorial/guides didn't clear my doubts, in fact after this conversation I still have some, I don't mind learning curves, but I think the importing stuff should be more intuitive.

Overall I like the possibilities and will keep using CUE, but wanted to take a moment to reflect on my experience so you guys can get the outside perspective.

Many thanks for taking the time to reply.

[hansbogert]

You mean I could have then, 1 type file and 1 implementation as long as they are in the same folder with the same package name, I tried that and I didn't manage to make it work, may try again.

That's correct:

$ tree
.
|-- main.cue
`-- types.cue

1 directory, 2 files

$ cat main.cue

package person

alice: #Person & {
	name: "Alice"
	age:  13
}

bob: #Person & {
	name: "Bob"
	age:  25
}

$ cat types
#Person: {
	name: string
	age:  int & >=0 & <=120
}

Cue commands by default just take all files belonging to a package. If there's no ambiguity, i.e., there's only one package in the current directory, it takes that package:

$ cue export
{
    "alice": {
        "name": "Alice",
        "age": 13
    },
    "bob": {
        "name": "Bob",
        "age": 25
    }
}

Would it work if I decide to have it like this?

No, directories are significant. However, if you insist on a directory, you can call cue commands as follows, assuming your example directory hierarchy:

 cue vet types/types.cue main.cue

I previously said CUE is not opinionated, however seeing the above, I do think it's opinionated in the way you are allowed to reference other files, you can't do that on a per-file basis, you either need packages or feed them as parameters to the cue commands. Note that I'm only rookie as well, so someone might well correct me later on in this thread

Is there any reason why relative imports are not an option?

You can, but then you need a 'proper' module, that's how you started out. The reason, I think, is that relative imports by 'just' referencing plain files becomes messy quite fast. I also note that the packages and imports system have been heavily influenced by Golang. Modern languages do not allow relative imports. I do think this is actually one of the strengths of CUE but might feel as a needless limitation when starting out.

I didn't find documentation that covers imports, is there any?

The link I referenced earlier, references the previous documentation about modules: https://cuelang.org/docs/concept/modules-packages-instances/ it shows how you can keep modules/packages locally, it does imply a cue.mod directory though.

I agree with the rest of your usecase being very valid and your observation that the modules for someone just starting out feels a bit like you have to reverse engineer on how to use it.

I think a light-weight documentation should be written which just gives 1 to 3 use-cases and gives the reader confidence that they are using the packages/modules correctly, and why you should do it in a certain matter. I came from a Golang background yet even then the subtle differences made me somewhat inefficient at times by having to 'poke' CUE to see what works and doesn't

[adriangalilea]

it does imply a cue.mod directory though.

This is what I'm pointing out.

You can, but then you need a 'proper' module, that's how you started out. The reason, I think, is that relative imports by 'just' referencing plain files becomes messy quite fast. I also note that the packages and imports system has been heavily influenced by Golang. Modern languages do not allow relative imports. I do think this is actually one of the strengths of CUE but might feel as a needless limitation when starting out.

I see this now, and understand the rationale, but this is not clear from the docs.

Things that I think the docs should cover:

• Why no relative imports? (for people looking for this keyword coming from simpler/older languages)

• <How do we suggest you structure your packages/cue config>

• What other options do you have?

All this:

You mean I could have then, 1 type file and 1 implementation as long as they are in the same folder with the same package name, I tried that and I didn't manage to make it work, may try again.

That's correct:

$ tree
.
|-- main.cue
`-- types.cue

1 directory, 2 files

$ cat main.cue

package person

alice: #Person & {
	name: "Alice"
	age:  13
}

bob: #Person & {
	name: "Bob"
	age:  25
}

$ cat types
#Person: {
	name: string
	age:  int & >=0 & <=120
}

Cue commands by default just take all files belonging to a package. If there's no ambiguity, i.e., there's only one package in the current directory, it takes that package:

$ cue export
{
    "alice": {
        "name": "Alice",
        "age": 13
    },
    "bob": {
        "name": "Bob",
        "age": 25
    }
}

Would it work if I decide to have it like this?

No, directories are significant. However, if you insist on a directory, you can call cue commands as follows, assuming your example directory hierarchy:

 cue vet types/types.cue main.cue

I agree with the rest of your usecase being very valid and your observation that the modules for someone just starting out feels a bit like you have to reverse engineer on how to use it.

Yes, and really I don't mind opinionated stuff, is that I would like:

• To be redirected from my expectations into the solution
• To be convinced

As I was typing this you typed:

I think a light-weight documentation should be written which just gives 1 to 3 use-cases and gives the reader confidence that they are using the packages/modules correctly, and why you should do it in a certain matter. I came from a Golang background yet even then the subtle differences made me somewhat inefficient at times by having to 'poke' CUE to see what works and doesn't

My thoughts exactly 😃

Last note: I would add a link to these docs if they do happen on the relative import error warning on the console, that'd be the dream, perhaps a TL;DR too, simple options to solve it:

• Same package name same dir
• Different dir with cue command specifying the path
• cue.mod approach

EDIT: I would go as far as to say that one of the quick guides section should cover project structure approaches like the 3 strategies stated above, directly or indirectly.