CUE Schema produces empty JSONSchema?

[deepbrook]

I'm trying to generate a jsonschema for devs, but I'm utterly failing.

Following @rogpeppe 's guide worked fine - exporting the #Team schema works as described. But when I run the command against my own schema I get this:

> cue def --out jsonschema -e '#UserYAML' users/schema.cue
{
    "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Here's my source, living in a users/ subdirectory:

@experiment(aliasv2,try,explicitopen)
package schema

import "strings"

import "list"

#GitLabAccessLevels: [
	"owner", "maintainer", "developer", "reporter", "planner", "guest", "minimal",
]

#ErPlRoles: matchN(1, ["none", "developer", "engineer", "admin"])

#UserYAML: {
	id!:                    int    // ID of the User's account
	handle!:                string // GitLab Handle of the User
	first_name!:      string
	last_name!:       string
	external!: bool // If the user is an external developer / contractor, set to 'true'
	// The access level granted to a user at the namespace (top level group) level;
	// External contractors may only be granted 'minimal access', and must be explicitly
	// added to groups and/or projects to which they should have access, on a need-to-know
	// basis.
	email: string | *"\(strings.Join([strings.Replace(first_name, " ", "", -1), last_name, if external {"ext"}], "."))@bwi.de"
	if external {
		role: *"minimal" | error("External contractors may not have an access level higher than 'minimal' in the BundesMessenger Toplevel group!")
	} else {
		email: "\(strings.Join([strings.Replace(first_name, " ", "", -1), last_name], "."))@bwi.de"
		role:  matchN(1, #GitLabAccessLevels)
	}

	// Declare whether the user is also a codeowner of groups they are part of.
	// External contractors may not be codeowners of group or user config files
	// in this repository.
	codeowner: {
		if external == true {
			users:  *false | error("External developers cannot review/approve User changes!")
			groups: *false | error("External developers cannot review/approve Group changes!")
		} else {
			users:  bool | *false
			groups: bool | *false // Note: they're only made code owner of a group's config file if they're owner or maintainer of that group!
		}
	}

	erpl: {

		if external {
			[string]: matchN(0, ["admin"]) | error("External contractors cannot be administrators!")
		}

		role: #ErPlRoles | *"none" // Default role to assign, unless specified otherwise below.
		zitadel:       #ErPlRoles | *role
		harbor:        #ErPlRoles | *role
		nexus:         #ErPlRoles | *role
		argocd:        #ErPlRoles | *role
		openbao:       #ErPlRoles | *role
		dtrack:        #ErPlRoles | *role
		// Access to our IONOSCloud accounts is only granted to admins and engineers.
		if list.Contains(["engineer", "admin"], role) {
			ionoscloud: "engineer" | "admin" | *role
		} else {
			ionoscloud: *"none" | error("Must be 'engineer' or 'admin' to gain access to IONOSCloud!")
		}

		password_version: int | *1 // Update this to roll passwords for this user
	}

	meta: {
		// If a user's handle changed, state the old value here. CUE will generate adequate moved blocks to update the terraform state.
		renamed: string | *""
	}
	...
}

I'm thinking it might be a silent error, something like "Buddy, I'm not generating that nonesense", or a simple layer 8 problem 😅

Not even sure if the parser can make sense of all those if clauses, to select the proper roles (if you have a better way for this, tips are appreciated as well).

Cheers!

[deepbrook]

@mvdan do you have an idea?

[mvdan]

Yes; @rogpeppe is working on an improvement to support this. I've already reviewed the change in https://cue.gerrithub.io/c/cue-lang/cue/+/1241049.

FWIW anything that sounds like a bug, even if it's a UX/error improvement, would be best raised as an issue so we can track it :) In this case I spotted it earlier in the week and pointed it out to Roger, but in general discussions are only for anything that is significantly less actionable - open-ended discussions, questions, proposals, etc.

[deepbrook]

That's fair - I simply wasn't sure if it's a bug or my approach. Thanks for the reply!

