Veterinary Service Data Schema: Rules and Doctrines

Purpose

This document is the operating rulebook for classifying, maintaining, and extending the veterinary service schema. It governs how every decision is made — from whether a procedure deserves its own service slug to how CMA compliance evidence is structured.

These doctrines keep three things true simultaneously:

1. Clinical integrity — the schema accurately represents real veterinary pathways.
2. Market comparability — consumers and regulators can compare equivalent services across clinics.
3. Implementation discipline — changes are controlled, documented, and auditable.

Status Vocabulary

All documentation, rollout notes, and external communications use consistent state labels:

These labels are not decorative. They are the authoritative source for what is production-ready and what is in controlled rollout.

1. Classification Doctrine

When something becomes a new service slug

Create a new slug only when one or more of the following are true:

• The clinical pathway is materially different.
• The components required for a standard pathway differ materially.
• The care setting or regulatory context differs materially.
• The package structure creates a genuinely distinct comparable product.

When something is a pricing dimension

Use price-row dimensions (not new slugs) when variation is primarily:

• Weight or size tiering (S / M / L / XL / G).
• Quantity tiering (area count, session count).
• Time-window differentiation (Day / Night / 24-Hour / Package).
• Pricing presentation mode (Headline / Itemised).
• Pricing context (Standard / Plan / With-Other-Service).

This is a critical design principle. The schema currently supports five orthogonal dimensions on a single price row — weight band, time window, pricing mode, pricing context, and hospitalisation care level. This eliminates the combinatorial explosion that would otherwise require hundreds of duplicate service slugs.

When something is a component variation

Keep one service slug and model the difference in component mappings when:

• The core procedure identity is unchanged.
• Variation is in inclusion/exclusion and line-item composition.
• A clinic may bundle vs separately charge the same underlying component.

When something is a note or qualifier

Use notes for administrative caveats, temporary availability constraints, or non-structural wording differences. Do not promote a note into schema entities unless it repeatedly affects comparability outcomes.

2. Species-Split Doctrine

Merge species into one slug when:

• The clinical pathway is materially equivalent across species.
• Species is primarily an applicability or pricing concern, not a pathway concern.
• Applicability is representable via animals[] tags with price differentiation via row dimensions.

Keep species-specific slugs when:

• Pathway or protocol differs materially (e.g. cat spay vs bitch spay — different anatomy, different anaesthetic risk).
• Component model differs materially (e.g. rabbit neutering requires different anaesthetic approach).
• Regulatory or specialist context is materially distinct.

Price difference alone is never sufficient to force a species split. If the procedure is clinically equivalent and only the price differs by species, model it as one service with species on the price row.

Animal-type allocation

Services carry canonical animals[] tags. These are applicability markers, not pricing axes:

• An empty animals[] means the service is applicable across all standard species — it does not mean "unknown" or "unclassified".
• Species-specific services explicitly list applicable animals.
• Remediation of animal-type misallocation follows a controlled pipeline with manifest, verification, and policy guardrails.

3. Hierarchy Doctrine

GROUP — taxonomy containers

Use GROUP to organise related services for discovery and comparison. Groups contain child services and define comparison pathways (e.g. "Puppy Vaccinations" groups individual dose and course children).

Groups never carry prices or component mappings. Pricing endpoints are always child ATOMIC or COURSE services. This separation prevents taxonomy navigation from being entangled with transactional pricing.

COURSE — packaged pathways

Use COURSE for multi-step packaged pathways where quantity and structure are part of the product identity (e.g. a 3-dose puppy vaccination course).

Courses are preserved as distinct services when the package structure creates a genuinely different comparable product. A 2-dose course and a 3-dose course are different products — flattening them destroys comparability.

ATOMIC — single clinical units

Use ATOMIC for single-encounter procedures. These are the primary pricing endpoints — the level at which consumers compare and clinics publish.

4. Component Doctrine

What components represent

ServiceComponent entities represent reusable billable or clinical units that appear across multiple services: general anaesthetic, surgical procedure, hospitalisation, laboratory fee, medication, post-operative care.

Each component carries structured defaults:

• Default pricing method (Fixed, From, Range, Per Unit).
• Unit type (Per Tooth, Per Night, Per Day, Per 24 Hours, Per Dose, Per Session, Per kg, Per Implant, and more).
• Variable/fixed intent — whether the component typically varies by case or is fixed.

