Uploading Files with Custom MetaData

ArDrive CLI has the capability of attaching custom metadata to ArFS File and Folder MetaData Transactions during the upload-file command. This metadata can be applied to either the GQL tags on the MetaData Transaction and/or into the MetaData Transaction's Data JSON.

All custom metadata applied must ultimately adhere to the following JSON shapes:

// GQL Tags
type CustomMetaDataGqlTags = Record<string, string | string[]>;

// Data JSON Fields
type CustomMetaDataJsonFields = Record<string, JsonSerializable>;

export type JsonSerializable =
    | string
    | number
    | boolean
    | null
    | { [member: string]: JsonSerializable }
    | JsonSerializable[];

e.g:

{ IPFS-Add: 'MY_HASH' }
{ 'Custom Name': ['Val 1', 'Val 2'] }

When the custom metadata is attached to the MetaData Transaction's GQL tags, they will become visible on any Arweave GQL gateway and also third party tools that read GQL data.

When these tags are added to the MetaData Transaction's Data JSON they can be read by downloading the JSON data directly from https://arweave.net/METADATA_TX_ID.

To add this custom metadata to your file metadata transactions, CLI users can pass custom metadata these parameters:

• --metadata-file path/to/json/schema
• --metadata-json '{"key": "val", "key-2": true, "key-3": 420, "key-4": ["more", 1337]}'
• --metadata-gql-tags "Tag-Name" "Tag Val"

The --metadata-file will accept a file path to JSON file containing custom metadata:

ardrive upload-file --metadata-file path/to/metadata/json # ...

This JSON schema object must contain instructions on where to put this metadata with the metaDataJson and metaDataGqlTags keys. e.g:

{
    "metaDataJson": {
        "Tag-Name": ["Value-1", "Value-2"]
    },
    "metaDataGqlTags": {
        "GQL Tag Name": "Tag Value"
    }
}

The --metadata-gql-tags parameter accepts an array of string values to be applied to the MetaData Tx GQL Tags. This method of CLI input does not support multiple tag values for a given tag name and the input must be an EVEN number of string values. (Known bug: String values starting with the "-" character are currently not supported. Use --metadata-file parameter instead.) e.g:

upload-file --metadata-gql-tags "Custom Tag Name" "Custom Value" # ...

And the --metadata-json parameter will accept a stringified JSON input. It will apply all declared JSON fields directly to the MetaData Tx's Data JSON. e.g:

 upload-file --metadata-json ' { "json field": "value", "another fields": false } ' # ...

Custom metadata applied to files and/or folders during the upload-file command will be read back through all existing read commands. e.g:

ardrive file-info -f 067c4008-9cbe-422e-b697-05442f73da2b
{
    "appName": "ArDrive-CLI",
    "appVersion": "1.17.0",
    "arFS": "0.11",
    "contentType": "application/json",
    "driveId": "967215ca-a489-494b-97ec-0dd428d7be34",
    "entityType": "file",
    "name": "unique-name-9718",
    "txId": "sxg8bNu6_bbaHkJTxAINVVoz_F-LiFe6s7OnxzoJJk4",
    "unixTime": 1657655070,
    "size": 262148,
    "lastModifiedDate": 1655409872705,
    "dataTxId": "ublZcIff77ejl3m0uEA8lXEfnTWmSBOFoz-HibqKeyk",
    "dataContentType": "text/plain",
    "parentFolderId": "97bc4fb5-aca4-4ffe-938f-1285153d98ca",
    "entityId": "067c4008-9cbe-422e-b697-05442f73da2b",
    "fileId": "067c4008-9cbe-422e-b697-05442f73da2b",
    "IPFS-Add": "MY_HASH",
    "Tag-1": "Val",
    "Tag-2": "Val",
    "Tag-3": "Val",
    "Boost": "1.05"
}

Applying Unique Custom MetaData During Bulk Workflows

With some custom scripting and the --metadata-file parameter, the ArDrive CLI can be used to apply custom metadata to each file individually in a bulk workflow. For example, if you choose a numbered file naming pattern you can make use of a for loop:

for i in {1..5}
do
ardrive upload-file -F f0c58c11-430c-4383-8e54-4d864cc7e927 --local-path "../uploads/test-file-$i.txt" -w "/path/to/wallet.json" --metadata-file "../custom/metadata-$i.json" --dry-run > "file-result-$i.json"
done