Developers

Quickstart, examples, and implementation guidance for JEP.

Quickstart

A JEP event is a signed JSON object. It defines 11 standard top-level fields; six are always required, while the others are conditional, recommended, or optional depending on the event.

Example event

A draft-06-compatible Judgment event. A JEP event defines 11 standard top-level fields. Six are always required; the others are conditional, recommended, or optional depending on the event.

{
  "jep": "1",
  "verb": "J",
  "who": "did:web:alice.example",
  "when": 1702900000,
  "what": {
    "claim": "Approved API integration milestone",
    "subject": "urn:example:integration:123"
  },
  "nonce": "abc123",
  "aud": "did:web:buyer.example",
  "ref": [
    "sha256:3a6eb0790f39ac87c94f3856b2dd2c5d110e6811602261a9a923d3bb23adc8b7"
  ],
  "ext": {},
  "sig": {
    "protected": "eyJhbGciOiJFZERTQSJ9",
    "signature": "base64url-signature-value"
  }
}

Core event fields

jepREQUIRED
Wire-format major version. Use "1" for the current wire format.
verbREQUIRED
Event verb: "J", "D", "T", or "V".
whoREQUIRED
Actor identifier claimed by the event.
whenREQUIRED
Actor-supplied event timestamp in Unix seconds.
whatCONDITIONAL
Claim object, descriptor, or algorithm-tagged digest.
nonceREQUIRED
Replay-protection nonce.
audRECOMMENDED
Intended audience or validation context.
refCONDITIONAL
Typed reference or event-hash reference.
extOPTIONAL
Extension object.
ext_critOPTIONAL
List of critical extension identifiers.
sigREQUIRED
Detached signature container.

Fields inside what, such as claim, subject, scope, result, evidence, and context, are semantic subfields. They are not additional JEP top-level fields.

Signature model

JEP events use detached signatures. The signature field contains the cryptographic signature over the canonical representation of the event payload.

Supported algorithms: Ed25519 (required), ES256 (optional profile).

Validation result

Verification events should include a validation result indicating what level of validation was achieved.

Common levels: syntax, signature, actor-binding, chain-integrity, credential-status, policy-compliance.

Failure codes

When validation fails, verifiers should indicate the failure reason.

INVALID_SYNTAXEvent does not conform to schema
INVALID_SIGNATURESignature verification failed
UNKNOWN_ACTORActor identifier cannot be resolved
EXPIREDEvent timestamp outside acceptable window
CHAIN_BROKENReferenced event not found or invalid
POLICY_VIOLATIONEvent violates profile policy

Conformance

A conformant JEP implementation must support the core event structure, Ed25519 signatures, and canonical JSON serialization.

Resources

IETF Internet-DraftGitHub Repository