Forem: Anh Quân Nguyễn

JSON Schema in 10 Minutes — Validation, Types & Real Examples

Anh Quân Nguyễn — Tue, 26 May 2026 03:44:14 +0000

Two years ago I shipped a webhook handler without input validation. A partner started sending us a slightly malformed payload (an extra field, one missing required field) and our worker silently processed garbage into the database for three days before anyone noticed. By the time I traced it, we had 12,000 corrupt rows and a very awkward customer call.

I learned JSON Schema the next week. This post is the cheat sheet I wish someone had handed me on day one — the keywords I actually use, the gotchas that bit me again later, and the honest comparison with OpenAPI and TypeScript types.

The seven types you'll use

Every JSON value is one of seven types: string, number, integer, boolean, object, array, or null. The integer type is a JSON Schema convenience (raw JSON only has number) but the schema layer enforces "no decimal places." A minimal schema:

{
  "type": "string"
}

That validates any string and rejects everything else. You can also accept a union:

{
  "type": ["string", "null"]
}

Useful for optional fields you want to keep present in the payload rather than omitting. Before I write more than a one-line schema I usually paste a sample payload into a JSON formatter to see the actual shape pretty-printed. Type errors almost always come from misreading the structure.

Objects, required, and the additionalProperties trap

Most real validation work happens on objects. The three keywords you use every day are properties, required, and additionalProperties:

{
  "type": "object",
  "properties": {
    "email":    { "type": "string" },
    "age":      { "type": "integer" },
    "verified": { "type": "boolean" }
  },
  "required": ["email"],
  "additionalProperties": false
}

Three gotchas to internalize. First, properties describes each field but does NOT make any of them required. Without the required array, every property is optional. Second, required is a separate list of property names that must be present (presence only, you still need type to validate the value). Third, additionalProperties: false rejects any property not listed. Without this line, the schema accepts arbitrary extra fields silently. This was the bug that hit me — the partner was sending email_address instead of email, and without additionalProperties: false my schema accepted it as "no email + an unknown field."

Set additionalProperties: false by default. Remove it only when you genuinely want a free-form object. For maps with arbitrary keys but a known value type, use it as a schema instead of a boolean:

{
  "type": "object",
  "additionalProperties": { "type": "number" }
}

That validates any object where every value is a number. Perfect for price lookup tables, feature-flag percentages, or anything keyed dynamically.

String validation: minLength, pattern, format, enum

Real string validation goes beyond "is it a string." The keywords that earn their keep:

minLength / maxLength, integer bounds on UTF-16 code units (not bytes, not graphemes)
pattern, ECMA-262 regex the string must match somewhere (use ^...$ anchors for a full match)
format, named formats like email, uri, date, date-time, uuid, ipv4, ipv6
enum, a fixed list of allowed values (works for any type)
const, a single allowed value (equivalent to a one-item enum)

A practical username field:

{
  "type": "string",
  "minLength": 3,
  "maxLength": 20,
  "pattern": "^[a-zA-Z0-9_]+$"
}

One gotcha that cost me a day: format is informational by default in older drafts. You must enable format assertion in your validator. Ajv requires ajv-formats. Python jsonschema needs format_checker. Without it, "format": "email" documents intent but does not actually reject invalid emails. See the JSON Schema spec for format for the full list and the assertion behavior per draft.

Number validation: minimum, maximum, multipleOf

For numbers and integers, the validation keywords are arithmetic:

minimum / maximum, inclusive bounds
exclusiveMinimum / exclusiveMaximum, exclusive bounds (in Draft 2020-12 these take a number, in older drafts they took a boolean)
multipleOf, the value must be a multiple of this number

Validating a percentage that must be 0 to 100 in 0.01 increments:

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.01
}

multipleOf has a floating-point trap I keep getting wrong. 0.1 is not exactly representable in IEEE 754, so { "multipleOf": 0.1 } will sometimes reject values you expect to pass. For money, I now store and validate as integer cents ({ "type": "integer", "minimum": 0 }). It is the same precision argument behind storing prices in the smallest currency unit everywhere else in the stack.

Array validation: items, minItems, uniqueItems

For arrays the workhorses are items (schema applied to every element), minItems / maxItems (length bounds), and uniqueItems (rejects duplicates by deep equality). A list of unique tags:

