Specification

The Gridz spec is the normative definition of what a profile is, how fields are signed, and how verifiers check them byte-for-byte. This section is the in-depth reference; for a lighter introduction see Concepts.

Design principles

Attestations are the source of truth. Websites, APIs, and databases are sinks — projections for convenience. A verifier with only the Grid JSON can validate every cell without trusting gridz.bio.
One cell, one signature. Each field is independently verifiable. Checking your bio does not require fetching or trusting your social links.
Hash the value, sign the hash. Signers commit to keccak256(JCS(value)) (EVM) or sha256(JCS(value)) (non-EVM), not raw cleartext. This keeps EIP-712 payloads bounded and matches EAS schema shapes.
One struct for all keys. A single GridzCell EIP-712 type covers ENS keys, agent keys, widgets, and arbitrary dynamic keys — the key string is a signed field.
Cross-runtime agreement. TypeScript (@gridz/core), Python, and Solidity must produce identical hashes. Cross-runtime fixture tests enforce this.

Architecture at a glance

┌─────────────────────────────────────────────────────────────┐
│  Grid (gridz/1.0.0)  ◄── signed attestations = source of truth │
│  subject · theme · cells[] · root_attestation                  │
└───────────────────────────────┬─────────────────────────────┘
                                │ publish (projections, not authority)
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
  gridz.bio / API         Postgres / SQLite          Neo4j graph
  (HTML + JSON)           (relational index)         (traversal / agents)
        │                       │                       │
        └───────────────────────┴───────────────────────┘
                                │ read → assemble Grid
                                ▼
                    verifyGrid() — hashes + signatures

gridz.bio is one output format, not the only one. The same signed Grid can project to databases, knowledge graphs, object stores, or plain JSON files. See Sinks & projections.

Normative documents (repo)

Machine-readable schemas and prose specs live in the specs/ directory of the main gridz repository. SDKs, CLI, and gridz.bio all validate against these files.

Document	What it defines
grid.schema.json	Grid model: `subject`, `theme`, `cells[]`, `root_attestation`
attestation.schema.json	Portable attestation envelope on every cell and the root
canonicalization.md	JCS serialization, hashing, merkle tree, verification order
standard-keys.md	Canonical field key registry (ENS, agent, widget namespaces)
eip712-types.ts	EIP-712 `GridzCell` / `GridzRoot` structs and EAS schema strings
deployments.md	GridzResolver, EAS, and schema UIDs per chain
openapi.yaml	HTTP API surface (profile read, verify, publish)

In this documentation

Grid model — subject, theme, cells, layout, authoring flags
Standard keys — ENS inheritance, agent keys, gridz.* widgets
Canonicalization — JCS, hashes, merkle tree, verification steps
Attestations — envelope formats, EIP-712, EAS schemas
Sinks & projections — databases, knowledge graphs, APIs, and other outputs
On-chain (Base) — production contracts, publish pipeline, resolver

Schema version

Published Grids MUST set schema_version to gridz/1.0.0. A breaking change to the Grid model bumps this string and requires a new root attestation over the updated cell set.

Related guides

Verification — how gridz.bio and verifyGrid check profiles in practice
API & integrations — fetch JSON Grids over HTTP
Toolkit — @gridz/core, React, MCP, CLI