The Judgment Pack field guide

This is a plain-language companion to the normative specification. It walks through every part of a Judgment Pack document so that a newcomer can read one, write one, and understand what each field means and does not mean. It is written for authors, reviewers, implementers, and anyone evaluating whether the format fits their work.

What the name means

A Judgment Pack is a portable document that describes a decision: the question being asked, the evidence that may bear on it, the possible results, the rules and exceptions that connect evidence to a result, and how uncertain or out-of-scope situations are handed off. It is a self-contained JSON file that can be inspected, versioned, and moved between systems.

A few terms recur throughout:

• Core is the base representation described here. It deliberately excludes profiles and extensions that a later specification may layer on top.
• 0.1.0-draft is the exact experimental draft this guide describes. It is a research preview and may change in incompatible ways.
• JPS is shorthand for the Judgment Pack Specification, the body of normative prose and schema that defines the format.

The single most important framing: this draft standardizes documents, not decision execution. It defines what a valid Judgment Pack document looks like and what its fields mean. It does not define a portable engine that reads a pack and returns a decision.

Normative words

The specification uses the requirement keywords from BCP 14, and they carry their special meaning only when written in all capitals:

Lower-case "must", "should", or "may" in this guide are ordinary English, not requirements.

Several other terms have precise senses in JPS:

• Normative — text or schema that determines conformance. A conformance claim must satisfy it.
• Informative — text that explains or experiments. It never determines conformance.
• Carrier — the serialized JSON text itself, as bytes and characters.
• Structural — the permitted shape of the document and the permitted forms of each value.
• Semantic — identifiers, references, and cross-field relationships between values.
• Evaluator — software that reads a pack, applies its conditions to runtime facts, and produces a result.
• Runtime facts — the external input supplied at evaluation time, against which conditions are tested.
• Handoff — passing a case to a person, queue, or system when the pack escalates or does not resolve.

The three conformance levels

This draft defines conformance for documents at three cumulative levels. Each level assumes the one before it.

• Carrier-conforming — the file is complete, valid JSON per RFC 8259, has no duplicate member names within any object, and is not silently truncated. A reader that hits a resource limit must fail explicitly rather than process only the part it managed to read.
• Structurally conforming — the document also passes the JSON Schema, including the format assertions. In JPS these format checks are required, not advisory: id must be an absolute URI, source.publishedAt must be an RFC 3339 full date, and every createdAt / reviewedAt must be an RFC 3339 date-time.
• Semantically conforming — the document is also internally coherent: local ids are unique within their collections, every reference resolves to exactly one object of the correct kind, every declared required extension is satisfied, and the cross-field rules in the prose hold.

JSON punctuation

A Judgment Pack is ordinary JSON. If the notation is unfamiliar, this is the whole vocabulary:

Two practical notes on numbers. JSON numbers are discouraged for business quantities whose exact decimal identity matters, because they can lose precision. And the operands of ordered comparisons in a condition are decimal strings, such as "5000", not JSON numbers — see JSON Pointer and decimal strings.

JSON has no comments, no trailing commas, and no NaN or Infinity; any of these makes the text invalid. Member names within a single object must be unique.

Root fields

The document is a single JSON object. These are its members:

No other member is allowed at the root; an unrecognized name makes the document invalid. Array order is preserved for authoring and display, but it never sets rule priority.

Version tokens

Two version fields describe different things and move independently:

• specVersion names which specification the document follows. In this draft it is always the exact string 0.1.0-draft.
• version names which revision of this pack you are looking at. It matches ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ — three dot-separated non-negative integers with no leading zeros.

Local ids and references

Objects inside a pack — outcomes, rules, evidence requirements, sources, exceptions — carry a local id. Every id matches:

^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$

Read token by token: it starts with one lowercase letter ([a-z]); continues with any lowercase letters or digits ([a-z0-9]*); then allows any number of hyphen-joined groups, where each group is a hyphen followed by one or more lowercase letters or digits ((?:-[a-z0-9]+)*). In plain terms: lowercase, starts with a letter, words joined by single hyphens, no leading or trailing hyphen, no underscores, no capitals.