[deepbrook]

So, to clarify: If I wanted to declare the CUE equivalent of dependentSchema, I'd have to use matchIf ?

[rogpeppe]

In general, I'd suggest that it's good CUE "hygiene" to keep pure schemas separate from "templates".

A pure schema declares structure, but does not define data. It:

• contains only required or optional fields, never regular fields
• does not contain default values
• does not define fields predicated on the values of other fields

A template fills out data given other data.

The last schema restriction is arguable, but I think makes sense - it means we
can define the data structure statically without predicating it on computation.
BUT it does mean that it's not currently possible to define patterns like dependentSchemas
directly in CUE in such a way that they can be translated to JSON Schema.
That is a restriction currently because there's no way to inspect if comprehensions
via that cue.Value API. Note that your example does not match the dependentSchemas pattern.

As an example, we could split your use case into schema and template like this:

@experiment(aliasv2,try,explicitopen)
package schema

import "strings"

import "list"

#GitLabAccessLevels: [
	"owner", "maintainer", "developer", "reporter", "planner", "guest", "minimal",
]

#ErPlRoles: or(["none", "developer", "engineer", "admin"])

#UserYAMLTemplate: {
	#UserYAML
	let Self = self

	email: string | *"\(strings.Join([
		strings.Replace(Self.first_name, " ", "", -1)
		Self.last_name
		if Self.external {"ext"}
	], "."))@bwi.de"
	if Self.external {
		role: *"minimal" | error("External contractors may not have an access level higher than 'minimal' in the BundesMessenger Toplevel group!")
	} else {
		email: "\(strings.Join([strings.Replace(Self.first_name, " ", "", -1), Self.last_name], "."))@bwi.de"
	}
	// Declare whether the user is also a codeowner of groups they are part of.
	// External contractors may not be codeowners of group or user config files
	// in this repository.
	codeowner: {
		if Self.external == true {
			users:  *false | error("External developers cannot review/approve User changes!")
			groups: *false | error("External developers cannot review/approve Group changes!")
		} else {
			users:  bool | *false
			groups: bool | *false // Note: they're only made code owner of a group's config file if they're owner or maintainer of that group!
		}
	}
	erpl!: {
		password_version: int | *1 // Update this to roll passwords for this user
		if Self.external {
			[string]: matchN(0, ["admin"]) | error("External contractors cannot be administrators!")
		}

		role: #ErPlRoles | *"none" // Default role to assign, unless specified otherwise below.
		zitadel:       #ErPlRoles | *role
		harbor:        #ErPlRoles | *role
		nexus:         #ErPlRoles | *role
		argocd:        #ErPlRoles | *role
		openbao:       #ErPlRoles | *role
		dtrack:        #ErPlRoles | *role
		// Access to our IONOSCloud accounts is only granted to admins and engineers.
		if list.Contains(["engineer", "admin"], role) {
			ionoscloud: "engineer" | "admin" | *role
		} else {
			ionoscloud: *"none" | error("Must be 'engineer' or 'admin' to gain access to IONOSCloud!")
		}
	}
	meta: {
		// If a user's handle changed, state the old value here. CUE will generate adequate moved blocks to update the terraform state.
		renamed: string | *""
	}
}


#UserYAML: {
	id!:                    int    // ID of the User's account
	handle!:                string // GitLab Handle of the User
	first_name!:      string
	last_name!:       string
	external!: bool // If the user is an external developer / contractor, set to 'true'
	// The access level granted to a user at the namespace (top level group) level;
	// External contractors may only be granted 'minimal access', and must be explicitly
	// added to groups and/or projects to which they should have access, on a need-to-know
	// basis.
	email!: string
	role!: or(#GitLabAccessLevels)
	codeowner!: {
		users!: bool
		groups!: bool
	}
	erpl!: {
		[!= "password_version"]: string
		password_version!: int
	}
	meta!: renamed!: string
	...
}