📝 IPA Metadata Standard

We are still figuring out the best way to define an IPA Metadata Standard. For the sake of transparency, the following document is our thoughts so far but is subject to change as we release future versions.

Official Ippy IP

Check out the official Ippy IP, which has both NFT & IP metadata.

How to Add Metadata to an IP Asset

Learn how to actually add the IP metadata discussed here to your IP Asset with an explanation or completed code example.

This is the JSON metadata that is associated with an IP Asset, and gets stored inside of an IP Account. You must call setMetadata(...) inside of the IP Account in order to set the metadata, and then call metadata() to read it.

Attributes & Structure

Below are the important attributes you should provide in your IP metadata. Under the Required For column is what the specific field is required for:

🔍 DATA Foundation Explorer - this field will help display your IP on the DATA Foundation Explorer
🕵️ Commercial Infringement Check - this field is required if your IP is commercial (that is, has commercialUse = true license terms attached). We will use these fields to run an infringement check on your IP.
- This applies when a commercialUse = true license term is attached.
🤖 AI Agents - used for displaying metadata associated with AI Agents

Property Name	Type	Description	Required For
`title`	`string`	Title of the IP	🔍 DATA Foundation Explorer
`description`	`string`	Description of the IP	🔍 DATA Foundation Explorer
`createdAt`	`string`	Date/Time that the IP was created (either ISO8601 or unix format). This field can be used to specify historical dates that aren’t on-chain. For example, Harry Potter was published on June 26.	🔍 DATA Foundation Explorer
`image`	`string`	An image for your IP. For audio assets, the recommended thumbnail aspect ratio is 1:1. For video assets, it is 16:9.	🔍 DATA Foundation Explorer
`imageHash`	`string`	Hash of your `image` using SHA-256 hashing algorithm. See here for how that is done.	🔍 DATA Foundation Explorer
`creators`	`IpCreator[]`	An array of information about the creators. See the type defined below	🔍 DATA Foundation Explorer
`mediaUrl`	`string`	Used for infringement checking, points to the actual media (ex. image or audio). For audio assets, the recommended thumbnail aspect ratio is 1:1. For video assets, it is 16:9.	🕵️ Commercial Infringement Check
`mediaHash`	`string`	Hashed string of the media using SHA-256 hashing algorithm. See here for how that is done.	🕵️ Commercial Infringement Check
`mediaType`	`string`	Type of media (audio, video, image), based on mimeType. See the allowed media types here.	🕵️ Commercial Infringement Check
`aiMetadata`	`AIMetadata`	Used for registering & displaying AI Agent Metadata. See the type defined below	🤖 AI Agents
N/A	N/A	You can include other values as well.	N/A

Type Definitions

Here are the type definitions for the complex types used in the metadata:

type IpCreator = {
  name: string;
  address: Address;
  contributionPercent: number; // add up to 100
  description?: string;
  image?: string;
  socialMedia?: IpCreatorSocial[];
  role?: string;
};

type IpCreatorSocial = {
  platform: string;
  url: string;
};

type AIMetadata = {
  // this can be any character file you want
  // example: https://github.com/elizaOS/characterfile/blob/main/examples/example.character.json
  characterFileUrl: string;
  characterFileHash: string;
};

Media Types

The following media types are allowed for the mediaType field:

Media Type	Description
`image/jpeg`	JPEG image
`image/png`	PNG image
`image/apng`	Animated PNG image
`image/avif`	AV1 Image File Format
`image/gif`	GIF image
`image/svg+xml`	SVG image
`image/webp`	WebP image
`audio/wav`	WAV audio
`audio/mpeg`	MP3 audio
`audio/flac`	FLAC audio
`audio/aac`	AAC audio
`audio/ogg`	OGG audio
`audio/mp4`	MP4 audio
`audio/x-aiff`	AIFF audio
`audio/x-ms-wma`	WMA audio
`audio/opus`	Opus audio
`video/mp4`	MP4 video
`video/webm`	WebM video
`video/quicktime`	QuickTime video

Hashing Content

To hash content for the imageHash or mediaHash fields, you can use the SHA-256 hashing algorithm. Here’s an example of how to do this in JavaScript:

import { toHex, Hex } from "viem";

// get hash from a file
async function getFileHash(file: File): Promise<Hex> {
  const arrayBuffer = await file.arrayBuffer();
  const hashBuffer = await crypto.subtle.digest("SHA-256", arrayBuffer);
  return toHex(new Uint8Array(hashBuffer), { size: 32 });
}

// get hash from a url
async function getHashFromUrl(url: string): Promise<Hex> {
  const response = await axios.get(url, { responseType: "arraybuffer" });
  const buffer = Buffer.from(response.data);
  return "0x" + createHash("sha256").update(buffer).digest("hex");
}

