Contributing

Contributing Guide

Two things move Finmarks forward: new entities and missing logo variants. Both are welcome. A metadata-only PR with "logos": { "full": null }is a real contribution — you do not need to bring artwork.

Setup

git clone https://github.com/Finmarks/Finmarks.git
cd Finmarks
pnpm install
pnpm validate

You need Node 18+ and pnpm.

Adding an entity

1. Create the folder

The folder name is the entity id — lowercase, kebab-case, and stable forever, because it appears in CDN URLs.

mkdir -p entities/acme-bank

2. Write entity.json

Minimum viable record:

{
  "id": "acme-bank",
  "name": "Acme Bank",
  "short_name": "Acme",
  "categories": ["private-bank"],
  "logos": { "full": null },
  "brand_color": "#004C8F",
  "country": "IN",
  "status": "active",
  "added_at": "2026-08-12",
  "updated_at": "2026-08-12",
  "contributors": ["your-github-username"]
}

If you open entity.json in VS Code you get autocomplete and inline validation — the schema is bound in .vscode/settings.json.

3. Add logos (optional but encouraged)

Drop SVGs into the folder and point at them in logos:

"logos": {
  "full": "full.svg",
  "icon": "icon.svg",
  "mono_dark": "mono-dark.svg",
  "mono_light": "mono-light.svg"
}

Use null for variants you do not have. The generated index only publishes URLs for files that actually exist, so a null never becomes a broken link.

4. Validate and open a PR

pnpm validate      # must pass
pnpm check-logos   # shows what is still missing

Field reference

Field	Required	Notes
`id`	✅	Kebab-case, matches the folder name, permanent
`name`	✅	Full official brand name
`short_name`	✅	For space-constrained UI, ≤24 chars
`categories`	✅	At least one. Tags are additive — list all that apply
`logos`	✅	The `full` key must be present, though it may be `null`
`country`	✅	`IN`, `US`, `GB`, `SG`, `AE`
`brand_color`		`#RRGGBB`, the primary brand colour
`legal_name`		Registered entity name
`founded`		Year, 1800–2030
`regulated_by`		`RBI`, `SEBI`, `IRDAI`, `NPCI`, `PFRDA`, `IFSCA`, `MCA`, `None`
`ifsc_prefix`		4 uppercase letters. Banks only
`upi_handles`		Include the `@`, e.g. `["@ybl"]`
`fip_id` / `fiu_id`		AA framework identifiers. `null` if unverified (vs. absent if unchecked)
`website`		Official website URL
`tags`		Additional search terms not covered by other fields

Logo sourcing rules

Assets must come from an official brand kit or official web property
Never trace logos by hand or pull from third-party aggregators
Declare the source in the PR description
Do not submit logos where the brand guidelines explicitly forbid redistribution — open an issue instead

SVGs must include a viewBox, use no raster embeds, no <script>tags, and weigh under 50KB. Run pnpm validate — it will tell you exactly what failed.

← PreviousTypeScript Types NextTrademarks →