27 KiB
| eip | title | description | author | discussions-to | status | type | category | created | requires |
|---|---|---|---|---|---|---|---|---|---|
| 6596 | Historical Asset Metadata JSON Schema | Metadata JSON Schema extension to enhance the discoverability, connectivity, and collectability of historically significant NFTs. | Phillip Pon <phillip@artifactlabs.com>, Gary Liu <gary@artifactlabs.com>, Henry Chan <henry@artifactlabs.com>, Joey Liu <joey@artifactlabs.com>, Lauren Ho <lauren@artifactlabs.com>, Jeff Leung <jeff@artifactlabs.com>, Yvan Fatal <yvan@artifactlabs.com>, Brian Liang <brian@artifactlabs.com>, Seungyong Moon <seungyong@artifactlabs.com>, Joyce Li <joyce@artifactlabs.com>, Phoebe Kwok <phoebe@artifactlabs.com>, Avir Mahtani <avir@artifactlabs.com>, Zeon Chan <zeon@artifactlabs.com>, Antoine Cote <anotine@volla.io>, David Leung (@dhl) | https://ethereum-magicians.org/t/eip-6596-historical-asset-metadata-json-schema/13090 | Draft | Standards Track | ERC | 2023-02-28 | 721, 1155 |
Abstract
This EIP proposes the establishment of a new metadata standard for Historical Asset Tokens (HATs) on the Ethereum platform. HATs are tokens that represent a specific historical asset, such as a collectible or a rare item, and provide comprehensive context and provenance needed to establish historical significance and value.
HAT is the metadata standard and smart contract for historical NFTs. While existing NFT standards offer the mechanism to ensure immutability and decentralised ownership of assets on the blockchain, we believe a rich metadata standard (that includes data for the underlying asset from its moment of creation to its moment of conversion) will imbue historical NFTs with the comprehensive context and provenance needed to establish historical significance and value. Additionally, the standard will enhance the discoverability, connectivity, and collectability of all HATs.
Motivation
In recent years, the market for collectible and rare items has experienced significant growth, with many people looking to buy, sell, and trade these assets in an efficient and secure manner. However, the current market for historical assets is often plagued by issues such as fraud, counterfeiting, and lack of transparency.
The creation of a standard for HATs on the Ethereum platform has the potential to address these issues and provide a secure and transparent marketplace for historical assets. By representing historical assets as tokens on the blockchain, it becomes possible to create a permanent, tamper-proof record of ownership and transfer of these assets, while also providing a level of transparency and security that is not currently available in traditional markets.
The standard is proposed as the number and variety of NFT projects increases. The current ERC-721 has a modest metadata extension, optionally allowing for the inclusion of “name” and “symbol” functions to identify NFT collections, and for "name", "descriptions", and “image” attributes to represent assets. Metadata plays a big role in facilitating the search and discovery of NFTs on marketplaces. As the number and variety of NFT projects increases, disconnected and limited metadata structures makes it difficult for collectors to navigate through the ocean of NFT assets on major marketplaces and make sense of their value.
The provenance and history of artworks, artifacts and historical IP can take different forms and be created by different issuers. While there is no consolidated archive, a standardised metadata structure provides connectivity across NFTs associated with historical and cultural assets, regardless of the medium and issuer. For example, a video clip issued by a local filmmaker about the 1997 handover of Hong Kong can be connected to the news coverage by South China Morning Post (SCMP) of the Sino-British Joint Declaration via the HAT metadata. While well-informed collectors may not need this programmed connectivity, a standardised metadata for HATs will make these connections easily accessible for all collectors, scholars, and interested parties.
Provenance and context are extremely important for historical assets. The archival and research of significant artworks, objects, and collections are ongoing; it is a collaborative effort between creators, artist estates, galleries, auction houses, scholars and institutions. The consolidation of information and knowledge is not only crucial to the understanding of our cultural heritage; the richer the context, the more valuable the asset is to collectors. A shared and standardised metadata structure enriches the context of an NFT. With the establishment of HATs, it is our hope that this standardised structure will contribute to the evolution of cultural heritage, and fully capture the context of culturally and historically significant assets, thereby ensuring relevant and fair value for all historically significant NFTs.
Specification
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
This EIP extends ERC-721 and ERC-1155 with 48 additional properties to capture the historical significance of the underlying asset.
Compatible contracts, besides implementing the relevant metadata schemas ("Metadata JSON Schema" for ERC-721 contracts or "Metadata URI JSON Schema" for ERC-1155 contracts), must implement the following metadata interface.
Historical Asset Metadata Extension TypeScript Interface
The following TypeScript interface defines the mandatory and optional properties compatible tokens must conform to:
interface HistoricalAssetMetadata {
name: string; // Name of the HAT
description: string, // Full description of the HAT to provide the historical context
image: string; // A URI pointing to a resource with mime type image/* to serve as the cover image of the HAT
properties: {
id: string; // An unambiguous identifier of the HAT
summary: string; // Short description of the HAT, no more than 200 characters
assetType: // The type of the underlying asset
"newspaper_cover"
| "magazine_a1_cover"
| "newspaper_article"
| "magazine_article"
| "photo"
| "graphic"
| "video"
| "audio"
| "3d_object"
| "others";
issuers: string[]; // Organizations or individuals who created the HAT
issueTimestamp: string; // The date and time the HAT was issued in ISO 8601 format
edition: number; // Unique serial number of the HAT
editionCount: number; // Total number of editions available for this HAT
fileURI: string; // Link to the digital file representing the HAT
fileSize: number; // Size of the digital file of the HAT in bytes
fileFormat: string; // MIME type of the digital file of the HAT
seriesName?: string; // The name of the series this HAT is a part of
assetFullText?: string; // The full text in the underlying asset of the HAT
assetCreators?: string[]; // Organizations or individuals who created the underlying asset
earliestPossibleCreationDate?: string; // Earliest possible creation date of the underlying asset in ISO 8601 date format
latestPossibleCreationDate: string; // Latest possible creation date of the underlying asset in ISO 8601 date format
assetCreationGeos?: string; // Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision
assetCreationLocations?: string[]; // Specific cities and named locations where the underlying asset was created
assetCreationCoordinates?: string[]; // Coordinates of the location where the underlying asset was created
relevantDates?: string[]; // Dates, in ISO 8601 date format, that are referenced and important to the significance of the HAT
relevantGeos?: string[]; // Country, subdivision, and city that are referenced and important to the significance of the HAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision
relevantLocations?: string[]; // Specific cities and named locations that are referenced and important to the significance of the HAT
relevantPeople?: string[]; // Individuals that are referenced and important to the significance of the HAT
relevantEntities?: string[]; // Entities that are referenced and important to the significance of the HAT
assetLanguages?: string[]; // Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage names
assetHeight?: string; // Height of the underlying asset
assetWidth?: string; // Width of the underlying asset
assetDepth?: string; // Depth of the underlying asset
assetFileURI?: string; // Link to a high quality file of the underlying asset
assetFileSize?: number; // Size of the digital file of the underlying asset in bytes
assetCopyrightHolder?: string; // Copyright holder of the underlying asset
assetCopyrightDocumentURI?: string; // Link to the legal contract that outlines the copyright of the underlying asset
assetProvenanceRecordURI?: string; // Link to the existing provenance record documents of the underlying asset
isPhysicalAsset?: boolean; // Flags whether the asset is tied to a physical asset
assetMedium?: string; // The material used to create the physical underlying asset
assetFormFormat?: string; // The physical form or the digital format of the underlying asset. For digital format, a MIME type should be specified.
issuerNotes?: string; // Issuer's notes regarding the HAT and its underlying asset
tokenReplaced?: string; // Token identifier of the token this HAT replaced
tokenReferenced?: string; // Token identifier of the token this HAT referenced, or is a derivative of
isOwnerTokenCopyrightRightHolder?: boolean; // Flags whether the HAT token holder is the copyright owner of the HAT. Does not include the copyright to the underlying asset
tokenCopyrightRightDocumentURI?: string; // Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the HAT
isOwnerAssetCopyrightRightHolder?: boolean; // Flags whether the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying asset
assetCopyrightRightDocumentURI?: string; // Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying asset
isOwnerTokenReprintRightHolder?: boolean; // Flags whether the token owner has non-exclusive reprint/second serial rights to the HAT. Does not include the rights to the underlying asset
tokenReprintRightDocumentURI?: string; // Link to legal document outlining the token owner’s reprint/second serial rights of the HAT
isOwnerAssetReprintRightHolder?: boolean; // Flags whether the token owner has non-exclusive reprint/second serial rights to the underlying asset. Does not include the rights to the underlying asset
assetReprintRightDocumentURI?: string; // Link to legal document outlining the token owner’s reprint/second serial rights of the underlying asset
isEligibleForRelatedTokenAirdrops?: boolean; // Flags whether the token holder is eligible for related HAT airdrops
isEligibleForMetaverseAccess?: boolean; // Flags whether the token holder can gain access to the HAT metaverse
}
}
Historical Asset Metadata JSON Schema
The following JSON Schema enforces the constraints set out in the above interface definition. Tokens adopting the Historical Asset Metadata JSON Schema extension should be validated against the JSON schema prior to minting:
{
"title": "Historical Asset Metadata",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the HAT"
},
"description": {
"type": "string",
"description": "Full description of the HAT to provide the historical context"
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* to serve as the cover image of the HAT",
"format": "uri"
},
"properties": {
"type": "object",
"description": "Historical asset attributes",
"properties": {
"id": {
"type": "string",
"description": "An unambiguous identifier of the HAT"
},
"summary": {
"type": "string",
"description": "Short description of the HAT, no more than 200 characters"
},
"assetType": {
"type": "string",
"enum": [
"newspaper_cover",
"magazine_a1_cover",
"newspaper_article",
"magazine_article",
"photo",
"graphic",
"video",
"audio",
"3d_object",
"others"
],
"description": "The type of the underlying asset"
},
"issuers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Organizations or individuals who created the HAT"
},
"issueTimestamp": {
"type": "string",
"description": "The date and time the HAT was issued in ISO 8601 format",
"format": "date-time"
},
"edition": {
"type": "integer",
"description": "Unique serial number of the HAT"
},
"editionCount": {
"type": "integer",
"description": "Total number of editions available for this HAT"
},
"fileURI": {
"type": "string",
"description": "Link to the digital file representing the HAT",
"format": "uri"
},
"fileSize": {
"type": "integer",
"description": "Size of the digital file of the HAT in bytes"
},
"fileFormat": {
"type": "string",
"description": "MIME type of the digital file of the HAT"
},
"seriesName": {
"type": "string",
"description": "The name of the series this HAT is a part of"
},
"assetFullText": {
"type": "string",
"description": "The full text in the underlying asset of the HAT"
},
"assetCreators": {
"type": "array",
"items": {
"type": "string"
},
"description": "Organizations or individuals who created the underlying asset"
},
"earliestPossibleCreationDate": {
"type": "string",
"description": "Earliest possible creation date of the underlying asset in ISO 8601 date format",
"format": "date"
},
"latestPossibleCreationDate": {
"type": "string",
"format": "date",
"description": "Latest possible creation date of the underlying asset in ISO 8601 date format"
},
"assetCreationGeos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision"
},
"assetCreationLocations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific cities and named locations where the underlying asset was created"
},
"assetCreationCoordinates": {
"type": "array",
"items": {
"type": "string"
},
"description": "Coordinates of the location where the underlying asset was created"
},
"relevantDates": {
"type": "array",
"items": {
"type": "string",
"description": "Dates, in ISO 8601 date format, that are referenced and important to the significance of the HAT",
"format": "date"
}
},
"relevantGeos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Country, subdivision, and city that are referenced and important to the significance of the HAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision"
},
"relevantLocations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific cities and named locations that are referenced and important to the significance of the HAT"
},
"relevantPeople": {
"type": "array",
"items": {
"type": "string"
},
"description": "Individuals that are referenced and important to the significance of the HAT"
},
"relevantEntities": {
"type": "string",
"description": "Entities that are referenced and important to the significance of the HAT"
},
"assetLanguages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage names"
},
"assetHeight": {
"type": "string",
"description": "Height of the underlying asset"
},
"assetWidth": {
"type": "string",
"description": "Width of the underlying asset"
},
"assetDepth": {
"type": "string",
"description": "Depth of the underlying asset"
},
"assetFileURI": {
"type": "string",
"description": "Link to a high quality file of the underlying asset",
"format": "uri"
},
"assetFileSize": {
"type": "integer",
"description": "Size of the digital file of the underlying asset in bytes"
},
"assetCopyrightHolder": {
"type": "string",
"description": "Copyright holder of the underlying asset"
},
"assetCopyrightDocumentURI": {
"type": "string",
"description": "Link to the legal contract that outlines the copyright of the underlying asset",
"format": "uri"
},
"assetProvenanceRecordURI": {
"type": "string",
"description": "Link to the existing provenance record documents of the underlying asset",
"format": "uri"
},
"isPhysicalAsset": {
"type": "boolean",
"description": "Flags whether the asset is tied to a physical asset"
},
"assetMedium": {
"type": "string",
"description": "The material used to create the physical underlying asset"
},
"assetFormFormat": {
"type": "string",
"description": "The physical form or the digital format of the underlying asset"
},
"issuerNotes": {
"type": "string",
"description": "Issuer's notes regarding the HAT and its underlying asset"
},
"tokenReplaced": {
"type": "string",
"description": "Token identifier of the token this HAT replaced"
},
"tokenReferenced": {
"type": "string",
"description": "Token identifier of the token this HAT referenced, or is a derivative of"
},
"isOwnerTokenCopyrightRightHolder": {
"type": "boolean",
"description": "Flags whether or not the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying asset"
},
"tokenCopyrightRightDocumentURI": {
"type": "string",
"description": "Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the HAT",
"format": "uri"
},
"isOwnerAssetCopyrightRightHolder": {
"type": "boolean",
"description": "Flags whether or not the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying asset"
},
"assetCopyrightRightDocumentURI": {
"type": "string",
"description": "Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying asset",
"format": "uri"
},
"isOwnerTokenReprintRightHolder": {
"type": "boolean",
"description": "Flags whether or not the HAT token owner has non-exclusive reprint/second serial rights to the HAT. Does not include the rights to the underlying asset"
},
"tokenReprintRightDocumentURI": {
"type": "string",
"description": "Link to legal document outlining the token owner’s reprint/second serial rights of the HAT",
"format": "uri"
},
"isOwnerAssetReprintRightHolder": {
"type": "boolean",
"description": "Flags whether or not the HAT token owner has non-exclusive reprint/second serial rights to the underlying asset. Does not include the rights to the underlying asset"
},
"assetReprintRightDocumentURI": {
"type": "string",
"description": "Link to legal document outlining the token owner’s reprint/second serial rights of the underlying asset",
"format": "uri"
},
"isEligibleForRelatedTokenAirdrops": {
"type": "boolean",
"description": "Flags whether or not the HAT token holder is eligible for related HAT airdrops"
},
"isEligibleForMetaverseAccess": {
"type": "boolean",
"description": "Flags whether or not the HAT token holder can gain access to the HAT metaverse"
}
},
"required": [
"assetType",
"id",
"issuers",
"summary",
"issueTimestamp",
"edition",
"editionCount",
"fileURI",
"fileSize",
"fileFormat",
"latestPossibleCreationDate"
]
}
},
"required": [
"name",
"description",
"image",
"properties"
]
}
Rationale
Choosing to Extend Off-Chain Metadata JSON Schema over On-Chain Interface
Both the ERC-721 and ERC-1155 provides natural extension point in the metadata JSON file associated with NFTs to provide enriched dataset about the underlying assets.
Providing enriched dataset through off-chain metadata JSON files allow already-deployed NFT contracts to adopt the metadata structure in this EIP without upgrade or migration. The off-chain design allows for flexible and progressive enhancement of any NFT collections to adopt standard such as this EIP, and to progressively enhance and enrich the collection over time.
By avoiding the need to newly create or adapt smart contracts, NFT collections can be deployed using audited and battle tested smart contract code, thus reducing the risk of adopting and implementing a new standard.
Capturing Attributes Extensions in properties property
The ERC-1155 standard has a properties property in its JSON Metadata Schema to define an arbitrary
set of additional metadata or properties to describe an underlying asset. Defining the metadata fields in this EIP over
this properties preserve the overall shape of the metadata schema of the ERC-1155, minimizing the
change needed to list and process the proposed properties.
For tokens minted against the ERC-721 standard, only one additional property needs to be added to the metadata JSON object to take advantage of the standardized fields, simplifying the adoption of this standard.
Backwards Compatibility
This EIP is fully backward compatible with ERC-721 and ERC-1155.
Security Considerations
NFT platforms and systems working with Historical Asset Metadata JSON files are recommended to treat the files as client supplied data and follow the appropriate best practices for processing such data.
When processing the URI fields, backend systems should take care to prevent a malicious issuer exploiting these fields to perform Server-Side Request Forgery (SSRF).
Frontend or client-side systems are recommended to escape all control characters that may be exploited to perform Cross-Site Scripting (XSS).
Processing systems are also recommended to take care with resource allocation to mitigate against buffer overflow due to improper processing of variable data such as strings, arrays, and JSON objects. This is to prevent the systems from becoming susceptible to Denial of Service (DOS) attack or circumventing security protection through arbitrary code exception.
The metadata JSON files and the digital resources representing both the token and underlying assets should be stored in a decentralized storage network to preserve integrity and to ensure available of data for long term preservation.
Establishing the authenticity of the claims made in the Metadata JSON file is beyond the scope of this EIP, and is left to future EIPs to propose an appropriate protocol.
Copyright
Copyright and related rights waived via CC0.