OpenETR CLI JSON Model¶
This specification describes the JSON output model for the openetr command line interface.
The JSON model is intended for machine-readable processes that need to issue, query, verify, or route OpenETR records without parsing human console text.
Examples include:
- workflow engines
- service wrappers
- REST API adapters
- agentic tools
- CI or batch jobs
- document-management systems
- warehouse receipt systems
- trade finance platforms
- verifier and recognition services
Status¶
Draft.
This document reflects the current reference CLI direction. The JSON model should be treated as a reference component contract, not as the Nostr protocol wire format itself.
The signed event wire format is specified separately in OPENETR_NOSTR_WIRE_FORMAT_SPEC.md.
Design Goal¶
The CLI JSON model exists so that another process can call openetr, inspect a single JSON document, and decide what to do next.
The design goals are:
- emit valid JSON on successful machine-readable command paths
- avoid prompts in JSON mode
- preserve normal shell exit status semantics
- expose signed event evidence without requiring text parsing
- separate command success from verifier-policy warnings
- include enough data for another process to continue a workflow
- avoid leaking private key material
Human-readable output remains the default. JSON mode is opt-in through --json.
Relationship To The Wire Format¶
OpenETR events are Nostr events.
The Nostr event is the cryptographically signed evidence.
The CLI JSON output is a view over:
- local command inputs
- resolved OpenETR configuration
- signed Nostr events
- relay query results
- derived graph summaries
- warning or guard annotations
The JSON output does not replace the signed event. It is not itself the source of truth.
A verifier should treat JSON output as a convenient evidence package produced by the reference component. Where correctness matters, it should still rely on the included raw event data, event ids, signatures, tags, authors, and policy annotations.
JSON Invocation¶
Commands that support machine-readable output expose:
openetr <command> --json
Examples:
openetr issue examples/mlwr-20260713.pdf --json
openetr query examples/mlwr-20260713.pdf --json
openetr encumber examples/mlwr-20260713.pdf --beneficiary lender --json
openetr transfer initiate examples/mlwr-20260713.pdf --transferee consignee --json
JSON mode should not ask an interactive confirmation question. If a guard would normally ask the user what to do, JSON mode should return a structured guard response and exit non-zero unless an explicit override such as --force is supplied.
Response Envelope¶
Every JSON-capable command should emit one top-level JSON object.
The common top-level fields are:
| Field | Meaning |
|---|---|
ok |
Boolean command result. true means the command completed its requested operation. false means the command was blocked, rejected, or failed in a structured way. |
command |
CLI command surface that produced the response, such as issue, query, issue-etr, or query-etr. |
reason |
Machine-readable reason code when ok is false. |
warning |
Human-readable warning summary for a guard or policy warning. |
warnings |
Array of structured warning objects when the command succeeds but has policy or graph annotations. |
digest |
Hex object digest where applicable. |
object_id |
Bech32 OpenETR object identifier where applicable. |
digest_source or source |
Source file path when the command was invoked with a local file. |
relays |
Relay list used by the command. |
The envelope is intentionally simple so shell, service, and agent callers can branch on ok, reason, and warnings[].code.
Exit Status¶
JSON mode preserves shell semantics.
Recommended behavior:
- exit
0whenokistrue - exit non-zero when
okisfalse - do not rely on warning presence alone to set a non-zero exit status
Warnings mean the command completed but discovered information a verifier or policy should inspect.
For example, query --json may return ok: true while also reporting multiple Anchor Events in warnings.
Structured Guard Responses¶
A guard is a command-level condition that blocks or asks for confirmation before continuing.
In human mode, a guard may print a warning and prompt.
In JSON mode, a guard should return structured JSON and avoid prompting.
Example duplicate origin guard:
{
"ok": false,
"command": "issue",
"reason": "duplicate_origin_event",
"digest": "2976895f610a8e928249f365827c2fd385d2c7d71da0e4d3bf47845f8dcbdd20",
"object_id": "nobj199mgjhmpp28f9qjf7djcylp06wza937hrkswf5alg7z9lrwtm5sqyenss3",
"existing": {
"count": 1,
"same_author": true,
"latest_event_id": "e8f9858243640ece19fb346de346d30ed1d8e6c835a04a20a480f7e295f69a73",
"latest_issuer_npub": "npub1..."
},
"hint": "Re-run with --force to publish another Anchor Event for this object."
}
A machine process can then decide whether to stop, query the existing record, route to human review, or intentionally re-run with --force.
Successful Publish Responses¶
A successful publish command should include:
ok: trueevent_idkindpubkeyandpubkey_hexobject_idanddigestwhere applicable- signed event
tags - event
content - raw signed
event - relay acknowledgement information when available
- post-publish query or verification information when available
Example shape:
{
"ok": true,
"command": "issue",
"event_id": "c70f3d7b8b3d3283b423e68d88fba49750c8795bfd13bd084ec31370e7de8e46",
"kind": 1415,
"object_id": "nobj199mgjhmpp28f9qjf7djcylp06wza937hrkswf5alg7z9lrwtm5sqyenss3",
"digest": "2976895f610a8e928249f365827c2fd385d2c7d71da0e4d3bf47845f8dcbdd20",
"verification": {
"matched_object_filter": true,
"exact_event_returned": true
}
}
Relay acknowledgement data may be absent even when the event is successfully retrievable. A post-publish query that returns the exact event is often the stronger evidence for caller workflows.
Query Responses¶
query --json returns an object-centric view of the OpenETR graph. query-etr --json remains available as a compatibility alias.
The top-level response identifies the command, object digest, object id, relays, and source. The result object contains the graph view.
Important result fields include:
| Field | Meaning |
|---|---|
origin_kind |
Compatibility field name for the Anchor Event kind, currently 1415. |
control_event_kind |
Compatibility field name for the Evidence Event kind, currently 1416. |
relay_filter |
Anchor Event query filter. |
transfer_filter |
Evidence Event query filter. |
count |
Number of Anchor Events returned for the object query. |
origin_event_count |
Explicit count of Anchor Events found. |
initial_event |
Selected Anchor Event used as the initial event for the displayed candidate state. |
origin_events |
All Anchor Events returned for the object. |
transfer_groups |
Evidence Event groups linked by e references. |
summary_control_chains |
Human-readable chain summaries for compact display. |
lifecycle_state |
Candidate lifecycle state derived by the reference component. |
current_controller |
Candidate current controller derived by the reference component. |
encumbrance_summary |
Counts of encumbrance, discharged, and outstanding encumbrance events. |
outstanding_encumbrances |
Structured outstanding encumbrance items. |
warnings |
Structured warning annotations. |
The query result is deliberately evidentiary. It should not be treated as a final legal conclusion by itself.
Verification Results¶
Machine-readable verification should expose independent result dimensions
rather than a universal valid field.
Recommended status values are:
validinvalidunverifiableconflictingabsentnot_evaluatednot_applicable
An implementation may initially expose only the dimensions it evaluates, but it should not use omission to imply success. Each evaluated dimension should identify its status, basis, and relevant evidence identifiers.
Example:
{
"verification_results": {
"artifact_integrity": {"status": "valid", "algorithm": "sha256"},
"event_authenticity": {"status": "valid", "event_ids": ["<event-id>"]},
"graph_continuity": {"status": "valid"},
"history_continuity": {"status": "not_evaluated"},
"source_consistency": {"status": "unverifiable"},
"transition_validity": {"status": "valid", "policy": "openetr-baseline@1"},
"retrieval_coverage": {"status": "unverifiable"},
"temporal_proof": {"status": "absent"},
"observation_attestation": {"status": "absent"},
"monitoring_status": {"status": "not_evaluated"},
"actor_recognition": {"status": "not_evaluated"},
"system_reliability": {"status": "not_evaluated"}
}
}
The top-level ok field continues to describe command execution. It does not
mean that every verification dimension is valid or that the resulting state
has external legal effect.
Retrieval Observations¶
Where relay clients expose retrieval information, JSON output should preserve observations per relay or repository. A useful shape is:
{
"retrieval": {
"status": "unknown_completeness",
"sources": [
{
"source": "wss://relay.example",
"status": "authentication_required",
"events_returned": 4,
"protocol_hints": ["auth"]
}
]
}
}
Recommended retrieval statuses include complete_for_source,
more_available, authentication_required, and unknown_completeness.
complete_for_source is scoped to the matching stored records reported by
that source. It is not a claim that the global OpenETR evidence set is
complete.
Historical State Results¶
Where a command or API supports historical state derivation, the JSON result should identify the exact evidence and rules used. A useful shape is:
{
"historical_state": {
"terminal_event_id": "<event-id>",
"basis_event_ids": ["<anchor-id>", "<event-id>"],
"policy": "openetr-baseline@1",
"evidence_sources": ["wss://relay.example"],
"retrieval_scope": "declared_sources",
"competing_event_ids": [],
"completeness": "unknown_completeness",
"state": {"controller": "<npub>", "lifecycle": "active"},
"warnings": []
}
}
This result is evidence-set-relative, rule-set-relative, and path-relative. It must not be interpreted as globally authoritative state at the event's declared timestamp unless separate accepted evidence supports that conclusion.
Event Views¶
Where the JSON response includes an event view, the current model includes:
| Field | Meaning |
|---|---|
event_role |
origin for kind 1415; control for kind 1416. |
action |
Value of the action tag when present. |
action_label |
Display label, such as origin issue, transfer initiate, or encumber. |
action_marker |
Compact graph marker, such as ++, ->, +$, or -$. |
id |
Event id hex. |
event_ref |
Bech32 event reference. |
kind |
Nostr event kind. |
author_hex |
Signer pubkey hex. |
author_npub |
Signer pubkey as npub. |
created_at |
Display timestamp. |
o_values |
Object tag values. |
prior_event_id |
Prior event id from the e tag, if present. |
subject_npub |
Participant from the p tag, if present. |
structured_tags |
Non-core structured tags as name/value views. |
raw_event |
Raw signed Nostr event data. |
The raw_event field is important. It preserves the signed evidence so another process can independently inspect or verify event ids, pubkeys, signatures, content, and tags.
Warnings¶
Warnings are structured annotations. They are not necessarily command failures.
Each warning should include:
| Field | Meaning |
|---|---|
code |
Stable machine-readable warning code. |
severity |
Usually warning; future values may include info or error. |
message |
Human-readable explanation. |
| Additional fields | Warning-specific data. |
Example:
{
"code": "multiple_origin_events",
"severity": "warning",
"origin_event_count": 2,
"event_ids": [
"e8f9858243640ece19fb346de346d30ed1d8e6c835a04a20a480f7e295f69a73",
"c70f3d7b8b3d3283b423e68d88fba49750c8795bfd13bd084ec31370e7de8e46"
],
"selected_initial_event_id": "e8f9858243640ece19fb346de346d30ed1d8e6c835a04a20a480f7e295f69a73",
"selection_basis": "earliest Anchor Event by created_at/id"
}
A verifier policy should inspect warnings and decide what recognition effect to give them.
This aligns with OPENETR_GENERIC_VERIFIER_POLICY.md: policy issues should normally be surfaced as annotations rather than hiding signed evidence.
Policy And Recognition¶
JSON output can say:
- what signed evidence was found
- what the reference component derived as candidate state
- what warnings were detected
- which event was selected as the initial basis for a candidate view
JSON output should not claim final legal effect by itself.
Recognition remains a policy concern.
For example, a downstream verifier may decide that multiple_origin_events is:
- acceptable but logged
- warning-only
- a reason to require human review
- a reason to select a newer Anchor Event
- a reason to refuse recognition
- resolved by an external registry, trust framework, or domain rule
OpenETR's JSON model makes that decision inspectable. It does not force one policy result on every organization.
Privacy And Secret Handling¶
JSON output must not include private signing keys, root nsec values, profile signer secrets, recovery phrases, or other secret key material.
The JSON model may include:
- public
npubvalues - public key hex values
- event ids
- event signatures
- event content
- event tags
- profile metadata already published as Nostr kind
0metadata
This is sufficient for machine-readable workflows without exposing local root or profile secrets.
Agent-Friendly Use¶
An agent or service wrapper should generally:
- run an
openetrcommand with--json - parse stdout as JSON
- check process exit status
- check
ok - branch on
reasonifokis false - inspect
warningseven whenokis true - use
raw_eventand event ids for evidence and audit trails - apply local or domain-specific verifier policy before assigning recognition effect
For example:
ok=falseandreason=duplicate_origin_event: stop or route to review unless the workflow intentionally permits--forceok=trueandwarnings[].code=multiple_origin_events: continue only if the selected verifier policy recognizes one origin basisok=trueandverification.exact_event_returned=true: treat the publish as relay-query verified for workflow purposes
Compatibility Notes¶
The JSON model may evolve as the component matures.
Consumers should prefer stable fields:
okcommandreasonwarnings[].codeevent_idobject_iddigestresult.initial_event.idresult.origin_eventsresult.transfer_groupsresult.current_controllerresult.lifecycle_stateraw_event
Consumers should tolerate additional fields.
Consumers should not depend on object key ordering, display-only chain labels, or exact human-readable message text when a stable code is available.
Non-Goals¶
The JSON model does not:
- replace the Nostr wire format
- define legal effect
- define final recognition policy
- require any particular relay service
- expose private keys
- guarantee that every organization will derive the same recognized state
It is a machine-readable interface to the OpenETR reference component and its current evidence model.