ARC-36: Convention for declaring filters of an NFT

This is a convention for declaring filters in an NFT metadata

Standard for declaring filters inside non-fungible token metadata

Abstract

The goal is to establish a standard for how filters are declared inside a non-fungible (NFT) metadata.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Comments like this are non-normative.

If the property filters is provided anywhere in the metadata of an nft, it MUST adhere to the schema below. If the nft is a part of a larger collection and that collection has filters, all the available filters for the collection MUST be listed as a property of the filters object. If the nft does not have a particular filter, it’s value MUST be “none”.

The JSON schema for filters is as follows:

{
  "title": "Filters for Non-Fungible Token",
  "type": "object",
  "properties": {
    "filters": {
      "type": "object",
      "description": "Filters can be used to filter nfts of a collection.  Values must be an array of strings or numbers."
    }
  }
}

Examples

Example of an NFT that has traits & filters

{
  "name": "NFT With Traits & filters",
  "description": "NFT with traits & filters",
  "image": "https://s3.amazonaws.com/your-bucket/images/two.png",
  "image_integrity": "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
  "properties": {
    "creator": "Tim Smith",
    "created_at": "January 2, 2022",
    "traits": {
      "background": "yellow",
      "head": "curly"
    },
    "filters": {
      "xp": 120,
      "state": "REM"
    }
  }
}

Rationale

A standard for filters is needed so programs know what to expect in order to filter things without using rarity.

Backwards Compatibility

If filters wants to be added on top of fields ARC-16 traits and filters should be inside the properties object. (eg: Example above)

Security Considerations

None.

Copyright

Copyright and related rights waived via CCO.

Citation

Please cite this document as:

Stéphane Barroso, "ARC-36: Convention for declaring filters of an NFT," Algorand Requests for Comments, no. 36, March 2023. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0036.md.