Validator error codes: two-level vs single-level primitive checks

[niquola]

Context

We are designing the error code system for the new FHIRSchema validator. The validator returns ValidationIssue[] (empty = success) with codes like fs101, fs107, etc.

See full draft: docs/new/error-codes.md

The question

For primitive type validation, should we have two levels or one level of error codes?

Option A: Two levels (JSON type then FHIR literal)

First check JSON type, then validate the literal:

birthDate: 123       -> fs101 expected-string
birthDate: "30-02"   -> fs107 invalid-date

Code	Name	Description
fs101	expected-string	Expected JSON string, got number/boolean
fs102	expected-number	Expected JSON number, got string/boolean
fs103	expected-boolean	Expected JSON boolean, got string/number
fs107	invalid-date	Bad format or impossible calendar date
...	invalid-*	One code per FHIR primitive type

Pros:

• JSON type checks are fixed (3 codes), FHIR literal validators are pluggable
• Can enable/disable individual FHIR type validators independently
• New primitive types can be added without touching JSON layer
• Clear separation of concerns: JSON shape vs FHIR semantics

Option B: Single level (FHIR type only)

One code per FHIR type covers both JSON type and literal:

birthDate: 123       -> fs107 invalid-date (message: expected string, got number)
birthDate: "30-02"   -> fs107 invalid-date (message: impossible calendar date)

Pros:

• Fewer codes, simpler
• User sees FHIR-meaningful error immediately
• expected-string for integer64 field (which IS a JSON string) is confusing
• TypeScript/Rust compilers do not separate token-level from semantic-level errors
• No question about emitting 1 vs 2 issues per field

FHIR primitive type tree

JSON boolean
  -- boolean

JSON number
  -- integer (int32)
     -- unsignedInt (>= 0)
     -- positiveInt (> 0)
  -- decimal

JSON string
  -- string / markdown
  -- code, id
  -- uri -> url, canonical, oid, uuid
  -- base64Binary
  -- date, dateTime, instant, time
  -- integer64 (64-bit int as string!)
  -- xhtml

What do you think?

Which approach is better for a validator that aims to become a community spec?