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:

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:

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:

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:

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:

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:

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:

❌ 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):

ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

CIDv1 (recommended):

ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4

Gateway Translation (informative):

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

Data URI Format

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

Example (JSON):

data:application/json;base64,eyJuYW1lIjoiQWdlbnQifQ==

Example (inline JSON without encoding):

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

1. Complement, not replace: These standards fill gaps in offchain data formats not covered by EIP-8004
2. Implementation-agnostic: Any ERC-8004 registry or explorer MAY adopt these formats
3. Interoperability: Following these standards improves cross-platform compatibility
4. 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:

{
  "fieldName": "example-value"
}

Unknown Field Handling

Forward Compatibility Principle

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

1. MUST NOT reject documents containing unknown fields
2. SHOULD preserve unknown fields when re-serializing data
3. SHOULD log warnings for unexpected fields (informative, not errors)
4. 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:

{
  "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:

0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

Hash Computation

For JSON content:

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

Example (informative):

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:

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