Unexpected behaviour for struct disjunctions

[mboogerd]

Hi, I've been playing around with Cue for a few days now and most seems to work pretty intuitively. Really nice!

I have one weird case with struct disjunctions that I don't fully understand. Take the following CUE expression (reproducer below):

struct-disjunction.cue

{ a: string } | { b: int }

I would expect the following two JSON payloads to pass vet/validation:
a.json

{"a": "string"}

and b.json

{"b": 42}

But it doesn't:

cue vet a.json struct-disjunction.cue
incomplete value {a:"test"} | {a:"test",b:int}

cue vet b.json struct-disjunction.cue
incomplete value {b:1,a:string} | {b:1}

It does pass for a JSON value of

{
    "a": "string",
    "b": 42
}

but that is the evaluation result I would expect for a conjunction CUE expression { a: string } & { b: int }, or a disjunction of open structs { a: string, ... } | { b: int, ... }, but not a disjunction of closed structs.

A potentially related, second question: if I employ CUE definitions, the evaluation also turns into something incomprehensible:

union.cue

#A: {
    a: string
}

#B: {
    b: number
}

#A | #B

cue eval union.cue
{
    #A: a: string
    a: string
    #B: {
        b: number
    }
} | {
    #A: {
        a: string
    }
    b: number
    #B: {
        b: number
    }
}

I'm not sure if these two things are related at all, but they appear around the same construction. Can someone clarify for me what is happening here? Thanks a bunch in advance!

Reproducer script

cd $(mktemp -d)
(
echo "{ a: string } | { b: int }" > struct-disjunction.cue
echo '{"a": "string"}' > a.json
echo '{"b": 42}' > b.json
cue vet a.json struct-disjunction.cue
cue vet b.json struct-disjunction.cue
)

[mboogerd]

Hmmm, I noticed just now that there is an explicit construction to create a closed struct: close({ a: string }) | close({ b: int }). However, it raises additional questions:

1. What is the meaning is of a non-closed struct that is not marked with ...?
2. Why can't I vet {"a": "test"} with the explicitly open struct CUE expression { a: string, ... } | { b: int, ... }
3. Why is this closed struct disjunction non-commutative? (isn't that in direct conflict with the lattice laws?)

It fails to validate {"a": "test"}

cd $(mktemp -d)
(
echo "close({ a: string }) | close({ b: int })" > struct-disjunction.cue
echo '{"a": "string"}' > a.json
cue vet a.json struct-disjunction.cue
)

field not allowed: a

But it succeeds in validating {"b": 42}

cd $(mktemp -d)
(
echo "close({ a: string }) | close({ b: int })" > struct-disjunction.cue
echo '{"b": 42}' > b.json
cue vet b.json struct-disjunction.cue
)

[myitcv]

@mboogerd welcome to the CUE project!

There are a few things going on here, one of which might well be a bug 😄 so I'll try to pick things apart.

In the expression:

{ a: string } | { b: int }

the structs that are part of the disjunction, {a: string} and {b: int}, are open. When we talk about using a schema like this expression to validate some data, we look to ensure that it unifies with the data and gives a complete and unambiguous result. "Unifies" simply means "the data is consistent with the schema's constraints". Taking the example of a.json:

{"a": "test"}

(I assume from your description above that "string" was a typo given the error message).

Both structs in the disjunction are open, hence this value unifies with both of them to give the values you see in the error message (depending on whether you are validating a.json or b.json):

{a:"test"} | {a:"test",b:int} // a.json
{b:1,a:string} | {b:1}        // b.json

and hence neither of the elements of the struct is eliminated. Notice that in each, there is an incomplete value, because b:int is not a concrete value, neither is a:string, i.e. the evaluator can't fully determine if this is valid or not. So this is working as intended for both a.json and b.json.

This also explains why by comparison the following passes validation:

{
    "a": "string",
    "b": 42
}

That value unifies with both structs to give a complete and identical value in each case, hence the result is unambiguous.

...but not a disjunction of closed structs.

And herein lies the answer (as you have discovered). The structs above are not closed. They can either by closed by the close() builtin, or by using definitions. The use of definitions is more common, so I will go with your example:

#A: {
    a: string
}

#B: {
    b: number
}

#A | #B

The output from cue eval union.cue is as expected, because the expression #A | #B is embedded. The top level already includes the definitions #A and #B, hence both options repeat that structure, one says that the field a: string is valid, the other that b: number is valid. This approach of embedding is not however without its limitations, which is where the must() comes in, but that is not yet implemented.

So given what I believe you are trying to achieve (you are trying to describe limits on the struct of the JSON), I think definitions are your way forward.

