Conventions | ERC-8004 pre-v1 (Legacy)

Description

Shared terminology and format conventions for ERC-8004 Offchain Standards

Purpose

This document defines the common conventions, terminology, and data format standards used across all ERC-8004 offchain standard documents in this specification set. It serves as a normative reference for understanding field types, constraints, and validation requirements.

RFC 2119 Key Words

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in all standard documents are to be interpreted as described in RFC 2119.

Summary:

MUST / REQUIRED / SHALL: Absolute requirement of the specification
MUST NOT / SHALL NOT: Absolute prohibition
SHOULD / RECOMMENDED: Valid reasons may exist to ignore, but implications must be understood
SHOULD NOT / NOT RECOMMENDED: Valid reasons may exist to permit, but implications must be understood
MAY / OPTIONAL: Truly optional; implementers can choose to include or omit

Field Type System

All field specifications in standard documents use the following type notation:

JSON Primitive Types

Type	Description	Examples
`string`	UTF-8 text string	`"DataAnalyst Pro"`, `"https://example.com"`
`number`	JavaScript number (integer or float)	`42`, `3.14`, `100`
`boolean`	True or false value	`true`, `false`
`object`	JSON object (key-value pairs)	`{"key": "value"}`
`array`	Ordered list of values	`[1, 2, 3]`, `["a", "b"]`
`null`	Null value	`null`

Constrained Types

When fields have specific constraints, they are documented as:

Type: number
Constraints: uint256, ≥ 0, ≤ 100

Common Constraint Patterns:

