Agreement data standard

The agreement data standard is the common language of Agreements Protocol. It defines the JSON structure used to produce an agreement definition: the shared object that applications render, agents inspect, and execution engines enforce. The standard is maintained in CNSLabs/agreements-standard. Complete examples are available in Simple Agreement and Complex Agreement.

What the standard describes

Use agreement JSON to produce an agreement definition that describes:

human-readable agreement content
participants and participant-backed variables
allowed inputs and authorized issuers
lifecycle states and state transitions
outcomes and optional actions
optional contract references used by runtime validation or actions

The important property is that the agreement definition is data, not custom per-agreement application code. The same definition can be validated by the Agreements API, prepared by SDK helpers, and executed by the onchain execution engine. Because the data standard is separate from any single runtime, the agreement-data layer is where the protocol semantics live. The EVM engine is the first concrete execution engine for those semantics.

Agreement sections

Select a section to see the part of the agreement definition it controls.

Metadata
Variables
Contracts
Content
Execution

metadata identifies the agreement definition and gives downstream tools stable naming, versioning, and template context.

{
  "metadata": {
    "id": "did:example:mou-v1",
    "templateId": "did:template:mou-v1",
    "version": "1.0.0",
    "createdAt": "2024-03-20T12:00:00Z",
    "name": "Grant With Feedback",
    "author": "Agreements Protocol",
    "description": "A human-readable agreement with executable lifecycle rules."
  }
}

variables define the reusable facts, participant roles, types, and validation hints the agreement depends on.

{
  "variables": {
    "partyAName": {
      "type": "string",
      "name": "Party A Name",
      "description": "Legal name of the first party",
      "validation": {
        "required": true,
        "minLength": 1
      }
    },
    "granteeAddress": {
      "type": "address",
      "subtype": "participant",
      "name": "Grantee Wallet"
    }
  }
}

contracts can attach runtime contract references and chain context that actions or validation logic need.

{
  "contracts": {
    "workToken": {
      "description": "The Work Token",
      "address": "0x12be78ca652191616f49420dfa28214bafe9326c",
      "chainId": "59141",
      "abi": "[{\"inputs\":[{\"internalType\":\"address\",\"name\":\"account\"}]}]"
    }
  }
}

content is the human-readable agreement text. It can reference variables so rendered prose and executable data stay aligned.

{
  "content": {
    "type": "md",
    "data": "# SIMPLE GRANT AGREEMENT\n\n**BETWEEN GRANTOR:**\n\n${variables.grantorName} (Grantor)\n\n${variables.granteeName} (Grantee)\n\nThe parties agree to the grant scope, duration, and payment terms."
  }
}

execution defines the execution path: the initial state, allowed inputs, validation conditions, transitions, and optional actions.

{
  "execution": {
    "states": {
      "AWAITING_TEMPLATE_VARIABLES": {
        "name": "Awaiting Template Variables"
      },
      "AWAITING_RECIPIENT_SIGNATURE": {
        "name": "Pending Recipient Signature"
      }
    },
    "initialize": {
      "initialState": "AWAITING_TEMPLATE_VARIABLES"
    },
    "inputs": {
      "grantorData": {
        "type": "VerifiedCredentialEIP712",
        "displayName": "Template Variable Submission"
      }
    },
    "transitions": [
      {
        "from": "AWAITING_TEMPLATE_VARIABLES",
        "to": "AWAITING_RECIPIENT_SIGNATURE",
        "conditions": [{ "type": "isValid", "input": "grantorData" }]
      }
    ]
  }
}

Inputs

Inputs define the valid interactions that can move an agreement forward. An input definition specifies:

the input type
the expected data shape
the authorized issuer
optional display metadata
how submitted data maps into agreement variables or transition conditions

At runtime, an input submission must match the authored input definition and be submitted by an authorized issuer. In the EVM implementation, this authorization is expressed through EIP-712 signed input data. The current examples use VerifiedCredentialEIP712 inputs, which are supported by the current EVM execution engine. Use only input types and subtypes documented for that engine.

How the standard moves through the system

You author agreement JSON as an agreement definition.
The Agreements API validates the agreement definition before deployment context is added.
Deployment supplies live initValues, participant mappings, observers, and signed authorization.
SDK helpers convert the authored definition and deployment values into engine-compatible payloads.
The onchain execution engine stores and enforces the execution path for that deployed agreement instance.

For authoring guidance, see Author Agreement JSON and Validate Agreement Structure.

Start

Author agreements

Deploy and operate

Examples

Reference

What the standard describes

Agreement sections

Inputs

How the standard moves through the system

Start

Author agreements

Deploy and operate

Examples

Reference

Documentation Index

​What the standard describes

​Agreement sections

​Inputs

​How the standard moves through the system

What the standard describes

Agreement sections

Inputs

How the standard moves through the system