{
  "type": "array",
  "items": { "type": "string", "minLength": 1 },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

For positional tuples where each index has a different schema, use prefixItems in Draft 2020-12 or items as an array in older drafts. A coordinate pair where index 0 is longitude and index 1 is latitude:

{
  "type": "array",
  "prefixItems": [
    { "type": "number", "minimum": -180, "maximum": 180 },
    { "type": "number", "minimum":  -90, "maximum":  90 }
  ],
  "items": false
}

The trailing "items": false rejects any extra elements beyond the two declared positions. The array equivalent of additionalProperties: false.

Schema composition: $ref, allOf, oneOf, anyOf

Once your schemas grow past a single page, you will want to break them up and combine them. JSON Schema has four composition keywords:

$ref, reuse another schema by JSON Pointer (e.g., "#/$defs/address" or an external URL)
allOf, data must validate against every subschema (intersection / mixin)
anyOf, data must validate against at least one (union, OK if multiple match)
oneOf, data must validate against exactly one (XOR, rejects if zero or multiple match)

A reusable address schema referenced from two parents:

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street":  { "type": "string" },
        "city":    { "type": "string" },
        "country": { "type": "string", "minLength": 2, "maxLength": 2 }
      },
      "required": ["street", "city", "country"]
    }
  },
  "type": "object",
  "properties": {
    "shipping": { "$ref": "#/$defs/address" },
    "billing":  { "$ref": "#/$defs/address" }
  }
}

For discriminated unions (event types, message kinds), oneOf with a const discriminator is the standard pattern:

