OpenETR Generic Domain Adapter Specification¶
This specification defines the generic role of a domain adapter in OpenETR.
It is intended to make clear what OpenETR does, what a domain adapter does, and what remains outside both in the Recognition Layer.
Status¶
Draft.
Purpose¶
OpenETR is a protocol for deriving consequential state from end-verifiable evidence concerning durable electronic records.
Different domains need different language, data models, validation rules, roles, workflows, and recognition frameworks. A warehouse receipt system should speak warehouse-receipt language. A bill-of-lading system should speak maritime transport language. An Apostille workflow should speak Competent Authority and e-Register language. A Product Passport workflow should speak product, lifecycle, compliance, and evidence language.
The domain adapter is the boundary object between those domain workflows and the generic OpenETR protocol layer.
The design goal is:
Domain adapters make OpenETR useful in a specific domain
without making the OpenETR core specific to that domain.
Layer Model¶
OpenETR systems should keep four layers distinct.
Domain adapter
domain vocabulary, workflows, validation, UI/API, rulebook-specific state
OpenETR protocol layer
Evidence Graph records, evidence records, control graphs, profile signing,
state transition rules, consequential-state derivation
Wire format
signed events, kinds, tags, relays, event ids, object queries
Recognition layer
law, contracts, registries, trust frameworks, institutional policy,
competent authorities, relying-party decisions
The domain adapter sits above OpenETR. It translates domain actions into OpenETR operations and translates OpenETR graph results back into domain language.
What OpenETR Core Does¶
The OpenETR core provides generic Evidence Graph records and state-transition infrastructure.
It defines:
- digest-identified Digital Artifacts
- Anchor records
- evidence records
- linked evidence records
- signed event publication and retrieval
- object-centric graph queries
- control graph traversal
- profile-backed signing
- participant references
- generic lifecycle events
- verifier policy warnings
- candidate state derivation
OpenETR core answers questions such as:
- What object digest is being referenced?
- Which signed events exist for that object?
- Which profile key signed each event?
- How do events link through prior-event references?
- What candidate control graph can be reconstructed?
- What consequential state can be derived under a selected policy?
- What warnings arise from structural or baseline-policy checks?
OpenETR core should remain domain-neutral.
It should not need to know whether the object is a warehouse receipt, bill of lading, Apostille package, Product Passport, health record, certificate, credential, permit, or another controllable record.
What OpenETR Core Does Not Do¶
OpenETR core does not decide:
- legal title
- ownership
- contractual rights
- priority
- protected-holder status
- KYC or AML sufficiency
- regulatory compliance
- public-authority competence
- document-content sufficiency
- cargo-release eligibility
- medical consent validity
- Product Passport regulatory completeness
- Apostille recognition
- whether a relying party must accept a record
It also should not contain:
- complete domain schemas
- jurisdiction-specific legal rules
- carrier-specific bill-of-lading forms
- warehouse-specific receipt templates
- healthcare data models
- Apostille e-Register policy
- product-category delegated-act rules
- local registry account models
Those concerns belong to domain adapters, recognition profiles, external systems, or relying-party policy.
What A Domain Adapter Does¶
A domain adapter presents OpenETR in domain language.
It is responsible for:
- domain vocabulary
- user-facing workflows
- domain API actions
- domain data schemas
- domain-specific validation
- domain-specific status labels
- role mapping
- profile selection and actor mapping
- domain event tags
- linked evidence conventions
- warning presentation
- recognition-input selection
- integration with external systems
- human-readable rendering
The adapter should make a domain workflow feel natural while keeping the underlying control evidence portable.
Examples:
- an MLWR adapter maps "pledge receipt" to
ENCUMBER - an eBL adapter maps "surrender bill of lading" to
REDEEMor an eBL presentation profile - an Apostille adapter maps "attach e-Register reference" to linked evidence
- a Product Passport adapter maps "attach repair evidence" to linked evidence or
ATTEST
What A Domain Adapter Does Not Do¶
A domain adapter does not, by itself, create legal effect.
It should not claim that a signed event automatically satisfies:
- MLETR
- MLWR
- Apostille Convention recognition
- Product Passport regulation
- healthcare consent law
- secured-transactions law
- customs or port rules
- bank policy
- registry rules
- court or agency acceptance
The adapter may implement local policy checks, but those checks are not the same as universal recognition.
The adapter may say:
Under this selected verifier policy, this graph is recognized.
It should not say:
OpenETR itself makes this legally effective everywhere.
Generic Adapter Responsibilities¶
Every domain adapter should define the following.
Domain Scope¶
The adapter should state:
- record types covered
- record types excluded
- applicable domain vocabulary
- intended users
- intended relying parties
- relevant external standards or rulebooks
- recognition assumptions
Digital Artifact Strategy¶
The adapter should define what is hashed.
Possible strategies include:
- final artifact as the Digital Artifact
- canonical structured record as the Digital Artifact
- package or bundle as the Digital Artifact
- public document as the Digital Artifact with linked evidence
- evidence artifact as linked object
The adapter must specify:
- canonicalization rules, if any
- package finalization rules
- digest algorithm
- whether transformations create new objects
- how versions are related
- how generated representations are treated
Domain Roles¶
The adapter should map domain roles to OpenETR participant roles.
Examples:
- warehouse operator -> issuer / obligor / attestor
- receipt holder -> current controller
- carrier -> issuer / obligor
- shipper -> transferor or participant
- consignee -> transferee or relying party
- Competent Authority -> recognized attestor or authority source
- manufacturer -> issuer or attestor
- repairer -> linked-evidence attestor
This mapping should not imply legal authority by itself. Authority must be established by recognition inputs or policy.
Domain Actions¶
The adapter should map domain actions to OpenETR operations.
Generic operations include:
ISSUETRANSFERATTESTENCUMBERDISCHARGEREDEEMTERMINATE- linked evidence creation
- verifier annotation
The adapter should define whether each domain action:
- publishes an OpenETR event
- creates linked evidence
- runs local validation only
- consults recognition inputs
- updates only the domain system
- produces a human-readable representation
Domain Event Tags¶
The adapter should define signed tags needed for domain interpretation.
Common generic tags include:
["domain", "<domain_id>"]["document_type", "<type>"]["record_reference", "<domain_reference>"]["record_description", "<short_description>"]["jurisdiction", "<jurisdiction>"]["version", "<profile_or_record_version>"]
Domain-specific tags should be stable, documented, and machine-readable.
The event content field should remain human-readable context. It should not be the primary machine interface for domain data.
Domain Validation¶
The adapter should define validation rules.
Categories may include:
- field-level validation
- cross-field validation
- conditional validation
- state-based validation
- authorization validation
- external-reference validation
- schema validation
- canonicalization validation
- linked-evidence validation
Validation may occur:
- before event publication
- during graph verification
- during recognition-policy evaluation
- during external-system integration
The adapter should distinguish each stage.
Status Dimensions¶
The adapter should avoid one overloaded status field.
It should define separate status dimensions where the domain requires them.
Examples:
- document lifecycle status
- control status
- regulatory status
- cargo-release status
- registry verification status
- recognition status
- evidence completeness status
- privacy or access status
OpenETR may derive generic control state. The adapter decides how to present domain state.
Linked Evidence Model¶
The adapter should define which artifacts are linked evidence rather than the main Digital Artifact.
Examples:
- inspection reports
- registry responses
- e-Register lookups
- repair records
- certificates
- translations
- shipment data packages
- C2PA-enabled media
- authority credentials
- verifier reports
Linked evidence should remain digest-addressed and independently verifiable where possible.
Recognition Inputs¶
The adapter should identify relevant recognition inputs.
Examples:
- trust registries
- Competent Authority lists
- domain registries
- local allow lists
- KYC providers
- EUDI Wallet credentials
- Verifiable Credentials
- Nostr Web of Trust signals
- TRQP responses
- contracts
- statute or regulation
- institutional policy
The adapter should treat these inputs as recognition context, not base OpenETR truth.
Privacy And Storage¶
The adapter should define what may safely be published.
It should distinguish:
- public event metadata
- private document bytes
- sensitive personal data
- regulated data
- commercial data
- storage location
- relay policy
- retention policy
- redaction rules
OpenETR should not require sensitive content to be published on public relays. Digest-linked evidence can be useful even when the underlying bytes remain in controlled storage.
Generic Domain Adapter Template¶
A domain adapter specification should use this structure unless there is a reason to deviate:
- Status
- Purpose
- Architectural boundary
- Domain model
- Digital Artifact strategy
- Domain roles
- Domain actions and OpenETR mapping
- Suggested event tags
- Validation model
- Status dimensions
- Linked evidence model
- Recognition inputs
- Privacy and storage
- Non-goals
- Recommended roadmap
- Open questions
- References
Adapter Categories¶
OpenETR can support different categories of domain adapter.
Transferable-Record Adapters¶
These adapters use control transfer as a central workflow.
Examples:
- warehouse receipts
- bills of lading
- promissory notes
They commonly map domain actions to ISSUE, TRANSFER, ENCUMBER, DISCHARGE, REDEEM, and TERMINATE.
Non-Transferable Controllable-Record Adapters¶
These adapters focus on issuance, status, authority, evidence, verification, and lifecycle, but may not require transfer of control.
Examples:
- Apostille documents
- Product Passports
- certificates
- permits
- health-record packages
They commonly use ISSUE, ATTEST, linked evidence, warning, replacement, revocation, and verifier-policy annotations.
Evidence-Graph Adapters¶
These adapters focus on associating many evidence artifacts with a primary object.
Examples:
- Product Passport lifecycle evidence
- compliance evidence
- repair history
- audit records
- inspection media
They commonly rely on linked evidence records and attestation events.
Credential-Supported Adapters¶
These adapters use credentials or wallets as authority inputs.
Examples:
- EUDI Wallet-supported authority proof
- Verifiable Credential-backed role proof
- mDL or identity-backed signer recognition
The credential may be the Digital Artifact, linked evidence, or a recognition input.
Validation Versus Recognition¶
Domain adapters should distinguish validation from recognition.
Validation asks:
- Is the data complete?
- Is the event structurally sound?
- Is the action allowed by the local workflow?
- Does the record satisfy the adapter's schema?
- Are required references present?
Recognition asks:
- Will this verifier rely on the event?
- Does the signer have authority?
- Does a law, registry, or institution accept the evidence?
- Is the action legally or commercially effective?
- Does the record satisfy the governing rulebook?
A domain adapter may implement both validation and recognition-policy evaluation, but it should label them separately.
Publication Versus Recognition¶
OpenETR is an open signed-event system.
The fact that an event can be published does not mean that every verifier must recognize it.
Domain adapters should preserve this distinction:
event exists
-> signature and structure can be verified
-> graph can be traversed
-> adapter can interpret domain meaning
-> recognition policy decides effect
This is the practical meaning of:
Transact globally, validate locally.
Non-Goals¶
A generic domain adapter specification should not:
- redefine the OpenETR core wire format
- put domain-specific legal rules into the base protocol
- imply that all domains are transferable records
- require public storage of sensitive documents
- replace official registries or authorities
- claim universal legal effect
- hide policy differences behind cryptographic validity
- make
contentparsing part of the machine contract
Conformance Expectations¶
A domain adapter is conformant with this generic specification if it:
- identifies its Digital Artifact strategy
- maps domain actions to OpenETR operations
- documents its domain tags
- documents its validation stages
- separates technical verification from recognition
- identifies relevant recognition inputs
- defines privacy and storage expectations
- states non-goals and recognition limits
- preserves OpenETR core event semantics
Existing And Candidate Adapters¶
Current or candidate adapters include:
- MLWR warehouse receipts
- electronic bills of lading
- Apostille documents
- Product Passports
- health records
- credentials and attestations
- C2PA-linked media evidence
- secured finance records
Each should be documented as a domain-specific profile or adapter specification that refers back to this generic boundary.
Bottom Line¶
The domain adapter is where OpenETR becomes useful to a real domain.
It is also where OpenETR avoids becoming trapped inside one domain.
The core rule is:
OpenETR records portable signed control and evidence facts.
Domain adapters translate those facts into domain workflows.
Recognition layers decide legal, regulatory, institutional, or commercial effect.