ADR-008. A constraint is translated or named, never guessed and never silent

Status: accepted, 7 September 2026. Still in force.

Context

The generator was good at type, required, enum and default. It was blind to everything else the contract says about a parameter, and the blindness had a concrete cost: lb_subscriber accepted email_config and webhook_config, which the contract forbids with a shared x-one-of: config marker. The API answered 400. Nothing else in the chain could say so: not the documentation, not the argument_spec, not ansible-test sanity, which has no way to know. The defect was visible only on a user’s first playbook.

The danger has moved. It is no longer “the generator picks the wrong str or int”. It is:

the module accepts two parameters the API forbids together.

Much subtler, and invisible until the 400.

The parser saw the marker and dropped it, with a comment saying it was a separate job.

Decision

Every constraint keyword the contract can carry is in one of three states, and the report says which:

  • translated into an argument_spec constraint. x-one-of becomes mutually_exclusive;

  • carried by the IR and counted, not yet translated. Nullability is here: a clearable field and an absent field produce the same request today, and telling them apart needs a clear/reset semantics the contract does not describe. Counting it first is what will size that work;

  • absent from the document, which is measured and not asserted. A list written by hand would stay true on screen and false in the contract the day upstream adds the constraint, and the parameter would pass without it.

Two rules follow, and both are the repository’s rule 3 applied to constraints:

  • nothing is guessed. The generator does not invent a required_one_of because a group looks like it should have one. The contract does not declare it, so the module does not require it.

  • nothing is silent. A keyword found and not translated raises a parser warning naming it and its count.

Consequences

A group whose members are not all options of the module is dropped rather than narrowed: Ansible refuses to load a module whose mutually_exclusive names an absent option, and it refuses it for every call. A badly placed constraint would break more than it protects.

The report now publishes three different numbers, and their names say what they count. An earlier version announced nullable both as carried and as absent; both were true, because one counted an OpenAPI 3.0 keyword the contracts never use and the other counted the 3.1 form they do use. A count with an ambiguous name is the same defect as a ratio with no denominator.

Nullability stays counted and untranslated, deliberately. That is a debt, it is named, and it is sized: the report gives the number.

What this record does not decide

What to do about clearable fields. That needs a semantics the contract does not carry, and it will be decided when the count says it is worth it.