Skip to main content
A semantic operation is a described change rather than an edited file. You hand cordango apply a list of operations and it rewrites the affected source files.
This is the preferred path for structural change, and the path an agent should use.

​
Scope is required

--scope names the one aggregate the change may touch. An operation naming anything outside the scope is refused, and no file is written. A rejected attempt costs nothing and needs no cleanup, which is what makes it safe to let an agent try.

​
The operations

upsert_entity, upsert_field, remove
Upserts, deliberately. An operation that describes the state a thing should be in can be applied twice without a different result, which matters when whatever is applying it decides to retry.

​
Ask what an operation may say

The operation vocabulary is a different question from the App Definition’s, and for a while it was the one nobody could ask. An agent worked it out by submitting deliberately invalid operations and reading the rejections. The schemas had existed the whole time. Nothing exposed them.
An operation and a file spell some things differently. A reference’s target is target in an operation and targetEntity in a file. A trigger is on against trigger. cordango vocabulary lists every pair. See the schema.

​
The file

note is for whoever reads the diff later.

​
See it before you do it

Prints which files a change would write or delete, and writes nothing.

​
Then check

cordango apply writes to the working tree. It doesn’t stage, commit, or validate anything on your behalf. A person reads the diff and decides.

​
Why not just edit the file

For a one-line change, do edit the file. Operations earn their place in three situations: Scope enforcement. The guarantee that a change can’t touch anything outside one aggregate is worth having when the thing making the change is a model. Refusal is free. A rejected operation set leaves the tree exactly as it was, with no half-applied state to clean up. They describe intent. upsert_field on ticket is a reviewable statement about what was meant. A YAML diff shows what changed but not why it was one change.