Payload soundness
Simile treats a request or response payload as sound only when it satisfies the complete compiled contract. The contract includes the supported OpenAPI schema rules and every recognized cross-field relationship declared withx-simile-constraints.
There is one authority for relationships: simile-schema::soundness. It owns extension parsing,
compiled constraint types, proof evaluation, and the establishment step used during synthesis. The
schema validator delegates all multi-value rules to that module. Incoming request payloads are
accepted only after the complete validator reports no violations. Request and response synthesis
use the same validator as their final gate, so generation cannot bypass a relationship that
validation enforces. The compiled .similec artifact carries the typed constraints; the runtime
does not reparse source OpenAPI or infer relationships from property names or prose.
This is a proof relative to the published contract. It does not claim that an incomplete contract
describes every private production invariant. A service provider must publish each relationship it
wants Simile to prove.
Ordered fields
Ordering is the first supported relationship:* segment to visit every item in an
array, as in /lines/data/*/amount. An ordered
constraint means each present, non-null value is less than or equal to the next present, non-null
value. Equality is valid. Ordinary OpenAPI required and nullable declarations continue to decide
whether a value may be absent or null.
The compiler accepts an ordered relationship only when:
- it contains at least two unique paths;
- every path resolves to a declared property;
- all paths resolve to compatible numeric values, or to strings explicitly formatted as
date-time; and - the relationship can be represented by the compiled schema graph.
ordered violation at the first later field that breaks the relationship.
Seeded synthesis generates values and then establishes the relationship before sending the complete
candidate through the same validator. If no sound finite candidate can be found within the bounded
search, synthesis fails instead of returning an unsound payload.
Relative bounds
A bounded constraint compares one constructive target with fields that supply dynamic bounds:minimum, maximum, exclusive-minimum, and exclusive-maximum. Every
participant must use the same numeric or RFC 3339 date-time kind. Bound sources must be required
and non-null, while the target may be optional or nullable because synthesis can establish it. An
inclusive violation copies the boundary. An exclusive violation chooses the next representable
integer, finite float, or date-time beyond that boundary.
Only the target is mutable. Simile applies all declared bounds to a candidate transactionally and
commits the result only when the complete relationship is sound. Contradictory bounds therefore
fail synthesis without leaving a partially repaired payload.
Conditional implications
An implication lets one field state constrain several others:when predicate is the antecedent. When it is false, the implication is satisfied without
examining its consequences. When it is true, every predicate under then.all must hold. Simile
accepts equals, contains, and state field predicates. contains applies to arrays. State is
one of present, absent, null, non-null, or null-or-absent; an explicitly null property is
present, while an absent property has no value in the object.
The antecedent can instead compare two numeric or RFC 3339 date-time fields:
greater-than, greater-than-or-equal, less-than, and
less-than-or-equal. A comparison is an antecedent, not an assignment expression. Consequences
remain constructive field assertions so Simile can compile a schema-valid witness for each one.
Every path must resolve to a declared property, every predicate must have a witness allowed by the
property schema, and assertions for the same path must be jointly satisfiable. Unsupported branches
such as then.any, empty consequence sets, dead predicates, and contradictory consequences fail
compilation.
Synthesis applies each triggered consequence set transactionally. It repeats all relationships to
a bounded fixed point so that one consequence may trigger another implication. A cycle or conflict
that cannot settle is rejected by the complete validator; Simile never returns the intermediate
candidate as sound.
Equality across fields and items
An equality constraint proves that every selected value is the same:required and item-count rules continue to decide whether that collection may be empty.
Distinct selected values
A distinct constraint rejects repeated scalar values selected across an array:Scalar set relationships
Set constraints relate two arrays of compatible scalar values:subset-of, superset-of, and disjoint. The right-hand array is the required,
non-null reference. The left-hand array is the constructive target Simile may repair by removing,
adding, or excluding values. This direction is explicit so generation never has to guess which of
two peer collections is authoritative.
Numeric equations
An equation computes one numeric field from required numeric source fields:{ path: /some/field } and a
constant leaf is { literal: 200 }. add and multiply accept two or more expressions;
subtract accepts exactly two. Sources must be required, non-null numeric properties and an
equation may not read its own target. Integer-only arithmetic stays integer-shaped when it fits the
JSON integer range. Simile proves the computed result during validation and writes that result into
the target during synthesis.
Equations do not silently apply currency rounding, clamp negative values, or infer accounting
meaning. Those are separate declared relationships or ordinary schema bounds.
Collection aggregates
An aggregate relates a numeric target to values selected from an array:sum, count, min, and max. The source must contain an array
wildcard. sum, min, and max require non-null numeric selected values; count accepts any
selected value kind. An optional when uses the same field-predicate language as an implication.
This is important for paginated representations: a partial page must not claim to prove a
whole-list aggregate. Without a guard, the selected collection is treated as complete. The sum or
count of an empty collection is zero; minimum and maximum have no value for an empty collection and
therefore cannot prove a target.
Per-item relationships
Relationships declared on an array’sitems schema are compiled and evaluated once for every
item. No separate loop construct is required:
Lifecycle snapshots
A lifecycle constraint proves that a state and its transition timestamps describe one possible path through a finite transition graph:created-at is
required. Transition timestamps use the same numeric or date-time kind and must be nullable or
optional so timestamps outside the chosen path can be cleared.
Validation accepts a snapshot only when one declared path ends at the current state, every
timestamp on that path is present and non-null, timestamps outside it are null or absent, and the
path is temporally ordered from creation onward. Synthesis chooses a deterministic valid path,
establishes its timestamps, and clears incompatible branches. Cyclic workflows and event histories
that need repeated transitions require a different event-oriented relationship; they are not
misrepresented as this snapshot model.
Derived string templates
A template ties a string field to required scalar fields:{/...} placeholder is a JSON Pointer. Its source must be a required, non-null string, number, or
boolean property. The target must be a string. Validation renders and compares the complete value;
synthesis writes the rendered string. Templates do not perform URL encoding or interpret prose.