The engine
The scoring formula as one JavaScript file with no dependencies. The same file ranks every option in Conscious Consuming and runs the worked formula on this kit's front page.
- Version: 0.11
- Size: 35 KB, no dependencies
- Licence: AGPL-3.0-or-later
Use it
In a browser or in Node, import the version you built against. Each version keeps its own address, so an app can pin it.
import engine, { score } from 'https://valuescommons.org/standard/engine/open-values-engine-0.11.mjs';
const ctx = {
criteria: [{ key: 'pay', label: 'Fair pay' }, { key: 'price', label: 'Price' }],
weights: { pay: 5, price: 3 }, // how much each criterion matters, 0 to 5
};
const result = score({ code: 'coop', name: 'Roaster co-op', scores: { pay: 90, price: 55 } }, ctx);
// result.score is 0 to 100; result.coverage says how much of the weight had facts
In Node without a network, clone the repository and use require('./app/engine.js'); it is the same file. The latest version is always at open-values-engine.mjs.
How a score is worked out
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.
- Each criterion has a weight from 0 to 5, set by the person, and each option has a fact for some criteria, from 0 to 100.
- The score is the weighted average of the facts the option has. A criterion weighted 0 does not count.
- Coverage is the share of the person's total weight that has a fact. Missing facts are not counted as 0: the average is pulled toward 50 by the missing share, so the score is
round(average × coverage + 50 × (1 − coverage)). - When coverage is below 25%, the engine returns no score. An app MUST show such an option as not scored, never as a number.
- A criterion weighted 4 or 5 whose fact is 20 or less caps the score at 49, however good the rest is. A
certifiedcriterion never caps, because its 0 means no label was found, which is missing paperwork, not harm. - An option that breaks one of the person's hard rules, such as an allergen, is left out and gets no score.
The worked formula on the front page runs this engine live; change a weight there and watch each rule act.
A worked example
Four made-up coffees, weighted fair pay 5, price 3 and Fairtrade label 2. These numbers were computed by the engine when this page was built.
| Option | Facts | Score | Coverage | Why |
|---|---|---|---|---|
| Roaster co-op | pay 90, price 55, label 100 | 82 | 100% | weighted average, every fact known |
| House blend | pay 60, price 85 | 66 | 80% | weighted average, pulled toward 50 for the missing facts |
| Certified budget brand | pay 18, price 95, label 100 | 49 | 100% | capped at 49 by Fair pay (18) |
| New brand | price 70 | 56 | 30% | weighted average, pulled toward 50 for the missing facts |
What it exports
| Name | What it does |
|---|---|
score(option, ctx) | The score of one option for one person's weights, with its coverage, the criteria that moved it most, and any cap. Returns null when the option is left out or has too few facts. |
verdict(option, ctx) | The score plus a plain fit label, the fact given as its reason, and a band for each criterion. |
passportApply(passport, map, base) | Turns a person's values file into weights for one app's criteria, and lists the values that app has no place for. |
passportFrom(weights, ...) | Writes a values file from an app's own weights. |
mergePassports(files, name) | Adds up several people's values files into one group file, keeping how far apart they are on each value. |
buildSlate(passport, lens, opts) | Applies a group's values to a facts file and returns the options to use and to move away from, each with its reason. |
mergeLens(lens, patches) / diffLens(a, b) | Applies change files to a facts file, or works out the change file between two versions. |
lensHash(lens) | The fingerprint of a facts file, so a change file can say which version it was made for. |
Also exported, for the sites' own use: THEMES, KEY2THEME, themeDefaults, weakestAxis, allergenStatus, allergenDecision, bandFill, provOf, UNIVERSAL, forkLens, lensFromRatings, signature, sigDistance, analogues, buildGraph, edgesHash, mergeGraph, WEAVE_CONTEXT, toJSONLD, indexMatch, runIndex, twinOf.