ODVS v1 - draft specification

Scope

ODVS covers how an appraisal is reduced to a canonical record and hashed. It does not cover the valuation model itself: that is the engine's job, identified by an engine id and version inside the record. The point is that two parties, or two engine versions, can compare appraisals byte for byte.

The canonical record

An appraisal keeps the fields that are a pure function of the domain and nothing else: the normalized domain, the engine id and engine version, the estimated value, the confidence score, the optional low and high bounds, and optional named numeric factor outputs (metrics). Database ids, timestamps, comparable-sale lists and anything else that depends on the environment are left out.

Every number must be finite. NaN, Infinity and -Infinity have no canonical bytes and must be refused; negative zero is folded to 0.

Domain normalization

A single pass, in this order:

1. Trim with ECMAScript String.prototype.trim(), which removes the ECMAScript whitespace and line-terminator sets, including U+00A0, U+FEFF and U+2028.
2. Lower-case with ECMAScript String.prototype.toLowerCase(), which is locale-independent and maps U+0130 to i followed by U+0307. Internationalized names stay in Unicode and are never converted to punycode.
3. Remove a URL scheme such as https://.
4. Remove everything from the earliest /, ? or #.
5. Remove one leading www. and then one trailing dot.

Because it is a single pass, normalizing twice can change a result further: www.www.x.com becomes www.x.com, and a second pass would give x.com. Hash version 1 pins the single-pass result, and the vectors below check it. Repeating until nothing changes is a candidate for a later hash version.

Serialization

Every hashed string is canonical JSON: UTF-8, no whitespace, object keys sorted recursively, so the order fields arrive in never matters.

• Keys sort by UTF-16 code unit, the ECMAScript default sort, not by code point. An emoji key therefore sorts before U+FF5A, and "10" before "9".
• Numbers are written by ECMAScript Number::toString, for example 1e+21, 1e-7 and 0.30000000000000004.
• Strings are escaped as ECMAScript JSON.stringify escapes them: quote, backslash and control characters escaped, a lone surrogate written as a \uXXXX escape, and all other non-ASCII characters written as-is.

The three hashes

All three are lowercase hex SHA-256 over canonical JSON.

inputCommitment = SHA256({ d: domain, e: engineId, v: engineVersion })
resultDigest    = SHA256(canonical result fields)
appraisalHash   = SHA256({ commitment: inputCommitment, result: resultDigest, hv: 1 })

The input commitment identifies the computation: the same domain on the same engine version always gives the same commitment. The result digest pins the numbers produced. The appraisal hash is the citable id of the whole appraisal.

The determinism property

For a deterministic engine, two appraisals with the same input commitment must have the same result digest. A pair that shares a commitment but differs in its digest is a determinism violation, and anyone holding both can show it.

Conformance

An implementation conforms to this draft when it reproduces every hash below and refuses each of the 3 non-finite inputs (NaN and plus or minus Infinity). The expected hashes were produced by a separate Node implementation and are checked against this site's own code by its test suite. You can run all 18 vectors against the code this site is serving in the ODVS verifier, in your own browser. The input of each vector is readable in the code the verifier runs; a licensed, machine-readable vectors file follows once the licence is chosen.