uint256: Unsigned 256-bit integer (0 to 2^256-1)
0–100 inclusive: Integer or number in range [0, 100]
≥ 0: Non-negative number
enum: "A" | "B" | "C": One of the specified string values
ISO 8601: ISO 8601 date-time format
CAIP-2: CAIP-2 blockchain identifier format
CAIP-10: CAIP-10 account address format
hex (0x...): Hexadecimal string prefixed with "0x"
URI: Uniform Resource Identifier (https://, ipfs://, ar://, data:)

Type Notation in Tables

Standard documents use tables with the following columns:

Field	Type	Constraints	Description
`fieldName`	`string`	`enum: "A" \| "B"`	Human-readable explanation

Address and Chain Identifiers

CAIP-2: Blockchain ID Format

Specification: CAIP-2

Format: namespace:reference

For EVM chains: eip155:chainId

Examples:

text

eip155:1          → Ethereum Mainnet
eip155:11155111   → Sepolia Testnet
eip155:8453       → Base Mainnet
eip155:84532      → Base Sepolia
eip155:137        → Polygon PoS
eip155:42161      → Arbitrum One
eip155:10         → Optimism

CAIP-10: Account Address Format

Specification: CAIP-10

Format: namespace:chainId:address

For EVM chains: eip155:chainId:0x...

Examples:

text

eip155:1:0x8004a6090Cd10A7288092483047B097295Fb8847
eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
eip155:137:0xABCDEF1234567890ABCDEF1234567890ABCDEF12

Validation Rules:

Address MUST be checksummed (EIP-55) or lowercase
Chain ID MUST be valid for the namespace
Format MUST match exactly namespace:chainId:address

CAIP-10 for Contract Addresses

For referencing smart contracts (e.g., agent registries):

Format: namespace:chainId:contractAddress

Example:

text

eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55

This uses the CAIP-10 format for contract references in the standards.

OASF: Agent Skills and Domains Taxonomy

Overview

Specification: OASF v0.8.0
Full Name: Open Agent Skills Framework

OASF provides a standardized hierarchical taxonomy for describing agent capabilities and application domains.

Skills Format

Format: category/skill_name

Skills describe what agents can do, organized hierarchically.

Examples:

text

analytical_skills/data_analysis
communication_skills/natural_language_processing
creative_skills/content_generation
technical_skills/code_generation

Domains Format

Format: domain_name

Domains categorize agent application areas.

Examples:

text

finance_and_business
healthcare_and_medicine
education_and_training
creative_arts

Usage in Standards

OASF taxonomy is used in Agent Metadata Standard for declaring agent capabilities. See Agent Metadata Standard for detailed endpoint specification.

Timestamp Format

All timestamps in standard documents MUST use ISO 8601 format in UTC timezone.

ISO 8601 Extended Format

Format: YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ

Examples:

text

2025-12-21T14:30:00Z
2025-12-21T14:30:00.123Z

Requirements:

Date separator: - (hyphen)
Date-time separator: T (capital T)
Time separator: : (colon)
Timezone: Z (UTC) REQUIRED
Milliseconds: .sss (OPTIONAL)

Invalid Examples:

text

❌ 2025-12-21 14:30:00        (missing T)
❌ 2025-12-21T14:30:00+08:00  (non-UTC timezone)
❌ 12/21/2025 2:30 PM         (non-ISO format)

Unix Timestamps

In some contexts (e.g., updatedAt field in Agent Metadata), Unix timestamps (seconds since epoch) MAY be used:

Type: number
Constraints: uint, ≥ 0

Example: 1763112328 (represents 2025-12-21 14:30:28 UTC)

When both ISO 8601 and Unix timestamps are acceptable, the standard document will specify clearly.

URI Schemes

All URI fields (e.g., agentURI, feedbackUri, image, endpoint) MUST use one of the following schemes:

Supported Schemes

Scheme	Description	Example	Use Case
`https://`	HTTP Secure	`https://example.com/file.json`	Production APIs, hosted files
`ipfs://`	IPFS Content ID	`ipfs://bafkreiabc...`	Decentralized immutable storage
`ar://`	Arweave Transaction ID	`ar://abc123...`	Permanent decentralized storage
`data:`	Data URI	`data:application/json;base64,ew...`	Inline data embedding

Recommended Minimum Support

Implementations SHOULD support at minimum:

REQUIRED: https://
RECOMMENDED: ipfs://, data:
OPTIONAL: ar://

IPFS URI Format

CIDv0 (legacy):

text

ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

CIDv1 (recommended):

text

ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4

Gateway Translation (informative):

text

ipfs://bafkreiabc...
  → https://ipfs.io/ipfs/bafkreiabc...
  → https://cloudflare-ipfs.com/ipfs/bafkreiabc...

Data URI Format

Syntax: data:[<mediatype>][;base64],<data>

Example (JSON):

text

data:application/json;base64,eyJuYW1lIjoiQWdlbnQifQ==

Example (inline JSON without encoding):

text

data:application/json,{"name":"Agent"}

URI Validation

Implementations MUST:

Validate scheme is supported
Reject relative URIs (e.g., ./file.json, ../data.json)
Reject URIs without scheme (e.g., example.com/file.json)

Implementations SHOULD:

Support scheme-specific validation (e.g., IPFS CID format)
Handle gateway fallbacks for decentralized schemes

Versioning Strategy

Standard Document Versions

Each standard document has an independent version number following Semantic Versioning (SemVer) principles:

Format: MAJOR.MINOR

MAJOR: Incremented for breaking changes (incompatible field changes, removals)
MINOR: Incremented for backward-compatible additions (new optional fields, clarifications)

Version 0.x (Pre-release)

Version 0.x indicates draft status
Breaking changes MAY occur between 0.x versions
Once stable, version advances to 1.0

Version 1.x+ (Stable)

Version 1.x and above follow strict backward compatibility
Breaking changes REQUIRE advancing to next MAJOR version
OPTIONAL fields may be promoted to RECOMMENDED/REQUIRED in MINOR versions with transition period

Document Version Table

Each standard document includes a version table:

Version	Date	Changes
1.0	2025-12-21	Initial stable release
0.2	2025-12-15	Added optional field X
0.1	2025-12-01	Initial draft

Normative vs Non-normative Content

Normative Content

Content that defines requirements and MUST be followed for compliance.

Normative sections include:

Field requirements (MUST, SHOULD, MAY)
Field types and constraints
Validation rules
Format specifications

Non-normative Content

Content that provides informative guidance but does not define requirements.

Non-normative sections are marked with:

Non-normative: This section provides informative guidance and examples. It does not define normative requirements.

Examples of Non-normative Content:

Real-world usage statistics
Implementation recommendations beyond SHOULD/MAY
Design philosophy and rationale
Historical context
Migration suggestions
Extended examples and tutorials

Relationship to EIP-8004

These standard documents are supplementary and non-normative with respect to the official EIP-8004 specification.

Scope Distinction

Aspect	EIP-8004 (Official)	These Standards (Supplementary)
Defines	Smart contract interfaces	Offchain data formats
Scope	Onchain behavior	Offchain metadata schemas
Status	Ethereum EIP process	Community recommendations
Authority	Normative for ERC-8004	Informative guidance
Compatibility	MUST comply	SHOULD adopt for interoperability

Design Goals

Complement, not replace: These standards fill gaps in offchain data formats not covered by EIP-8004
Implementation-agnostic: Any ERC-8004 registry or explorer MAY adopt these formats
Interoperability: Following these standards improves cross-platform compatibility
Flexibility: Allow custom extensions while maintaining core interoperability

Non-normative Status

These standards do not override EIP-8004 requirements
Where conflicts exist, EIP-8004 takes precedence
Implementations MAY use alternative offchain formats
Adoption of these standards is RECOMMENDED but OPTIONAL

Field Specification Format

All core standard documents (Agent Metadata, Feedback, Validation) use consistent field specification tables:

Standard Field Table

Field	Type	Constraints	Description
`fieldName`	`string`	`maxLength: 100`	Human-readable explanation of the field's purpose and usage

Extended Field Specification

For complex fields, specifications include:

Field Name: fieldName
Type: string
Constraints: maxLength: 100, pattern: ^[a-z0-9-]+$
Required: MUST / SHOULD / MAY
Default: (if applicable)

Purpose: High-level description

Validation:

✅ Valid example
❌ Invalid example with error code

Example:

json

{
  "fieldName": "example-value"
}

Unknown Field Handling

Forward Compatibility Principle

To support extensibility and forward compatibility, implementations SHOULD adopt the following behavior for unknown fields:

MUST NOT reject documents containing unknown fields
SHOULD preserve unknown fields when re-serializing data
SHOULD log warnings for unexpected fields (informative, not errors)
MAY ignore unknown fields in processing logic

Custom Extensions

Implementations MAY add custom extension fields using reverse domain notation:

Recommended pattern: x-<domain>-<fieldname>

Examples:

json

{
  "name": "Agent",
  "x-8004scan-internal-id": "abc123",
  "x-mycompany-custom-tag": "value"
}

Constraints:

Extension fields SHOULD use x- prefix
Extension fields MUST NOT conflict with standard field names
Extension fields SHOULD be documented in implementation guides

Content Hashing

When standards reference content hashing (e.g., feedbackHash, requestHash, responseHash), the following applies:

Hash Algorithm

Algorithm: Keccak-256 (Ethereum standard)

Output Format:

Type: bytes32 (onchain)
Type: string with hex (0x...) prefix (offchain references)

Example:

text

0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

Hash Computation

For JSON content:

Serialize JSON with no whitespace (compact form)
Encode as UTF-8 bytes
Compute Keccak-256 hash
Represent as hex string with 0x prefix

Example (informative):

javascript

import { keccak256 } from "ethers";

const data = JSON.stringify({ name: "Agent" });
const hash = keccak256(toUtf8Bytes(data));
// Result: 0x...

MIME Types

When specifying file types (e.g., in Attachment Pattern), use standard IANA MIME types:

Common MIME Types

File Type	MIME Type	Usage
JSON	`application/json`	Structured data
PDF	`application/pdf`	Documents
PNG	`image/png`	Images
JPEG	`image/jpeg`	Images
SVG	`image/svg+xml`	Vector images
Plain Text	`text/plain`	Text files
CSV	`text/csv`	Tabular data
MP4	`video/mp4`	Videos
ZIP	`application/zip`	Archives

Custom MIME Types

For custom or specialized formats, use application/x-<format>:

Examples:

text

application/x-groth16-proof
application/x-plonk-proof

Validation and Error Codes

Standard documents reference validation error codes in the format:

Pattern: <scope>_<description>

Examples:

missing_required_name: Missing required field name
invalid_caip2_format: Invalid CAIP-2 blockchain identifier format
mcp_missing_endpoint: MCP endpoint configuration missing required endpoint field

Scope Prefixes:

missing_: Field is absent
invalid_: Field has incorrect format or value
empty_: Field is present but empty (array, string, object)
<protocol>_: Protocol-specific validation (e.g., mcp_, a2a_)

Character Encoding

All text content MUST use UTF-8 encoding.

Requirements:

JSON files MUST be valid UTF-8
String fields MUST support Unicode characters
No BOM (Byte Order Mark) in JSON files

Number Precision

Integer Values

For integer fields (e.g., agentId, score):

Use JSON number type without decimal point
Support range: 0 to 2^53-1 (JavaScript safe integer)
For Ethereum uint256, use string representation if value > 2^53-1

Decimal Values

For decimal fields (e.g., amount in payment proofs):

Use string representation for precision-sensitive values
Recommended: Wei/smallest unit representation as string
Example: "1000000000000000000" (1 ETH in wei)

Language and Localization

Default Language

All standard documents and examples use English (en-US) as the default language.

Localization Support

Standards do not currently define localization requirements. Implementations MAY support:

Language tags (e.g., description-en, description-zh)
Accept-Language header negotiation
Separate localized metadata files

Abbreviations and Acronyms

Standard Abbreviations

Abbreviation	Full Term
A2A	Agent-to-Agent Protocol
CAIP	Chain Agnostic Improvement Proposal
CID	Content Identifier (IPFS)
EIP	Ethereum Improvement Proposal
ERC	Ethereum Request for Comments
IPFS	InterPlanetary File System
JSON	JavaScript Object Notation
MCP	Model Context Protocol
NFT	Non-Fungible Token
OASF	Open Agent Skills Framework
TEE	Trusted Execution Environment
URI	Uniform Resource Identifier
URL	Uniform Resource Locator
UTC	Coordinated Universal Time
zkML	Zero-Knowledge Machine Learning
zkSNARK	Zero-Knowledge Succinct Non-Interactive Argument of Knowledge

First Use Convention

When introducing an abbreviation for the first time in a document:

Write full term followed by abbreviation in parentheses
Example: "Model Context Protocol (MCP)"

References

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
https://www.rfc-editor.org/rfc/rfc2119
CAIP-2: Blockchain ID Specification
https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
CAIP-10: Account ID Specification
https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md
ISO 8601: Date and time format
https://www.iso.org/iso-8601-date-and-time-format.html
Semantic Versioning 2.0.0
https://semver.org/
IANA Media Types (MIME types)
https://www.iana.org/assignments/media-types/media-types.xhtml

Version: 1.0
Last Updated: 2025-12-21
Status: Normative

Description ​

Purpose ​

RFC 2119 Key Words ​

Field Type System ​

JSON Primitive Types ​

Constrained Types ​

Type Notation in Tables ​

Address and Chain Identifiers ​

CAIP-2: Blockchain ID Format ​

CAIP-10: Account Address Format ​

CAIP-10 for Contract Addresses ​

OASF: Agent Skills and Domains Taxonomy ​

Overview ​

Skills Format ​

Domains Format ​

Usage in Standards ​

Timestamp Format ​

ISO 8601 Extended Format ​

Unix Timestamps ​

URI Schemes ​

Supported Schemes ​

Recommended Minimum Support ​

IPFS URI Format ​

Data URI Format ​

URI Validation ​

Versioning Strategy ​

Standard Document Versions ​

Version 0.x (Pre-release) ​

Version 1.x+ (Stable) ​

Document Version Table ​

Normative vs Non-normative Content ​

Normative Content ​

Non-normative Content ​

Relationship to EIP-8004 ​

Scope Distinction ​

Design Goals ​

Non-normative Status ​

Field Specification Format ​

Standard Field Table ​

Extended Field Specification ​

Unknown Field Handling ​

Forward Compatibility Principle ​

Custom Extensions ​

Content Hashing ​

Hash Algorithm ​

Hash Computation ​

MIME Types ​

Common MIME Types ​

Custom MIME Types ​

Validation and Error Codes ​

Character Encoding ​

Number Precision ​

Integer Values ​

Decimal Values ​

Language and Localization ​

Default Language ​

Localization Support ​

Abbreviations and Acronyms ​

Standard Abbreviations ​

First Use Convention ​

References ​

Description

Purpose

RFC 2119 Key Words

Field Type System

JSON Primitive Types

Constrained Types

Type Notation in Tables

Address and Chain Identifiers

CAIP-2: Blockchain ID Format

CAIP-10: Account Address Format

CAIP-10 for Contract Addresses

OASF: Agent Skills and Domains Taxonomy

Overview

Skills Format

Domains Format

Usage in Standards

Timestamp Format

ISO 8601 Extended Format

Unix Timestamps

URI Schemes

Supported Schemes

Recommended Minimum Support

IPFS URI Format

Data URI Format

URI Validation

Versioning Strategy

Standard Document Versions

Version 0.x (Pre-release)

Version 1.x+ (Stable)

Document Version Table

Normative vs Non-normative Content

Normative Content

Non-normative Content

Relationship to EIP-8004

Scope Distinction

Design Goals

Non-normative Status

Field Specification Format

Standard Field Table

Extended Field Specification

Unknown Field Handling

Forward Compatibility Principle

Custom Extensions

Content Hashing

Hash Algorithm

Hash Computation

MIME Types

Common MIME Types

Custom MIME Types

Validation and Error Codes

Character Encoding

Number Precision

Integer Values

Decimal Values

Language and Localization

Default Language

Localization Support

Abbreviations and Acronyms

Standard Abbreviations

First Use Convention

References