{
  "oneOf": [
    { "type": "object", "properties": { "kind": { "const": "email" },
        "to": { "type": "string", "format": "email" } }, "required": ["kind", "to"] },
    { "type": "object", "properties": { "kind": { "const": "sms" },
        "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "required": ["kind", "phone"] }
  ]
}

A real signup schema

Putting every keyword together, here is roughly the schema I now use for a signup endpoint:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SignupRequest",
  "type": "object",
  "properties": {
    "email":     { "type": "string", "format": "email", "maxLength": 254 },
    "password":  { "type": "string", "minLength": 12, "maxLength": 128 },
    "username":  { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,20}$" },
    "age":       { "type": "integer", "minimum": 13, "maximum": 120 },
    "country":   { "type": "string", "enum": ["US", "UK", "CA", "AU"] },
    "newsletter":{ "type": "boolean", "default": false },
    "referrals": { "type": "array", "items": { "type": "string", "format": "email" },
                   "maxItems": 5, "uniqueItems": true }
  },
  "required": ["email", "password", "username", "age", "country"],
  "additionalProperties": false
}

It enforces the email format with the 254-char maximum from RFC 5321, a 12-character minimum password from NIST SP 800-63B, a regex-validated username, an integer age within plausible bounds, a closed enum of supported countries, an optional boolean with a documented default, and an optional referral list capped at 5 unique emails. The trailing additionalProperties: false is the line that would have saved me three days and 12,000 rows two years ago.

Tooling: Ajv (Node) and jsonschema (Python)

Declare which draft you target with the $schema keyword at the root. The two production-grade validators I reach for:

Ajv for Node.js and browser, the fastest JS validator, supports Draft 2020-12. Install ajv and ajv-formats together if you use format. Compile schemas once at startup with const validate = ajv.compile(schema), then call validate(data) on every request. This is 10 to 100 times faster than recompiling per call.
jsonschema for Python, the reference Python validator. Use Draft202012Validator(schema).validate(data) or iterate .iter_errors(data) to surface all errors at once instead of failing on the first.

For quick iteration without writing code, I usually paste the schema and a sample payload into a JSON formatter to confirm both parse, then run them through a browser-based validator. When debugging an unexpected failure, a diff checker helps me compare a failing payload against a known-good payload to spot the offending field.

JSON Schema vs OpenAPI vs TypeScript

These three describe data shapes but solve different problems:

TypeScript types are compile-time only. They vanish at runtime, so a malformed API payload will silently corrupt your program if you trust the type without validating. Great for developer ergonomics, useless for runtime safety.
JSON Schema is runtime validation that works in any language. Use it at API boundaries, for config files, for database documents, and for any cross-language data contract. A single schema can drive validation in your Node frontend, Python backend, and Go worker without rewriting.
OpenAPI (formerly Swagger) wraps JSON Schema inside an API description. It adds endpoints, methods, status codes, authentication, examples, and tooling for client SDK generation. Use it when you are describing an HTTP API and want documentation, client codegen, and validation in one document.

The stack I default to now: write the JSON Schema as source of truth, generate TypeScript types from it with json-schema-to-typescript, and embed the same schema inside an OpenAPI spec for HTTP routes. One source, three outputs, no drift.

The mistakes I kept making

1. Forgetting `additionalProperties: false`

The original bug. Without it, any extra field passes validation. A client typo like { "emial": "x@y.com" } validates as "no email present plus an unknown field" instead of the clean error you want. Add it by default.

2. Confusing `required` with `type`

Listing a property under properties does NOT make it required. You must also add it to the required array. Conversely, required only checks presence. A wrong-type field still fails, but on the type check, not the required check.

3. Using `format` without enabling assertion

In Ajv you must require('ajv-formats')(ajv). In Python jsonschema pass format_checker=FormatChecker(). Without this, format: email is metadata only and accepts any string. I burned half a day on this one.

4. `oneOf` where `anyOf` is correct

oneOf rejects data that matches more than one subschema. If your subschemas overlap (a value that is both a positive integer and a multiple of 5), oneOf rejects. Use it only for genuinely disjoint cases like discriminated unions.

5. `multipleOf` with floats

IEEE 754 cannot exactly represent 0.1. { "multipleOf": 0.1 } will reject values you expect to pass. Use integer units (cents, basis points) instead.

6. Recompiling schemas on every request

Ajv's compile() is expensive. The compiled validator is fast. Compile once at module load, store the function, reuse it.

Closing thought

JSON Schema looks verbose at first. Often the schema is longer than the data. That is the point. Every constraint you encode is one bug you cannot ship. Start with your top three API endpoints, then your config files, then your cross-service messages. Within a sprint you will catch at least one bug that would have made it to production.

If you want a sandbox, try the JSON Schema Reference Tutorial and an online validator like jsonschemavalidator.net. And if you ever debug a pattern validation that is misbehaving, a regex tester is faster than guessing.

Originally published at calculators.im.

I Keep Forgetting Subnet Math — Here's the Cheat Sheet I Actually Use

Anh Quân Nguyễn — Tue, 19 May 2026 03:17:29 +0000

I have been writing backend code for years and I still cannot tell you, off the top of my head, how many usable hosts are in a /22. Every time I open an AWS VPC config or a Kubernetes cluster blueprint, I do the same Google search: "subnet calculator", click whatever ranks first, type my CIDR, write down the answer. Then I forget all of it within a week.

After the fourth or fifth time I had to look up whether /27 gives me 30 or 32 usable IPs, I sat down and built a one-page cheat sheet for myself. This post is that cheat sheet, plus the few mental shortcuts that have actually stuck. If you ship to cloud and only touch subnet math a few times a year, this is the post I wish I had bookmarked.

The three numbers that matter

For any CIDR, only three numbers matter in practice:

Block size — how many IPs total. Formula: 2^(32 − prefix). A /24 has 256 addresses.
Usable hosts — block size minus 2 (one for the network address, one for the broadcast). A /24 has 254 usable.
Magic number — 256 − mask_octet. Tells you where the next subnet starts. For /26 (mask 255.255.255.192), the magic number is 64, so subnets land at .0, .64, .128, .192.

Memorize one table and you will never need to do binary math in your head again:

Prefix	Block size	Usable hosts	Mask	Magic
/22	1,024	1,022	255.255.252.0	4 (3rd octet)
/23	512	510	255.255.254.0	2 (3rd octet)
/24	256	254	255.255.255.0	—
/25	128	126	255.255.255.128	128
/26	64	62	255.255.255.192	64
/27	32	30	255.255.255.224	32
/28	16	14	255.255.255.240	16
/29	8	6	255.255.255.248	8
/30	4	2	255.255.255.252	4

That is the entire subnet math for 99% of cloud work. Print it, tape it to your monitor, move on.

The magic number trick, with a worked example

Suppose someone gives you the IP 10.20.30.45/26 and asks for the network and broadcast addresses. No calculator, no binary conversion.

Prefix is /26, so the magic number is 64.
Look at the last octet: 45. Which multiple of 64 does it fall into? 0, 64, 128, 192. 45 is in the 0–63 block.
Network address: 10.20.30.0. Broadcast: 10.20.30.63 (one less than the next subnet, which would start at .64).
Usable range: 10.20.30.1 to 10.20.30.62.

Same trick for prefixes that fall in the third octet. 10.20.30.45/22 → magic number is 4, applied to the third octet. 30 falls in the 28–31 block (because 28 is the closest multiple of 4 at or below 30). Network: 10.20.28.0. Broadcast: 10.20.31.255. Block spans four /24s.

If your subnet boundaries do not look "round" — say 10.20.30.0/22 — that is a malformed CIDR. The network address must align to the magic number. 10.20.30.0 is not a valid /22 start; 10.20.28.0/22 is.

Cloud-specific gotchas you will hit

The textbook subnet math is the easy part. What actually trips up cloud engineers is the platform-specific quirks layered on top.

AWS VPC

AWS reserves five addresses per subnet, not two. The network address, the broadcast, and three more: the VPC router, DNS, and a future-use address. So a /28 AWS subnet has 11 usable IPs, not 14. This catches people every time they try to fit "exactly 14 EC2 instances" into a /28 and run out of IPs at instance #12.

VPC CIDR sizing also has hard limits: minimum /28, maximum /16. You can attach secondary CIDR blocks, but you cannot ever shrink a primary CIDR after creation. Always size up. A /16 gives you 65,536 addresses for free; there is no cost penalty for picking a large VPC CIDR and no benefit to picking a tight one.

Kubernetes

A typical EKS or GKE cluster needs three separate CIDRs:

Node CIDR — a subnet of the VPC, one IP per node (plus AWS's five). Size for max-nodes × 2.
Pod CIDR — usually 10.244.0.0/16 (Flannel default) or 192.168.0.0/16 (Calico). Each node gets a /24 slice (Flannel) so the cluster maxes out at 254 nodes with a /16 pod CIDR. Larger clusters need /12 or smaller per-node allocations.
Service CIDR — usually 10.96.0.0/12 (kubeadm default). Sized for total Services, not Pods. A /16 is overkill for most clusters; a /20 is plenty.

The most common k8s networking mistake is overlapping the pod CIDR with the VPC CIDR. Pick non-overlapping ranges from day one — renumbering pod CIDR in a running cluster is a recreate-the-cluster operation.

Docker

Docker's default bridge is 172.17.0.0/16. The default docker network create allocates from 172.18.0.0/16 upward in /24 chunks. If your corporate VPN also uses 172.x.x.x ranges (very common), you will get phantom routing failures where Docker containers can reach the internet but cannot reach internal services. Reconfigure Docker's default address pools in /etc/docker/daemon.json:

{
  "default-address-pools": [
    {"base": "10.99.0.0/16", "size": 24}
  ]
}

This carves Docker out of the 172.x space and into a private 10.x range your VPN almost certainly does not use.

Subnet math in code (Python and Go)

When you actually need to compute subnets programmatically — generating Terraform, validating user input, planning a migration — every modern language has a stdlib for this.

Python uses ipaddress:

import ipaddress

# Parse a network
net = ipaddress.ip_network("10.20.30.0/22")
print(net.network_address)    # 10.20.28.0 — auto-normalized!
print(net.broadcast_address)  # 10.20.31.255
print(net.num_addresses)      # 1024
print(len(list(net.hosts()))) # 1022 — excludes network + broadcast

# Check if an IP is in a subnet
ip = ipaddress.ip_address("10.20.29.50")
print(ip in net)  # True

# Subdivide a /22 into /24s
for sub in net.subnets(new_prefix=24):
    print(sub)
# 10.20.28.0/24
# 10.20.29.0/24
# 10.20.30.0/24
# 10.20.31.0/24

# Detect overlap (catches the VLSM mistake from earlier)
a = ipaddress.ip_network("10.0.0.0/25")
b = ipaddress.ip_network("10.0.0.64/26")
print(a.overlaps(b))  # True

Note: passing strict=False to ip_network lets you parse 10.20.30.0/22 (a malformed CIDR — .30 is not the network address). With strict=True (the default since Python 3.9) it raises ValueError. Use strict=True in production input validation; the explicit error is far more useful than a silently-corrected network.

Go uses net/netip (Go 1.18+):

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    prefix, _ := netip.ParsePrefix("10.20.30.0/22")
    // Normalize to actual network address
    prefix = prefix.Masked()
    fmt.Println(prefix.Addr())   // 10.20.28.0
    fmt.Println(prefix.Bits())   // 22

    ip, _ := netip.ParseAddr("10.20.29.50")
    fmt.Println(prefix.Contains(ip))  // true
}

The older net.IPNet API still works but net/netip is value-typed, allocation-free, and the recommended choice for new code.

A 30-second AWS CLI sanity check

When debugging "why can't my EC2 instance reach this other EC2 instance," step one is always: are they on subnets that route to each other? Quick CLI check:

# List subnets with their CIDRs in the current VPC
aws ec2 describe-subnets \
  --query 'Subnets[*].[SubnetId,CidrBlock,AvailabilityZone]' \
  --output table

# Check route table for a subnet
aws ec2 describe-route-tables \
  --filters Name=association.subnet-id,Values=subnet-abc123 \
  --query 'RouteTables[*].Routes' \
  --output table

If two subnets are in the same VPC and the route tables both have local routes for the VPC CIDR, they can reach each other (assuming security groups and NACLs allow). Most "why no connectivity" tickets resolve here.

Three mistakes I have personally shipped to production

Subnet too small. A /28 for "we only need 10 instances" — then AWS takes 5, leaving 11. Add a load balancer, add scaling, you are out of IPs. Always start at /24 for any production subnet unless you have a hard reason not to.

Pod CIDR overlapping VPC CIDR. Created a GKE cluster with default pod CIDR 10.0.0.0/14 inside a VPC at 10.0.0.0/16. Cluster came up, pods on the same node could reach each other, pods on different nodes silently dropped traffic. Three hours debugging later: pick non-overlapping CIDRs.

Forgot AWS's 5 reserved IPs. Provisioned 14 EC2 instances in a fresh /28. First 11 launched fine, the rest failed with InsufficientFreeAddressesInSubnet. The fix is /27 (32 addresses, 27 usable after AWS reservations).

Closing — make subnet math boring

The whole point of the cheat sheet is that subnet math should be boring. You should not have to think about it. You should be able to glance at a CIDR, know the block size and the magic number, and move on to whatever interesting problem you were actually trying to solve.

If you need to verify a non-trivial CIDR or plan a VLSM allocation across multiple subnets, I built a free subnet calculator that handles IPv4, IPv6, and VLSM planning. There's also a longer-form guide on the math behind CIDR, VLSM, and IPv6 subnetting if you want to go deeper than this cheat sheet.

The tool is free, no signup, no tracking. If it saves you a Google search next quarter, that is the entire goal.

Cross-posted with canonical from calculators.im.

Lessons Learned Building 270+ Online Calculators: A Developer's Deep Dive

Anh Quân Nguyễn — Tue, 21 Apr 2026 10:26:03 +0000

When I started building calculators.im, I thought it would be a simple project — create a few calculator pages, deploy, done. Two years and 270+ calculators later, I've learned more about web performance, SEO, and product scaling than I ever expected. Here's everything I wish someone had told me before I started.

The Project: What Is calculators.im?

calculators.im is a collection of 270+ free online calculators covering everything from finance (mortgage, compound interest, ROI) to health (BMI, calorie needs, pregnancy due date) to math (scientific, percentage, fractions) and beyond.

The tech stack: Go for the backend, HTMX for interactivity, Tailwind CSS for styling, Redis for caching, and NGINX + Cloudflare for serving.

Lesson 1: SEO Is 80% of Your Traffic — Treat It as a Feature

I originally thought "build good calculators and they'll come." Wrong.

The reality: calculator sites are brutally competitive. There are dozens of sites competing for every keyword like "mortgage calculator" or "BMI calculator." Here's what actually works:

Target long-tail keywords over short ones. Instead of competing for "loan calculator" (dominated by Bankrate, NerdWallet), target "car loan calculator with extra payments" or "loan calculator with balloon payment." Lower competition, still significant volume.

Schema markup is non-negotiable. Adding WebApplication and FAQPage schema to each calculator dramatically increased click-through rates. Google often shows rich results in SERPs for tool pages with proper schema.

Page speed = ranking factor for tools. Users expect calculators to respond instantly. Every 100ms of latency costs you. With Go + HTMX, our Time to First Byte (TTFB) is under 50ms globally thanks to Cloudflare caching.

Lesson 2: HTMX Was the Right Bet — But Has Trade-offs

Choosing HTMX over React was controversial when I started. Here's the honest verdict after building 270 pages:

Wins:

Zero client-side hydration = better Core Web Vitals (LCP, CLS)
SEO-friendly by default — all content is server-rendered
Bundle size: ~14kb for htmx vs 130kb+ for a React app
Simpler mental model: HTML attributes over JavaScript state management

Trade-offs:

Complex interactions (real-time charts, drag-and-drop) require either Hyperscript or vanilla JS alongside HTMX
The community is smaller than React's, so fewer StackOverflow answers
Some HTMX patterns feel verbose for highly dynamic UIs

Would I choose HTMX again? Yes — especially for content-heavy tool sites where SEO matters. For a complex SaaS dashboard, I'd reconsider.

Lesson 3: Go Is Overkill for Small Projects — Perfect for Scale

Go was genuinely the right choice, but not for the reasons I expected:

Memory footprint: Our entire server runs on a $6/month VPS and handles thousands of daily visits with ~30MB RAM usage. A Node.js equivalent would use 5-10x more memory.

Compilation catches bugs early. Go's strict type system eliminated an entire category of runtime errors that plague dynamic-language projects.

Single binary deployment. go build, rsync to server, restart. No npm install, no dependency conflicts, no environment issues.

The unexpected lesson: Go forces you to be explicit about error handling. At first this feels tedious (if err != nil everywhere), but it makes your code dramatically more reliable in production.

Lesson 4: Calculator UX Is Harder Than It Looks

Building a "simple" calculator that delights users involves surprisingly subtle decisions:

Input formatting: Users expect numbers to auto-format (1000 → 1,000) as they type. Implementing this with HTMX + Go required careful input sanitization to avoid formatting conflicts.

Instant results: Never make users click a "Calculate" button. Use HTMX's hx-trigger="input" to recalculate on every keystroke. Users expect calculator-app behavior from web calculators.

Mobile-first number inputs: On mobile, use inputmode="decimal" rather than type="number". The decimal keyboard is much better than the native number input's spinner interface for financial inputs.

Error states matter: When a user enters invalid input (letters in a number field, negative age, etc.), show clear, friendly error messages in context — not a page-level alert.

Lesson 5: The Content Around the Calculator Matters More Than the Calculator

This was my biggest revelation: the page content surrounding the calculator is more important for SEO than the calculator itself.

Every calculator page on calculators.im includes:

A 500-800 word explanation of the formula and methodology
A worked example with real numbers
An FAQ section targeting "People Also Ask" queries
A table of common values for reference

This content strategy is what earns backlinks, ranks for informational queries, and keeps users on the page longer — all positive signals.

Lesson 6: Redis Caching Saved Us at Scale

When a Reddit post linked to our percentage calculator, we got ~8,000 visits in 2 hours. Without Redis caching:

Every request would hit Go and render the page fresh
At 8,000 req/hr, that's manageable but wasteful

With Redis:

Static page HTML is cached for 1 hour
Dynamic calculation results are cached by input parameters
Cache hit rate during the spike: 94%
P99 response time during the spike: 18ms

The caching strategy: cache at two layers — page-level (full HTML response via Cloudflare) and calculation-level (Redis for computed results with the same inputs).

Lesson 7: Build the Infrastructure Once, Deploy 270 Times

The most important architectural decision was treating calculators as data, not code.

Each calculator is defined by a YAML config file:

Input fields with types, labels, validation rules
Formula as a Go expression
Output formatting
SEO metadata

The Go backend reads these configs and generates both the HTML and the calculation logic dynamically. Adding a new calculator takes about 15 minutes — write the YAML, write the formula, deploy.

This approach let us go from 10 calculators to 270+ without a linear increase in development time.

What I'd Do Differently

Start with the content strategy, not the calculator. Write the explanatory content first, then build the tool around it.
Add structured data from day 1. Retrofitting schema markup to 270 pages was painful.
Build analytics from the start. Understanding which calculators get used heavily vs. which ones are ignored shapes your roadmap.

The Stack in Summary

Backend: Go — fast, cheap to run, rock-solid
Frontend interactivity: HTMX — SEO-friendly, tiny footprint
Styling: Tailwind CSS — consistent, maintainable
Caching: Redis — essential at any meaningful scale
Infrastructure: NGINX + Cloudflare — global performance, free DDoS protection

If you're building a similar tool site, I hope this saves you some of the trial and error. Check out calculators.im to see what 270 calculators looks like in practice.

What questions do you have? Drop them in the comments — happy to go deeper on any of these lessons.