Local ids are meaningful only inside a single pack version. They are not globally unique, and no meaning may be inferred from how one is spelled: manual-review and escalate carry weight only because other fields point at them, not because of the words. This draft has no imports and no remote references — every reference resolves within the one document.

Core objects

Decision

Both intent and question are non-empty human-readable strings. The decision object must not embed prompts or executable host-language code — it describes a decision, it does not script one.

Evidence requirements

Each element of evidenceRequirements declares an input the decision may depend on.

The optional kind is one of:

kind is descriptive only. It does not prove that evidence is authentic, sufficient, or actually supplied.

Sources

Each element of sources records provenance the author supplies.

A locator is an object with a kind and a value:

A citation, when present, must contain both a location and an excerpt. A locator is not fetched during validation and is not evidence that the source exists, that the excerpt is accurate, or that its license permits a given use.

Outcomes

outcomes lists the possible results, and there must be at least two.

An outcome is a declared result, not an authorization to perform any external action. Carrying it out is outside Core.

Rules

rules lists one or more rules, each connecting a condition to an outcome.

onUnknown records what the author intends when the condition cannot be determined:

• ignore — the rule supplies no candidate outcome, and it does not block resolution. Crucially, this does not turn an unknown result into false; it simply stands aside.
• escalate — an unknown result blocks resolution and asks for a handoff.

There is no rule-priority field, and array order carries no priority meaning.

Exceptions

exceptions describes typed departures from the ordinary rules.

The effect chooses which of targetRule and outcome are allowed:

Escalation

The optional escalation object records where a case should be handed off and why.

The trigger tokens are:

The target object has a kind — human-role, queue, or system — and a name. The escalation object records handoff intent, not delivery: it does not prove a handoff happened, and Core defines no delivery, routing, or authorization behavior.

Metadata

The optional metadata object carries self-asserted authorship and review information. None of its members are individually required.

Each entry in reviews records a reviewer, a reviewedAt date-time, a disposition of approved, changes-requested, or rejected, and an optional note.

The condition language

A condition appears in applicability, in each rule's when, and in each exception's when. Every condition is exactly one of five shapes, distinguished by its op member.

Literal — a fixed Boolean.

{ "op": "literal", "value": true }

The value must be true or false.

all / any — logical combinations.

{ "op": "all", "conditions": [ { "op": "literal", "value": true } ] }

The conditions array is non-empty and holds nested conditions. Use all for conjunction and any for disjunction.

not — negation of a single nested condition.

{ "op": "not", "condition": { "op": "literal", "value": false } }

fact — a comparison against a runtime-supplied facts document.

{ "op": "fact", "path": "/expense/amount", "operator": "greater-than", "value": "5000" }

• path is an RFC 6901 JSON Pointer selecting a value from the facts document.
• operator is one of the operators below.
• value is the operand. For ordered comparisons it is a decimal string; for in it is a non-empty array; for equality it may be any JSON value.

Equality is type-preserving: the string "1", the number 1, and the Boolean true are all distinct, and there is no coercion between JSON types. Array equality is order-sensitive; object equality ignores member order. The ordered operators (greater-than and friends) have a valid representation in the schema, but this draft does not define a portable ordering for their decimal-string operands — structural acceptance of an ordered condition does not imply that any two evaluators would order the values the same way.

evidence-present — checks whether a declared evidence requirement was supplied.

{ "op": "evidence-present", "evidenceRequirement": "receipt" }

The evidenceRequirement names a declared requirement's id.

How a pack would be evaluated (informative, experimental)

Everything in this section is a design experiment recorded so that reviewers can compare notes on it. The allowed shapes of conditions remain normative through the schema, but the results and the algorithm below do not determine conformance and may change.

Three-valued conditions. In the experiment a condition produces true, false, or unknown.

Evidence presence is true when the runtime explicitly associates at least one supplied item with the named requirement; false when a complete evidence manifest is available and associates none; and unknown when the runtime cannot tell whether the manifest is complete. This draft defines no evidence-manifest interchange format.