shasum -a 256 myfile.jpg

Example Use Cases

Ippy Mascot
Music
AI Agent

This is the official Ippy mascot that is registered on mainnet. You can view it on our protocol explorer here.

{
  "title": "Ippy",
  "description": "Official mascot of the DATA Foundation.",
  "createdAt": "1728401700",
  "image": "https://ipfs.io/ipfs/QmSamy4zqP91X42k6wS7kLJQVzuYJuW2EN94couPaq82A8",
  "imageHash": "0x21937ba9d821cb0306c7f1a1a2cc5a257509f228ea6abccc9af1a67dd754af6e",
  "mediaUrl": "https://ipfs.io/ipfs/QmSamy4zqP91X42k6wS7kLJQVzuYJuW2EN94couPaq82A8",
  "mediaHash": "0x21937ba9d821cb0306c7f1a1a2cc5a257509f228ea6abccc9af1a67dd754af6e",
  "mediaType": "image/png",
  "creators": [
    {
      "name": "The DATA Foundation",
      "address": "0x67ee74EE04A0E6d14Ca6C27428B27F3EFd5CD084",
      "description": "The World's IP Blockchain",
      "contributionPercent": 100,
      "socialMedia": [
        {
          "platform": "Twitter",
          "url": "https://x.com/DataFDN"
        },
        {
          "platform": "Telegram",
          "url": "https://t.me/yourproject"
        },
        {
          "platform": "Website",
          "url": "https://datafdn.org"
        },
        {
          "platform": "Discord",
          "url": "https://discord.gg/datafdn"
        },
        {
          "platform": "YouTube",
          "url": "https://youtube.com/@storyFDN"
        }
      ]
    }
  ],
  "tags": ["Ippy", "DATA Foundation", "DATA Foundation Mascot", "Mascot", "Official"], // experimental field
  "ipType": "Character" // experimental field
}

This is an example song generated on Suno and registered on our testnet. View the below example on our protocol explorer.

{
  "title": "Midnight Marriage",
  "description": "This is a house-style song generated on suno.",
  "createdAt": "1740005219",
  "creators": [
    {
      "name": "Jacob Tucker",
      "address": "0xA2f9Cf1E40D7b03aB81e34BC50f0A8c67B4e9112",
      "contributionPercent": 100
    }
  ],
  "image": "https://cdn2.suno.ai/image_large_8bcba6bc-3f60-4921-b148-f32a59086a4c.jpeg",
  "imageHash": "0xc404730cdcdf7e5e54e8f16bc6687f97c6578a296f4a21b452d8a6ecabd61bcc",
  "mediaUrl": "https://cdn1.suno.ai/dcd3076f-3aa5-400b-ba5d-87d30f27c311.mp3",
  "mediaHash": "0xb52a44f53b2485ba772bd4857a443e1fb942cf5dda73c870e2d2238ecd607aee",
  "mediaType": "audio/mpeg"
}

The main difference here is you should supply aiMetadata with a character file. You can provide any character file you want, or use this ElizaOS example as a template.View the below example on our protocol explorer.

{
  "title": "DATA Foundation AI Agent",
  "description": "This is an example AI Agent registered on the DATA Foundation.",
  "createdAt": "1740005219",
  "creators": [
    {
      "name": "Jacob Tucker",
      "address": "0xA2f9Cf1E40D7b03aB81e34BC50f0A8c67B4e9112",
      "contributionPercent": 100
    }
  ],
  "image": "https://ipfs.io/ipfs/bafybeigi3k77t5h5aefwpzvx3uiomuavdvqwn5rb5uhd7i7xcq466wvute",
  "imageHash": "0x64ccc40de203f218d16bb90878ecca4338e566ab329bf7be906493ce77b1551a",
  "mediaUrl": "https://ipfs.io/ipfs/bafybeigi3k77t5h5aefwpzvx3uiomuavdvqwn5rb5uhd7i7xcq466wvute",
  "mediaHash": "0x64ccc40de203f218d16bb90878ecca4338e566ab329bf7be906493ce77b1551a",
  "mediaType": "image/webp",
  "aiMetadata": {
    "characterFileUrl": "https://ipfs.io/ipfs/bafkreic6eu4hlnwx46soib62rgkhhmlieko67dggu6bzk7bvtfusqsknfu",
    "characterFileHash": "0x5e253875b6d7e7a4e407da899473b168229def8cc6a783957c35996928494d2d"
  }
}

Optional Properties

The following properties are optional but can provide additional context about your IP Asset:

We are still figuring out the best way to define an IPA Metadata Standard. The fields below are bound to change or be removed at some point.