Inclusion-status interpretation

isRequired on a mapping means "typically expected in the standard clinical pathway." It is a clinical expectation marker, not a hard validation constraint — clinics can deviate where clinically appropriate.

Hospitalisation care levels

Hospitalisation is modelled with both time-window and care-level resolution:

• Time windows: Day, Night, 24-Hour, Package.
• Care levels: Standard, Medical, Intensive.

This allows the schema to represent the full range of hospitalisation pricing — from a simple overnight stay to intensive 24-hour critical care — without collapsing materially different care contexts into a single rate.

5. Package and Bundle Doctrine

Courses, bundles, and combined services are preserved when they are materially distinct products in the market. Do not flatten all package variants into a generic parent.

For example:

• A puppy vaccination course (3 doses) and a single booster dose are different products.
• An annual vaccination with health check and one without are different products.
• A dental scale-and-polish bundled with extraction and one without are different products.

The test: if a consumer choosing between Package A and Package B would reasonably consider them different products, they should be different services in the schema.

6. Variant-Boundary Doctrine

Use this decision framework:

• Same service, different dimension — when identity is clinically equivalent and differences are best represented as weight bands, time windows, or pricing contexts.
• Same service, different component mapping — when the core procedure is the same but inclusion/exclusion of components differs.
• Different service — when the clinical pathway, required component baseline, or package semantics are materially different for comparison purposes.

When uncertain, default to preserving comparability first. Consolidate only when evidence strongly supports it.

7. Weight-Band Doctrine

Weight banding uses a canonical 5-tier model:

Weight bands are price-row dimensions, not separate service slugs. A single service (e.g. Dog Castration) can have up to five price rows differentiated by weight band.

Weight-band inference from free-text pricing is handled by the AI extraction pipeline, normalising the wide variety of clinic-specific band descriptions into the canonical tiers.

8. CMA Compliance Doctrine

Scope

The CMA compliance layer covers the full lifecycle of pricing transparency:

• What must be disclosed — defined by a locked 36-line CMA service registry.
• How disclosure is structured — through the schema's component and inclusion model.
• Where it is published — via publication targets (managed site, clinic profile, hosted fallback).
• How publication is proved — through typed proof records with strength ratings.
• How compliance is maintained — through state machine progression and drift detection.

Evidence standards

Every compliance action generates auditable proof:

Proof records carry strength ratings (Primary, Supporting, Informational) so that compliance assessments can distinguish between direct evidence and corroborating context.

State management

Compliance status follows a defined state machine:

Not Started → Draft in Progress → Ready for Review → Partially Published → Fully Published → Compliant.

Degradation states (Stale, Broken Since Publish, Non-Compliant) are detected automatically through drift monitoring. This ensures compliance is actively maintained, not just achieved once and forgotten.

Group-level compliance

For corporate veterinary groups, compliance policies can be defined at group level and inherited by member clinics. This enables estate-wide compliance management without requiring per-clinic manual oversight.

9. Alias and Legacy Doctrine

• Legacy naming variants are handled via explicit alias mapping. Concept identity is preserved without maintaining duplicate service slugs.
• Deprecated naming remains traceable for audit purposes but is removed from primary authoring paths.
• Canonical mapping is never inferred ad hoc from label similarity in production workflows. All mapping is explicit and reviewable.

10. Extension Doctrine

New services or components are added only when there is sustained evidence that current entities cannot represent the pathway cleanly.

Evidence threshold combines:

• Clinical distinction — is the pathway genuinely different?
• Market frequency — do enough clinics offer this to justify structured representation?
• Comparability impact — does the absence of this entity degrade comparison quality?
• Implementation cost — what is the migration and downstream impact?

Extensions follow the same controlled-batch rollout: catalog-seeded first, promoted to live-verified only after mapping, alias, and read-path validation pass.

11. Governance and Change Control

For external credibility and regulatory confidence, all schema changes are:

• Explicitly documented with rationale.
• State-labelled (live-verified / catalog-seeded / exception-tracked).
• Backwards-aware for existing comparison and audit paths.
• Reviewed against these doctrines before rollout.
• Auditable through compliance event logs with actor, timestamp, and event type tracking.

No schema change reaches production without passing through this governance framework.