Methodology
The published descriptor, releases and their versioning, model versions and the language of likelihood.
Every number the platform publishes comes from a model of the methodology, applied to data that names its source. The methodology is published as a descriptor generated from the very objects the computation reads, so the description cannot drift from what runs.
The descriptor
GET /methodology returns the release in force:
| Field | Content |
|---|---|
version | The methodology release, in semantic versioning |
fingerprint | sha256: and the digest of the descriptor's canonical JSON |
changelog | Every release, newest first, with its date, summary and changes |
models | Each model with its version, steps, parameters (values, units and rationale), references and limitations |
indices | The composite index frameworks |
The workbench's Methodology module shows the same descriptor, searchable, with the release history.
Releases
The methodology is versioned independently of the API. A change that alters any published output is a release:
| Release | When |
|---|---|
| Patch | A correction that changes outputs only in edge cases, such as tie-breaking, or a wording that keeps its meaning |
| Minor | A new model, a new parameter or a recalibrated parameter value |
| Major | A change to what a published quantity means: a scale, a definition or a band threshold |
Each model also carries its own version, bumped when its computation changes. A change that alters no output, such as a refactoring, keeps the version.
In every response
Lens-scoped responses state methodology: { version, fingerprint }. Compare the version with the one you stored to know whether a difference between two reads comes from the data or from the method.
Verifying a fingerprint
The fingerprint is sha256: followed by the lowercase hexadecimal SHA-256 of the UTF-8 encoding of the descriptor's canonical JSON, computed without the fingerprint member. Canonical JSON sorts object keys by UTF-16 code unit, omits whitespace and undefined members, keeps array order, and writes strings and numbers as JSON.stringify does.
function canonicalJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
if (value !== null && typeof value === "object") {
const members = Object.entries(value)
.filter(([, member]) => member !== undefined)
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(
([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`,
);
return `{${members.join(",")}}`;
}
return JSON.stringify(value);
}
const response = await fetch(
`${process.env.PRAXIS_URL}/api/v1/intelligence/methodology`,
{ headers: { Authorization: `Bearer ${process.env.PRAXIS_TOKEN}` } },
);
const { fingerprint, ...descriptor } = await response.json();
const digest = await crypto.subtle.digest(
"SHA-256",
new TextEncoder().encode(canonicalJson(descriptor)),
);
const hex = Array.from(new Uint8Array(digest), (byte) =>
byte.toString(16).padStart(2, "0"),
).join("");
const verified = fingerprint === `sha256:${hex}`;The language of likelihood
Every probability is also stated in the expressions of likelihood of Intelligence Community Directive 203. The lower bound is inclusive and the upper bound exclusive.
| Band | Probability |
|---|---|
| Almost no chance | 0 to 0.05 |
| Very unlikely | 0.05 to 0.20 |
| Unlikely | 0.20 to 0.45 |
| Roughly even chance | 0.45 to 0.55 |
| Likely | 0.55 to 0.80 |
| Very likely | 0.80 to 0.95 |
| Almost certain | 0.95 to 1 |
Index classes
Indices on 0 to 10, the country risk index and maritime stress, are classed with the risk classes of the INFORM Risk Index:
| Class | Score |
|---|---|
| Very low | 0 to 2 |
| Low | 2 to 3.5 |
| Medium | 3.5 to 5 |
| High | 5 to 6.5 |
| Very high | 6.5 to 10 |
A number printed beside its class never rounds into another class.