Result and reason tokens. The experiment distinguishes three result kinds: an outcome result naming exactly one declared outcome; a not-applicable result (which is not an outcome); and an unresolved result carrying one or more reasons. The reason vocabulary matches the escalation triggers — not-applicable, missing-required-evidence, unknown, conflict, no-match — plus a separate exception-escalation reason that marks a direct request from a true escalate exception rather than a trigger-selected one. Reasons form a de-duplicated set with no priority order.

Experimental evaluation order. Roughly, an evaluator would:

1. Test applicability (an omitted applicability counts as true). If false, stop with not-applicable; if unknown, stop unresolved with reason unknown.
2. Inspect required evidence, recording missing-required-evidence for any that is absent.
3. Evaluate exceptions and combine their effects: suppress-rule effects union their targets; force-outcome effects agree only if they name the same outcome; escalate effects take precedence and record exception-escalation.
4. Stop unresolved if required evidence is missing, an exception is unknown with onUnknown: escalate, forced outcomes conflict, or an exception directly requests escalation.
5. Otherwise honor a single compatible forced outcome, or else evaluate the unsuppressed rules.
6. Collect the outcomes of true rules as candidates; an unknown rule with onUnknown: escalate records unknown and blocks, while onUnknown: ignore contributes nothing and does not block.
7. If true rules name more than one distinct outcome, record conflict and stop unresolved.
8. Return the single candidate if there is one; otherwise use fallbackOutcome if present; otherwise stop unresolved with reason no-match.

Array order and lexical id order never break a tie in this experiment. onUnknown: escalate blocks otherwise compatible outcomes; onUnknown: ignore never rewrites an unknown into false and never erases it from a trace.

JSON Pointer and decimal strings

A fact.path is a JSON Pointer matching:

^(?:/(?:[^~/]|~0|~1)*)*$

• The empty string selects the whole facts document.
• Each / begins a new segment.
• ~1 means a literal / inside a segment, and ~0 means a literal ~.
• An unescaped ~ (one not followed by 0 or 1) is invalid.

For example, /expense/amount selects the amount member of the expense object.

The operand of an ordered comparison is a decimal string matching:

^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$

These are strings, not JSON numbers. The draft defines only the lexical grammar; it does not define scale, units, cross-unit conversion, or ordering for these values.

Extensions

The extensions object maps reverse-domain names to arbitrary JSON values:

{
  "extensions": {
    "com.example.review-policy": { "minReviewers": 2, "quorum": "unanimous" }
  }
}

Extension names follow a fixed pattern: the first segment is lowercase and alphanumeric and starts with a letter (no hyphens); there is at least one period; each later segment starts with a lowercase letter and may contain lowercase letters, digits, and hyphens; and no name may begin with the reserved prefix org.judgmentpack..

An optional extension must not change Core semantics. Consumers should preserve optional extensions when they round-trip a document, but they may otherwise ignore them.

A required extension is any name listed in metadata.requiredExtensions. Every listed name must also appear as a key in some extensions object in the document. A consumer that lacks a listed capability must report the document as structurally readable but not fully interpretable; it must not silently ignore a required extension.

Reading the JSON Schema

The normative schema is written in JSON Schema Draft 2020-12. This vocabulary is enough to read it:

What the draft leaves undefined

0.1.0-draft deliberately stops at document representation and validity. It does not define:

• evaluator conformance;
• a portable serialized decision-result format;
• portable ordered-decimal comparison;
• units or conversions between them;
• an evidence-manifest interchange format;
• authentication or signatures;
• the authority of an author or reviewer;
• imports or remote references;
• rule priority;
• automatic fetching of sources;
• authorization to execute an outcome; or
• delivery guarantees for escalation.

This boundary is the point, not an oversight. JPS defines a portable representation and a document-validity model; it is not a policy-execution engine.

Next

• Read the normative specification for the authoritative model and conformance requirements.
• Browse the schema field reference for the machine-readable structural constraints.
• Study a worked example — a complete, validated document.