Style Guide

Database structure

To visualize the entities relation, use the following structure:

provider -> offer -> listing

Folder structure:

• references/providers/providers.csv: provider identities. Answers the question "what companies provide services in Web3?"
• references/offers/<category>.csv: reusable offer templates. Answers the question "What services are being provided by those mentioned in providers?"
• listings/specific-networks/<network>/<category>.csv: network-specific listings. Answers the question "On which networks may I get these services?"
• listings/all-networks/<category>.csv: listings propagated to every network output. Does not answer a particular question, but helps to make database a bit more redundant - if offer is completely network-agnostic, it should be put here.

<category> is one of many categories in Chain.Love database. Check Chain.Love website to learn about data we provide and read about categories definitions. New categories may be added via a DBIP issue.

General rules

• Only actively maintained providers and offers are accepted.
• This repo is somewhat complicated. There is a wizard that will simplify a contribution process for you tenfold. Use it as a starting point.
• Add only data you are 100% sure about. If uncertain, leave blank or skip until verified.
• Keep data useful for developers and researchers. Do not add decorative or redundant text.
• Reuse existing wording where possible (for example security feature names) to keep filtering consistent.
• Keep provider identity and offer identity separated:
  • provider = who provides the service.
  • offer = what specific product/plan/tool is being listed.
• In listings, always use !offer:<slug> in offer column. Historically, there may be some entries that exist without a reference in offers, but all new offers should only mention offers and provide override for any columns necessary.
• Avoid duplicating information across columns.
• Avoid adding tools that are in deprecated, archived state or have not been updated for over a year.
• Keep each CSV A-Z sorted by slug.
• For adding new columns or new categories, open a DBIP issue first.
• Verify links and whether provider is supported on specific networks before submitting.
• For most columns, Markdown is supported when you need emphasis or inline links in free-text fields (follow each category page for which columns apply).

Link formatting

The link formatting is a bit tricky for now, as the offers are having support for custom buttons names, while providers are having a predefined set of buttons.

• In references/providers/providers.csv:
  • website, docs -> full URLs.
  • logoPath -> image filename only (for example alchemy.png). Consumers prepend references/providers/images/ when building URLs.
  • x, github, discord, telegram, linkedin -> value after domain only.
    • Example: https://github.com/Chain-Love/chain-love -> Chain-Love/chain-love.
• In offer/listing CSVs (actionButtons column), use Markdown links:
  • [Website](https://example.com)
  • [Docs](https://example.com/docs)

Booleans

• Always use uppercase TRUE/FALSE.

JSON columns

• Always validate JSON with jsonformatter.org.

Common abbreviations

• TBD can be used only by the internal Chain.Love team for transitional schema rollouts.