Give your protocol's data
a permanent home

Summary

Denna Spec is a convention for expressing any structured data as self-describing JSON files validated by JSON Schema. A Denna file (.denna-spec.json) is a JSON document containing a metadata block that identifies what it is, and any number of domain-defined fields containing the actual data. Its structure is validated by a standard JSON Schema referenced via the $schema field.

Denna does not replace JSON Schema — it is a thin orchestration layer on top of it. JSON Schema handles all structural validation. Denna defines the conventions JSON Schema alone cannot express: file naming, a standard metadata block, semantic value types, a schema namespace convention, and organizational guidance.

1. File Naming

1. A Denna file MUST use the extension .denna-spec.json.
2. The file name SHOULD be descriptive and use kebab-case. Examples: config.denna-spec.json, pnl-params.denna-spec.json, stablecoin-addresses.denna-spec.json.
3. Files intended to be validated by automated tooling MUST use the .denna-spec.json extension to be discovered by validators and CI pipelines.

2. File Structure

A Denna file MUST be a valid JSON object containing the following top-level fields:

{
  "$schema": "path/or/uri/to/schema.json",
  "metadata": { }
}

Beyond $schema and metadata, all other fields are defined by the domain schema referenced in $schema. The domain schema MAY define any additional fields using any names.

2.1. $schema REQUIRED

A string containing a relative path or absolute URI to a JSON Schema file that validates the entire Denna file. This is standard JSON Schema behavior — it enables IDE auto-completion, inline validation, and tells validators which schema to use. The referenced schema MUST validate the complete file including metadata and all domain content fields.

2.2. metadata REQUIRED

An object describing the file's identity and provenance.

2.3. Domain Content Fields

Any fields beyond $schema and metadata are defined by the domain schema. Common naming conventions:

3. Kind Identifiers

The metadata.kind field is a reverse-domain identifier that uniquely classifies the type of data. It follows a naming convention inspired by AT Protocol NSIDs.

3.1. Format

A kind MUST consist of at least three dot-separated segments. The first two SHOULD identify the schema publisher in reverse-domain order.

io.denna.defi.prime-config
^^ ^^^^^ ^^^^ ^^^^^^^^^^^^
|  |      |    name
|  |      namespace
|  domain
TLD

Pattern: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$

3.2. Namespace Conventions

4. Semantic Value Types

Reusable type definitions are available at spec.denna.io/schemas/v1/denna-types.schema.json. Import via $ref in domain schemas.

4.1. Address

{ "value": "0x1601843c5e9bc251a3272907010afa41fa18347e", "format": "evm" }
{ "value": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "format": "solana" }

4.2. Rate

{ "value": 30, "unit": "bps" }      // basis points
{ "value": 4.5, "unit": "percent" }  // percentage

4.3. Amount

{ "value": 1000000000, "currency": "USD" }

4.4. Duration

{ "value": 24, "unit": "months" }
{ "value": 7, "unit": "days" }

4.5. Date

"2026-01-01"  // ISO 8601 — YYYY-MM-DD

4.6. Chain Identifier

"ethereum"  // lowercase: base, arbitrum, optimism, solana, avalanche…

5. Domain Schemas

A domain schema is a JSON Schema file that defines the complete structure of a Denna file for a specific use case. Domain schemas:

1. MUST validate the full file including $schema, metadata, and all domain content fields.
2. SHOULD import shared type definitions via $ref from https://spec.denna.io/schemas/v1/denna-types.schema.json.
3. SHOULD use JSON Schema draft 2020-12 or later.
4. SHOULD be versioned at stable paths (e.g., schemas/v1/, schemas/v2/).
5. MAY be stored in the same repository as data files or published separately at a stable URL.

6. Schema Ecosystem

Denna Spec is designed around an open schema ecosystem. Any organization can publish schemas. No central registry is required.

• Official Denna schemas — maintained at schemas.denna.io, using the io.denna.* namespace.
• Custom schemas — any organization can publish schemas using their reverse-domain namespace, hosted anywhere accessible by URL.
• Local schemas — schemas stored in the same repository as data files, referenced with relative paths.

7. Versioning

1. The Denna Specification follows Semantic Versioning. Current version: 1.0.0.
2. Individual data files SHOULD include metadata.version to track data changes over time.
3. Domain schemas SHOULD be versioned at stable paths (schemas/v1/, schemas/v2/).

8. Validation

1. A Denna file is valid if and only if it passes JSON Schema validation against the schema in its $schema field.
2. Validators MUST resolve the $schema field and validate the entire file against the resolved schema.
3. If $schema is missing or cannot be resolved, the file MUST be treated as invalid.

Complete Example

Prime configuration — spark/config.denna-spec.json

{
  "$schema": "https://schemas.denna.io/v1/defi/prime-config.schema.json",
  "metadata": {
    "id": "spark-config",
    "name": "Spark",
    "kind": "io.denna.defi.prime-config",
    "version": "1.0.0",
    "lastUpdated": "2026-02-21",
    "source": { "repository": "primes-parameters", "references": ["src/lib/constants.ts:12"] }
  },
  "chains": [
    {
      "id": "ethereum",
      "almProxy": { "value": "0x1601843c5e9bc251a3272907010afa41fa18347e", "format": "evm" },
      "vaultProxy": { "value": "0x691a6c29e9e96dd897718305427ad5d534db16ba", "format": "evm" },
      "features": { "alm": true, "psm3": false }
    }
  ],
  "allocations": {
    "ethereum": [
      {
        "contract": { "value": "0x4dedf26112b3ec8ec46e7e31ea5e123490b05b8b", "format": "evm" },
        "protocol": "SparkLend",
        "type": "atoken",
        "underlying": "DAI"
      }
    ]
  }
}

Validation workflow — .github/workflows/validate.yml

name: Validate Denna Spec Files

on:
  pull_request:
    paths: ['**/*.denna-spec.json', 'schemas/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: daocraft/denna-spec@v1
        with:
          patterns: "**/*.denna-spec.json"
          exclude: "_template/**"