Property Name	Type	Description
`ipType`	`string`	Type of the IP Asset, can be defined arbitrarily by the creator. I.e. “character”, “chapter”, “location”, “items”, “music”, etc
`relationships`	`IpRelationship[]`	The detailed relationship info with the IPA’s direct parent asset, such as `APPEARS_IN`, `FINETUNED_FROM`, etc. See more examples here.
`watermarkImage`	`string`	A separate image with your watermark already applied. This way apps choosing to use it can render this version of the image (with watermark applied).
`media`	`IpMedia[]`	An array of supporting media. Media type defined below
`app`	`DataApp`	This is assigned to verified application from the DATA Foundation directly (on a request basis so far). We will map each App ID to a name
`tags`	`string[]`	Any tags that can help surface this IPA
`robotTerms`	`IPRobotTerms`	Allows you to set Do Not Train for a specific agent
N/A	N/A	You can include other values as well.

Type Definitions

type IpRelationship = {
  parentIpId: Address;
  type: string; // see "Relationship Types" docs below
};

type IpMedia = {
  name: string;
  url: string;
  mimeType: string;
};

type DataApp = {
  id: string;
  name: string;
  website: string;
  action?: string;
};

type IPRobotTerms = {
  userAgent: string;
  allow: string;
};

Relationship Types

The different relationship types that can be used for the relationships attribute.

DATA Foundation Relationships

APPEARS_IN - A character APPEARS_IN a chapter.
BELONGS_TO - A chapter BELONGS_TO a book.
PART_OF - A book is PART_OF a series.
CONTINUES_FROM - A chapter CONTINUES_FROM the previous one.
LEADS_TO - An event LEADS_TO a consequence.
FORESHADOWS - An event FORESHADOWS future developments.
CONFLICTS_WITH - A character CONFLICTS_WITH another character.
RESULTS_IN - A decision RESULTS_IN a significant change.
DEPENDS_ON - A subplot DEPENDS_ON the main plot.
SETS_UP - A prologue SETS_UP the story.
FOLLOWS_FROM - A chapter FOLLOWS_FROM the previous one.
REVEALS_THAT - A twist REVEALS_THAT something unexpected occurred.
DEVELOPS_OVER - A character DEVELOPS_OVER the course of the story.
INTRODUCES - A chapter INTRODUCES a new character or element.
RESOLVES_IN - A conflict RESOLVES_IN a particular outcome.
CONNECTS_TO - A theme CONNECTS_TO the main narrative.
RELATES_TO - A subplot RELATES_TO the central theme.
TRANSITIONS_FROM - A scene TRANSITIONS_FROM one setting to another.
INTERACTED_WITH - A character INTERACTED_WITH another character.
LEADS_INTO - An event LEADS_INTO the climax.?
PARALLEL - story happening in parallel or around the same timeframe

AI Relationships

TRAINED_ON - A model is TRAINED_ON a dataset.
FINETUNED_FROM - A model is FINETUNED_FROM a base model.
GENERATED_FROM - An image is GENERATED_FROM a fine-tuned model.
REQUIRES_DATA - A model REQUIRES_DATA for training.
BASED_ON - A remix is BASED_ON a specific workflow.
INFLUENCES - Sample data INFLUENCES model output.
CREATES - A pipeline CREATES a fine-tuned model.
UTILIZES - A workflow UTILIZES a base model.
DERIVED_FROM - A fine-tuned model is DERIVED_FROM a base model.
PRODUCES - A model PRODUCES generated images.
MODIFIES - A remix MODIFIES the base workflow.
REFERENCES - An AI-generated image REFERENCES original data.
OPTIMIZED_BY - A model is OPTIMIZED_BY specific algorithms.
INHERITS - A fine-tuned model INHERITS features from the base model.
APPLIES_TO - A fine-tuning process APPLIES_TO a model.
COMBINES - A remix COMBINES elements from multiple datasets.
GENERATES_VARIANTS - A model GENERATES_VARIANTS of an image.
EXPANDS_ON - A fine-tuning process EXPANDS_ON base capabilities.
CONFIGURES - A workflow CONFIGURES a model’s parameters.
ADAPTS_TO - A fine-tuned model ADAPTS_TO new data.

Get Started

The Data Stack

DATA Network

Notices

Official Ippy IP

How to Add Metadata to an IP Asset

Attributes & Structure

Type Definitions

Media Types

Hashing Content

Example Use Cases

Optional Properties

Type Definitions

Relationship Types

DATA Foundation Relationships

AI Relationships

Official Ippy IP

How to Add Metadata to an IP Asset

​Attributes & Structure

​Type Definitions

​Media Types

​Hashing Content

​Example Use Cases

​Optional Properties

​Type Definitions

​Relationship Types

​DATA Foundation Relationships

​AI Relationships

Attributes & Structure

Type Definitions

Media Types

Hashing Content

Example Use Cases

Optional Properties

Type Definitions

Relationship Types

DATA Foundation Relationships

AI Relationships