Specification

citemap.json — v3.4

The normative specification, rendered straight from the canonical Markdown source. Released 2026-06-02 · MIT · backward-compatible with v2.0–v3.3.

View source on GitHub ↗Vocabulary registry →

citemap.json Specification v3.4

Vocabulary expansion release: 14 new canonical primaryVertical values across 9 underserved business categories. Strictly additive on v3.3.

Status: Released 2026-06-02 Version: 3.4 Date: 2026-06-02 Authors: Brian Pofahl License: MIT Schema: https://citemaps.org/schema/v3.4/citemap.schema.json Vocabulary registry: ./registry/v3.4-vocabulary.md Backward Compatibility: Every valid v2.0, v3.0, v3.1, v3.2, and v3.3 citemap validates against v3.4 with at most a version field bump.

Overview

v3.4 is a vocabulary expansion minor bump on v3.3. No schema-shape changes, no field additions, no semantic renames — just 14 new canonical values added to the primaryVertical recommended-values registry.

The motivation is empirical. The v3.3 release retired manufacturer, industrial-services, membership-org, and local-business from the recommended-vertical list on the theory that manufacturing is a how (business model) and the user-facing vertical should be a what (market sector). That theory holds for manufacturers serving a single downstream sector (a food manufacturer = food-beverage, an apparel DTC = ecommerce). It breaks for cross-sector industrial suppliers (specialty filaments, fasteners, coatings, contract manufacturers, materials processors) whose market is "industrial-at-large." v3.3 left this segment without a clean home — surfaced by the 2026-06-02 Western Filament dogfood when the picker showed no canonical fit for an industrial-textile supplier.

The same dogfood pass exposed a broader gap: nine real-world business categories with no canonical vertical. v3.4 closes them all in one bump rather than piecemeal across the next several point releases.

The 14 additions break down as:

  1. Tier 1 (5 additions, full playbook depth): industrial, religious, it-services, veterinary, marketing-agency. Each is a category with hundreds of thousands or millions of US businesses, distinct directories and SEO playbook, and no current canonical home.

  2. Tier 2 (9 additions, supported with inherited playbook): funeral, fitness, transportation, performing-arts, cannabis, government, beverage-producer, photography, pharmacy. Each is a real segment with its own directory ecosystem but smaller population or sufficient adjacency that lighter playbook depth is acceptable for now.

After v3.4:

  • Tier 1: 24 → 29 recommended values (was 23 in v3.3; 24 reflects the Tier 1 set with local-business excluded from active picker but still in legacy alias map)
  • Tier 2: 8 → 17 recommended values
  • Total canonical: 32 → 46 recommended primaryVertical values

The bump is published as a MINOR rather than a PATCH because the registry's contract with consumers (third-party generators like Yoast, Rank Math, next-seo + the citemaps.org validator) explicitly requires a minor bump for any change to recommended-vocabulary. Patch bumps are reserved for documentation fixes and typos.

What's not in v3.4

v3.4 is deliberately scoped narrow. The following items remain parked for future releases:

  • @graph / relationships[] emission in Studio's reference implementation — spec-side defined in v3.3 §1 + §2 but Studio doesn't auto-derive yet. Planned for v3.5.
  • Per-vertical Property field extensions for the 14 new v3.4 verticals (industrial materials/capabilities, religious denomination/service-times, veterinary species-treated, etc.). Will land as each vertical gets dogfooded.
  • Policy section editor + emission path. Planned for v3.5.
  • Foundational-section emission audit — confirming every Studio citemap.json emits all 10 foundational sections per v3.3 §3 even when no user data fills them. Tracking item, not a spec change.

§1. Vocabulary additions

The full set of v3.4 vocabulary additions lives in the v3.4-vocabulary registry. This section summarizes; the registry has the canonical descriptions.

§1.1 Tier 1 additions

Value Replaces / fills gap Notes
industrial The post-v3.3 gap left by retiring manufacturer + industrial-services for cross-sector industrial suppliers Pair with modifiers: ["manufacturing-direct"] for producers; modifiers: ["b2b"] always applicable
religious Was being mapped to nonprofit (Tier 2), losing access to church-finder directories + service-time SEO patterns Distinct ecosystem (denominational directories, Faithstreet, ChurchFinder, etc.)
it-services Was being mapped to professional-services (Tier 1 catchall) or saas (which is a product, not a service) Distinct vendor-partner directories (Clutch IT, G2 Services, vendor partner finders)
veterinary Was being mapped to pet-services (grooming/boarding/training) or healthcare (human medicine) Distinct AVMA-adjacent directories + vet-board licensing context
marketing-agency Was being mapped to creative-agency (brand/design) Distinct agency-finder directories (Sortlist, Clutch agency, agency-finder sites)

