5. Data Model
5.1 Top-Level Structure
A UEARM v0.1 document MUST contain the following top-level fields:
| Field | Type | Required | Description |
schema_version | String | Yes | UEARM schema version |
action_id | String | Yes | Unique economic-action identifier |
created_at | Date-time | Yes | Creation timestamp |
identity | Object | Yes | Initiating entity and provenance |
economic_action | Object | Yes | Requested economic operation |
delegated_authority | Object | Yes | Authority grant and scope |
policy | Object | Yes | Applicable policy references |
execution_context | Object | Yes | Relevant execution environment |
governance | Object | Yes | Governance decision |
execution | Object | Yes | Current execution state |
evidence | Array | Yes | Evidence records |
outcome | Object | Yes | Current outcome representation |
extensions | Object | No | Namespaced implementation extensions |
5.2 Identity and Provenance
The "identity" object MUST contain:
"initiator_id""initiator_type""request_id"
The initiator type MUST identify the relevant category, such as:
HUMANAI_AGENTORGANIZATIONSYSTEM
An implementation SHOULD preserve the provenance of any delegated request and MUST NOT treat an unverified identity assertion as independently authenticated identity.
5.3 Economic Action
The "economic_action" object MUST contain:
"action_type""resource""parameters"
The initial action categories are:
PROCUREMENTFINANCIAL_TRANSFERCAPITAL_ALLOCATIONPAYMENT_INITIATIONRESOURCE_ALLOCATIONCONTRACTUAL_COMMITMENT
Additional action types MAY be introduced through documented extensions or a later specification revision.
The "resource" field identifies the economic resource, account, contract, asset, or other relevant object.
5.4 Economic Parameters
Where an action involves monetary values, the implementation MUST represent the amount using a decimal string.
Example:
"amount": "15000.00"
The following representation is NOT RECOMMENDED:
"amount": 15000.00
The use of decimal strings avoids relying on binary floating-point arithmetic for financial values.
A monetary amount MUST be associated with an explicit currency code.
For v0.1, currency codes SHOULD use the applicable ISO 4217 alphabetic code.
The implementation MUST distinguish:
- Requested amount.
- Authorized maximum amount.
- Reserved amount, if applicable.
- Executed amount.
- Settled amount, if independently established.
These values MUST NOT be treated as interchangeable.
5.5 Delegated Authority
The "delegated_authority" object MUST identify:
- Authority grant identifier.
- Granting principal.
- Authorized agent.
- Permitted action types.
- Monetary limit, where applicable.
- Currency, where applicable.
- Validity interval.
- Current authority status.
An authority grant SHOULD include a reference to the source document or record establishing the delegation.
An implementation MUST verify that the authority grant covers the requested action and its relevant economic parameters.
An authority grant that permits procurement MUST NOT automatically be interpreted as permitting financial transfers.
5.6 Policy and Constraints
The "policy" object MUST identify the applicable policy references.
Where a policy decision is made, the implementation SHOULD preserve:
- Policy identifier.
- Policy version.
- Evaluation timestamp.
- Evaluation context reference.
- Decision or evaluation result.
A policy reference alone does not establish that a policy was successfully evaluated.
5.7 Execution Context
The "execution_context" object SHOULD include:
- Environment identifier.
- Execution system identifier.
- Region or jurisdiction reference, where relevant.
- Context timestamp.
- Concurrency or transaction context reference.
Context information MUST be limited to what is necessary for the action and its governance requirements.
5.8 Governance Decision
The "governance" object MUST include:
- Decision identifier.
- Decision value.
- Decision timestamp.
- Decision reason.
The initial decision values are:
An ADMIT decision MUST be bound to the action and authority evaluated.
A change to material action parameters MUST trigger a new authorization evaluation.
An ADMIT decision MUST NOT be interpreted as proof that execution has occurred.
5.9 Execution State
The "execution" object MUST contain:
- Current state.
- Last state-transition timestamp.
It SHOULD also preserve:
- Execution attempt identifier.
- Idempotency key.
- Executor identifier.
- Cancellation status.
- Execution receipt reference.
A system MUST maintain an auditable history of state transitions, even when the top-level object only exposes the latest state.
5.10 Evidence and Verification
Each evidence record SHOULD contain:
- Evidence identifier.
- Evidence type.
- Evidence source.
- Capture timestamp.
- Related event or transaction identifier.
- Integrity reference, where available.
Evidence types may include:
COMMAND_RECORDAUTHORIZATION_RECORDPOLICY_DECISIONEXECUTION_RECEIPTSYSTEM_ACKNOWLEDGEMENTSETTLEMENT_CONFIRMATIONSTATE_TRANSITIONCANCELLATION_RECORD
The implementation MUST distinguish between:
- 1. Evidence captured.
- 2. Evidence validated for integrity.
- 3. Evidence independently verified for the intended claim.
A record marked as captured MUST NOT automatically be marked as verified.
5.11 Outcome
The "outcome" object MUST represent the latest known outcome.
Initial outcome values:
PENDINGCOMPLETEDPARTIALLY_COMPLETEDREJECTEDFAILEDCANCELLEDEXPIREDUNRESOLVED
An outcome SHOULD identify the evidence supporting its classification.
A COMPLETED execution state does not necessarily establish a COMPLETED settlement outcome.
6. JSON Schema v0.1
The following schema defines the initial structural contract.
It uses JSON Schema Draft 2020-12.
The schema validates structure and basic field constraints. It does not replace application-level validation of authority, policy, state transitions, or economic semantics.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://ouamarkom.com/spec/uearm/0.1/schema.json",
"title": "UEARM Economic Action",
"description": "Proposed Unified Economic Action Representation Model v0.1",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"action_id",
"created_at",
"identity",
"economic_action",
"delegated_authority",
"policy",
"execution_context",
"governance",
"execution",
"evidence",
"outcome"
],
"properties": {
"schema_version": {
"type": "string",
"const": "0.1"
},
"action_id": {
"$ref": "#/$defs/identifier"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"identity": {
"type": "object",
"additionalProperties": false,
"required": [
"initiator_id",
"initiator_type",
"request_id"
],
"properties": {
"initiator_id": {
"type": "string",
"minLength": 1
},
"initiator_type": {
"type": "string",
"enum": [
"HUMAN",
"AI_AGENT",
"ORGANIZATION",
"SYSTEM"
]
},
"request_id": {
"$ref": "#/$defs/identifier"
},
"provenance_ref": {
"type": "string"
}
}
},
"economic_action": {
"type": "object",
"additionalProperties": false,
"required": [
"action_type",
"resource",
"parameters"
],
"properties": {
"action_type": {
"type": "string",
"minLength": 1
},
"resource": {
"type": "object",
"required": [
"resource_type",
"resource_id"
],
"properties": {
"resource_type": {
"type": "string"
},
"resource_id": {
"type": "string"
}
},
"additionalProperties": false
},
"parameters": {
"type": "object",
"minProperties": 1
},
"requested_amount": {
"$ref": "#/$defs/money"
},
"beneficiary_id": {
"type": "string"
}
}
},
"delegated_authority": {
"type": "object",
"additionalProperties": false,
"required": [
"grant_id",
"granting_principal",
"authorized_agent",
"permitted_action_types",
"status",
"valid_from",
"valid_until"
],
"properties": {
"grant_id": {
"$ref": "#/$defs/identifier"
},
"granting_principal": {
"type": "string",
"minLength": 1
},
"authorized_agent": {
"type": "string",
"minLength": 1
},
"permitted_action_types": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
}
},
"maximum_amount": {
"$ref": "#/$defs/money"
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"REVOKED",
"EXPIRED",
"SUSPENDED"
]
},
"valid_from": {
"type": "string",
"format": "date-time"
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"authority_reference": {
"type": "string"
},
"revocation_reference": {
"type": "string"
}
}
},
"policy": {
"type": "object",
"additionalProperties": false,
"required": [
"policy_ids"
],
"properties": {
"policy_ids": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"policy_version": {
"type": "string"
},
"evaluation_reference": {
"type": "string"
}
}
},
"execution_context": {
"type": "object",
"additionalProperties": false,
"required": [
"environment_id",
"execution_system_id"
],
"properties": {
"environment_id": {
"type": "string"
},
"execution_system_id": {
"type": "string"
},
"region": {
"type": "string"
},
"context_reference": {
"type": "string"
}
}
},
"governance": {
"type": "object",
"additionalProperties": false,
"required": [
"decision_id",
"decision",
"decided_at",
"reason_code"
],
"properties": {
"decision_id": {
"$ref": "#/$defs/identifier"
},
"decision": {
"type": "string",
"enum": [
"ADMIT",
"REJECT",
"ESCALATE"
]
},
"decided_at": {
"type": "string",
"format": "date-time"
},
"reason_code": {
"type": "string"
},
"authority_snapshot_ref": {
"type": "string"
},
"policy_evaluation_ref": {
"type": "string"
}
}
},
"execution": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"updated_at"
],
"properties": {
"state": {
"type": "string",
"enum": [
"CREATED",
"PENDING",
"AUTHORIZED",
"REJECTED",
"EXECUTING",
"PARTIALLY_EXECUTED",
"COMPLETED",
"FAILED",
"CANCEL_REQUESTED",
"CANCELLED",
"EXPIRED"
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"attempt_id": {
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"executor_id": {
"type": "string"
},
"executed_amount": {
"$ref": "#/$defs/money"
},
"cancel_reference": {
"type": "string"
}
}
},
"evidence": {
"type": "array",
"items": {
"$ref": "#/$defs/evidence"
}
},
"outcome": {
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"PENDING",
"COMPLETED",
"PARTIALLY_COMPLETED",
"REJECTED",
"FAILED",
"CANCELLED",
"EXPIRED",
"UNRESOLVED"
]
},
"settled_amount": {
"$ref": "#/$defs/money"
},
"outcome_reference": {
"type": "string"
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"verification_reference": {
"type": "string"
}
}
},
"extensions": {
"type": "object"
}
},
"$defs": {
"identifier": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"money": {
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
}
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"evidence_id",
"evidence_type",
"source",
"captured_at"
],
"properties": {
"evidence_id": {
"$ref": "#/$defs/identifier"
},
"evidence_type": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"minLength": 1
},
"captured_at": {
"type": "string",
"format": "date-time"
},
"event_reference": {
"type": "string"
},
"integrity_reference": {
"type": "string"
},
"verification_status": {
"type": "string",
"enum": [
"NOT_VERIFIED",
"INTEGRITY_CHECKED",
"INDEPENDENTLY_VERIFIED",
"REJECTED"
]
}
}
}
}
}
6.1 Schema Validation Requirements
An implementation MUST:
- 1. Validate incoming documents against the declared schema version.
- 2. Reject documents with missing required fields.
- 3. Reject invalid data types and enum values.
- 4. Reject malformed monetary amounts.
- 5. Reject duplicate property names at the JSON parsing boundary.
- 6. Apply semantic validation after structural validation.
- 7. Document its handling of unsupported schema versions.
The "format" keyword in JSON Schema may be treated as an annotation rather than an enforced assertion by some validators. Therefore, implementations MUST explicitly validate timestamps and other critical formats in their application-level validation layer.