> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Agreement data standard

> Understand how the data standard defines agreement definitions: human-readable content, variables, participants, inputs, states, transitions, and execution history.

For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).

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](https://github.com/CNSLabs/agreements-standard). Complete examples are available in [Simple Agreement](/examples/simple) and [Complex Agreement](/examples/complex).

## 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](/system-architecture/on-chain).

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.

<Tabs sync={false} borderBottom={true}>
  <Tab title="Metadata">
    `metadata` identifies the agreement definition and gives downstream tools stable naming, versioning, and template context.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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."
      }
    }
    ```
  </Tab>

  <Tab title="Variables">
    `variables` define the reusable facts, participant roles, types, and validation hints the agreement depends on.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Contracts">
    `contracts` can attach runtime contract references and chain context that actions or validation logic need.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "contracts": {
        "workToken": {
          "description": "The Work Token",
          "address": "0x12be78ca652191616f49420dfa28214bafe9326c",
          "chainId": "59141",
          "abi": "[{\"inputs\":[{\"internalType\":\"address\",\"name\":\"account\"}]}]"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Content">
    `content` is the human-readable agreement text. It can reference variables so rendered prose and executable data stay aligned.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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."
      }
    }
    ```
  </Tab>

  <Tab title="Execution">
    `execution` defines the execution path: the initial state, allowed inputs, validation conditions, transitions, and optional actions.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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" }]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## 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

1. You author agreement JSON as an agreement definition.
2. The Agreements API validates the agreement definition before deployment context is added.
3. [Deployment supplies live `initValues`, participant mappings, observers, and signed authorization.](/workflow/deploy-an-agreement)
4. SDK helpers convert the authored definition and deployment values into engine-compatible payloads.
5. The onchain execution engine stores and enforces the execution path for that deployed agreement instance.

For authoring guidance, see [Author Agreement JSON](/workflow/author-agreement-json) and [Validate Agreement Structure](/workflow/validate-agreement-structure).