§1.2 Tier 2 additions

Value Replaces / fills gap Notes
funeral No prior home Distinct industry (funeral home directories, NFDA, pre-need-planning SEO)
fitness Was being mapped to beauty-wellness (appearance/wellbeing) Distinct directory ecosystem (ClassPass, MindBody, gym-finder sites)
transportation Was being mapped to logistics (B2B supply chain) Passenger transport + specialty freight are different from supply-chain logistics
performing-arts Was being mapped to events-venue (event hosting) Artistic production companies + their venues, different from event-hosting venues
cannabis Was being mapped to food-beverage or retail Distinct regulatory + directory ecosystem (Weedmaps, Leafly, state registries)
government Was being mapped to nonprofit with entityType: "government-entity" patch Now first-class — pairs with existing entityType: "government-entity" + organizationType: "government"
beverage-producer Was being mapped to food-beverage (broader retail/production) Specifically fermented/distilled beverage production with its own SEO + directories (Untappd, RateBeer, Distiller, Vivino)
photography Was being mapped to creative-agency (multi-channel design work) Distinct craft — wedding/portrait/commercial photographers aren't agencies
pharmacy Was being mapped to healthcare (provider) Distinct dispensing-side function with its own retail + medical schema requirements

§2. Backward compatibility

Every v3.0/v3.1/v3.2/v3.3 citemap.json validates against v3.4 with at most a version field bump. No fields renamed, no fields removed, no validation rules changed.

Consumers reading a v3.4 document MAY encounter a primaryVertical value not in their cached vocabulary list. The recommended consumer behavior:

  1. Accept the value as a valid string (validators MUST NOT reject unrecognized primaryVertical values per v3.3 §5.2)
  2. Refresh the vocabulary registry on next opportunity (the registry version field tells you which catalog version you're reading against)
  3. Until the registry is refreshed, fall back to the entity's additionalVerticals + modifiers + siteType for module routing

The v3.3 dual-write window for the four renamed legacy values (legal, financial, events, research) remains open through v3.4. v3.5 is scheduled to drop the legacy aliases per the v3.3 deprecation log.

§3. Producer guidance

Producers updating from v3.3 to v3.4 SHOULD:

  1. Emit version: "3.4" once the local vocabulary cache + the citemaps.org registry both include the v3.4 additions.
  2. Re-prompt users who self-selected a poor-fit vertical in v3.3 (most likely candidates: businesses that picked professional-services as a catchall when they actually fit it-services, marketing-agency, or industrial).
  3. Continue accepting + dual-writing the v3.3 legacy aliases through v3.4.

Producers MAY continue emitting version: "3.3" until they have updated their vocabulary cache; v3.4 makes no demands on producers who haven't expanded their picker.

§4. Consumer guidance

Consumers reading v3.4 documents SHOULD:

  1. Update vocabulary cache to include the 14 new primaryVertical values.
  2. Map the new values to their internal categorization if relevant (e.g., a recommender system mapping primaryVertical → ranking weights).
  3. Fall back gracefully when reading a v3.4 value not yet in the cache — don't reject the document, treat it as a string that will be added in the next vocabulary refresh.

§5. Open items

  • Per-vertical Property field extensions for the 14 new verticals — Studio's reference implementation currently uses field extensions for some Tier 1 verticals (restaurant has cuisine/priceRange, healthcare has specialties/insurances, saas has integrations/pricingTiers, etc.). Adding similar extensions for industrial / religious / it-services / veterinary / marketing-agency is parked. Will roll out as each vertical sees real dogfood signal.

  • Query packs + outreach templates per new vertical — the vertical config declares the query-pack and outreach-template groups by name; the actual template content layers in over time.

  • Vocabulary URL stability — the type-vocabulary URIs at https://citemaps.org/v3.4/types/{type} should resolve. They currently 404 because the Astro site hasn't published the type-detail pages yet. Tracking; not blocking the v3.4 release because the URIs serve as stable identifiers rather than fetchable resources.

Related