Compact self-describing codecs. Save space by using predefined multicodec tables.

Go to file

Steven Allen 0e370e5112 feat: import mime types		2020-02-05 14:00:50 -08:00
.travis.yml	ci: add validator script	2019-01-18 13:54:51 +00:00
LICENSE	Standardized Readme	2016-08-23 00:19:24 -04:00
README.md	feat: reserve MIME range	2020-01-31 16:35:05 -08:00
import-mime.py	feat: add a script for importing mime types	2020-01-31 16:35:05 -08:00
table.csv	feat: import mime types	2020-02-05 14:00:50 -08:00
validate.py	feat(validate): check mime types	2020-01-31 16:35:05 -08:00

README.md

multicodec

Canonical table of of codecs used by various multiformats

Motivation
Description
Examples
Multicodec table
- Adding new multicodecs to the table
Implementations
FAQ
Contribute
License

Motivation

Multicodec is an agreed-upon codec table. It is designed for use in binary representations, such as keys or identifiers (i.e CID).

Description

The code of a multicodec is usually encoded as unsigned varint as defined by multiformats/unsigned-varint. It is then used as a prefix to identify the data that follows.

Examples

Multicodec is used in various Multiformats. In Multihash it is used to identify the hashes, in the machine-readable Multiaddr to identify components such as IP addresses, domain names, identities, etc.

Multicodec table

Find the canonical table of multicodecs at table.csv. There's also a sortable viewer.

Adding new multicodecs to the table

The process to add a new multicodec to the table is the following:

1. Fork this repo
1. Update the table with the value you want to add
1. Submit a Pull Request

This "first come, first assign" policy is a way to assign codes as they are most needed, without increasing the size of the table (and therefore the size of the multicodecs) too rapidly.

The first 127 bits are encoded as a single-byte varint, hence they are reserved for the most widely used multicodecs. So if you are adding your own codec to the table, you most likely would want to ask for a codec bigger than 0x80.

Implementations

Code Ranges

There are some reserved code ranges.

MIME Types

The range 0x200000 - 0x2fffff is reserved for MIME types. Specifically, we've reserved:

Range 0x200000 - 0x20ffff: reserved for 'application/*' (there currently are ~1,300 subtypes)
Range 0x210000 - 0x21ffff: reserved for 'audio/*' (there currently are ~150 subtypes)
Range 0x220000 - 0x22ffff: reserved for 'font/*' (there currently are ~8 subtypes)
Range 0x230000 - 0x23ffff: reserved for 'image/*' (there currently are ~60 subtypes)
Range 0x240000 - 0x24ffff: reserved for 'message/*' (there currently are ~18 subtypes)
Range 0x250000 - 0x25ffff: reserved for 'model/*' (there currently are ~24 subtypes)
Range 0x260000 - 0x26ffff: reserved for 'multipart/*' (there currently are ~13 subtypes)
Range 0x270000 - 0x27ffff: reserved for 'text/*' (there currently are ~71 subtypes)
Range 0x280000 - 0x28ffff: reserved for 'video/*' (there currently are ~78 subtypes)

Everything from 0x290000 to 0x2fffff is reserved for future media types.

FAQ

Why varints?

So that we have no limitation on protocols.

What kind of varints?

An Most Significant Bit unsigned varint, as defined by the multiformats/unsigned-varint.

Don't we have to agree on a table of protocols?

Yes, but we already have to agree on what protocols themselves are, so this is not so hard. The table even leaves some room for custom protocol paths, or you can use your own tables. The standard table is only for common things.

Where did multibase go?

For a period of time, the multibase prefixes lived in this table. However, multibase prefixes are symbols that may map to multiple underlying byte representations (that may overlap with byte sequences used for other multicodecs). Including them in a table for binary/byte identifiers lead to more confusion than it solved.

You can still find the table in multibase.csv.

Can I use multicodec for my own purpose?

Sure, you can use multicodec whenever you have the need for self-identifiable data. Just prefix your own data with the corresponding varint encodec multicodec.

Contribute

Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.