Define the calculation boundary
An input contract describes the information a calculation accepts and what that information means. It is narrower than a model's motivation and more precise than an example screenshot. Begin with the requested output: weights, variance, a regression coefficient or a path statistic. Then name every required input and distinguish observations from assumptions. A portfolio variance calculation may consume an already estimated covariance matrix; that does not mean it also estimates covariance or chooses a sampling window. Keeping those boundaries explicit prevents a caller from assuming that a clean output includes upstream work that the calculation never performed.
Separate structure from meaning
JSON Schema can describe required properties, types and permitted extra fields. Its object documentation notes that listing properties does not by itself make them required, and that additional properties are allowed unless constrained. Those are useful structural checks, but they do not prove that two arrays describe the same assets or that a matrix uses the intended time horizon. Add semantic validation after parsing. For a strict hypothetical weights contract, require a nonempty asset list and an equally long numeric weight list, reject unknown fields, and check uniqueness of asset identifiers. Document those decisions rather than relying on parser defaults.
Treat units as part of identity
A volatility value of 0.20 means 20% only when the field specifies decimal annual volatility. The same number could represent daily volatility or variance under another contract. Labels therefore need units, frequency and transformation details, including whether returns are simple or logarithmic. Do not infer units from magnitude: a large legitimate observation can look like an accidental percentage input. A three-asset vector of 50, 30 and 20 should fail a decimal-weight contract rather than be silently divided by one hundred. An explicit conversion step can accept percentages, but it should preserve both the supplied values and the conversion chosen.
Validate numerical domains deliberately
RFC 8259 excludes NaN and Infinity from JSON numbers, yet a valid JSON token can still exceed a runtime's finite numeric range. Check finiteness after parsing as well as syntax before it. Individual models need additional domain rules: inverse-volatility weights require positive volatilities; a sample variance needs enough observations for its chosen denominator; an information ratio needs a defined treatment of zero tracking error. A long-only weights example can reject negative entries and require a sum within a declared tolerance of one. These are separate conditions. A vector that sums to one can still violate the nonnegativity requirement.
Preserve labels and axis order
A square matrix with the right dimensions can still be attached to the wrong assets. Require row and column labels to match the weight vector, or perform a documented label-based reordering before calculation. Sorting only the weights is not a repair because it changes the mapping between exposures and covariance entries. Symmetry and nonnegative diagonal checks are useful but do not establish positive semidefiniteness. Similarly, time-series rows need an ordering rule and a duplicate-time policy. A numeric array cannot explain whether its first observation is earliest, latest or arbitrarily sorted. Preserve that information where the caller can inspect it.
Make rejections reproducible
The table applies a hypothetical contract with exactly three unique labels, three finite decimal weights, nonnegative entries and an absolute sum tolerance of 0.000000001. Its rows change one condition at a time. The valid vector totals one; the percent-scaled vector totals one hundred; the short vector has the wrong length; the negative-weight vector totals one but violates the long-only domain. A rejection should identify the offending field and rule, not substitute a plausible default. These examples describe a proposed validation design, not a claim that a particular library card implements every listed check.
Contract the output and errors too
The contract should finish with output units, ordering, precision and failure behavior. Decide whether an undefined ratio produces an explicit error or a structured missing result; a finite zero should not stand in for both. Preserve full calculation precision while treating displayed rounding as presentation. Include a contract identifier with any reusable result so a later reader can distinguish a changed default from changed inputs. Acceptance tests should include the smallest valid case and targeted invalid cases. Passing them establishes interface consistency, not investment merit, but it makes the reference calculation a dependable component for further, separately specified analysis.
| Hypothetical input | Decision | Independent rule check |
|---|---|---|
| A,B,C; weights 0.5,0.3,0.2 | Accept | 3 unique labels; 3 finite nonnegative numbers; sum 1 |
| A,B,C; weights 50,30,20 | Reject | Sum 100, not 1; no implicit percent conversion |
| A,B,C; weights 0.5,0.5 | Reject | 2 weights for 3 labels |
| A,B,C; weights 0.6,0.5,-0.1 | Reject | Sum 1 but a negative weight |
| A,B,C; weights 0.5,null,0.5 | Reject | Null is not a numeric weight |
| A,A,C; weights 0.5,0.3,0.2 | Reject | Duplicate asset label |
Primary references
These sources support methods and conventions. The example values are original constructions, not observations extracted from these documents.
Related investigations
Implementation contractsMissing data and alignment: decide what was actually observable
Keep missingness, stale observations, asynchronous timestamps and covariance sample selection visible in a calculation's input history.
Implementation contractsReproducible model artifacts: preserve the calculation, not just its answer
Build a checkable evidence bundle that distinguishes identical files, numerically equivalent outputs and independently verified arithmetic.
Implementation contractsModel version and change control: preserve what each result meant
Define compatibility for mathematical outputs, classify hypothetical changes and keep first-edition evidence distinct from proposed future releases.