But it's at this point that I think we run into a bug, as you have demonstrated in your reply:

# vet a.json using #A
exec cue vet x.cue justa.cue a.json

# vet b.json using #B
exec cue vet x.cue justb.cue b.json

# Ensure a.json does not vet with #B
! exec cue vet x.cue justb.cue a.json

# Ensure b.json does not vet with #A
! exec cue vet x.cue justa.cue b.json

# vet a.json using #A | #B
exec cue vet x.cue both.cue a.json

# vet b.json using #A | #B
exec cue vet x.cue both.cue b.json

-- a.json --
{
	"a": "test"
}
-- b.json --
{
	"b": 42
}
-- both.cue --
package x

#A | #B
-- justa.cue --
package x

#A
-- justb.cue --
package x

#B
-- x.cue --
package x

#A: {a: string}
#B: {b: int}

This gives the output:

# vet a.json using #A (0.028s)
> exec cue vet x.cue justa.cue a.json
# vet b.json using #B (0.029s)
> exec cue vet x.cue justb.cue b.json
# Ensure a.json does not vet with #B (0.030s)
> ! exec cue vet x.cue justb.cue a.json
[stderr]
field not allowed: a:
    ./a.json:2:2
    ./justb.cue:1:1
    ./justb.cue:3:1
    ./x.cue:1:1
    ./x.cue:4:5
[exit status 1]
# Ensure b.json does not vet with #A (0.028s)
> ! exec cue vet x.cue justa.cue b.json
[stderr]
field not allowed: b:
    ./b.json:2:2
    ./justa.cue:1:1
    ./justa.cue:3:1
    ./x.cue:1:1
    ./x.cue:3:5
[exit status 1]
# vet a.json using #A | #B (0.029s)
> exec cue vet x.cue both.cue a.json
[stderr]
field not allowed: a
[exit status 1]
FAIL: /tmp/testscript469010135/repro.txt/script.txt:14: unexpected command failure

This corresponds with what you observed in your reply. What's also problematic is that error has no details as part of it. I will raise an issue to capture both issues.

(Note the final command doesn't run because of an error in the preceding command, but it succeeds as expected, just as you observed).

One other point to note is that CUE does not currently handle the concept of a protobuf oneof all that well. This will be addressed in #822 (search for the "oneof" heading for relevant references - apologies, I can't link to heading from an issue)

Reproducer script

Thank you for including this, reproducers make our lives much easier! My reproduction above using the txtar format, which as you can see is quite good for multi-file examples. You can read more about how to create/use such reproductions in our wiki.

1. What is the meaning is of a non-closed struct that is not marked with ...?

It has no effect in a non-closed struct.

2. Why can't I vet {"a": "test"} with the explicitly open struct CUE expression { a: string, ... } | { b: int, ... }

This is covered by my explanation above, that the result must be complete and unambiguous.

3. Why is this closed struct disjunction non-commutative? (isn't that in direct conflict with the lattice laws?)

This is the bug you have run into 😄

[myitcv]

I just raised #1148

[mboogerd]

Thanks a bunch for your exhaustive coverage of my question(s) and logging the bug! I now understand that ... is specifically to open a (by default closed) declared struct, close is to close a (by default open) 'ad-hoc' disjunction and that these modifiers are ineffective otherwise (as opposed to creating some possible hybrid state)

I wasn't aware of the non-ambiguity constraint on validation, so I've learned something new there too. If I understand correctly, we need data-to-be-validated to not only contain structures that pass one of the branches of the disjunction, it also needs to have something that strictly disqualifies it as all other branches of the disjunction (if the intention is to use it as a union as opposed to intersection)

I wonder if there's an opportunity to improve on the ergonomics here. It seems that we could detect when a disjunction expression is not intentional: For open types T1, T2, ... Tn, and disjunction: d: T1 | T2 | ... | Tn, return a warning if i: T1 & T2 & ... & Tn is consistent (i.e. none of the branches have something that discriminates it from the others). Although d should pass a syntax/semantics check, it probably shouldn't pass a linter of some sort. Perhaps that already exists though and I have just missed it? Or perhaps there are cases where that check isn't useful at all. I'll be glad to take your thoughts on it!

[myitcv]

It seems that we could detect when a disjunction expression is not intentional

This is a good thought, and one that I have previously explored with @mpvl (see #629 for some related discussion). The problem is that it's hard to avoid false positives with such a rule, and as such it could become more of a hinderance than a help. I'm going to mark this for discussion however, in case there is something that could be done in the case of discriminator fields specifically.