Package com.kazforge.jsonapi.diagnostic

@NullMarked package com.kazforge.jsonapi.diagnostic

Stable backend-independent document-read and mapping diagnostic families.

JsonApiDocumentReadException reports JSON decoding and core local or aggregate validation failures. Adapter-produced instances carry a document-relative JSON Pointer ("" for the document root), a payload-safe best-effort SourceLocation, and a core validation rule code when validation supplied one.

JsonApiMappingException reports domain mapping, binding, registry, and representation failures through a stable MappingDiagnostic. Its optional MappingLocation is a validated JSON Pointer over wire names; direct resource operations use resource-relative locations and envelope composition may prepend a document-relative prefix. No applicable member location is represented by null, never "" or /.

The families remain separate: successful document decoding followed by a domain-mapping failure is not reclassified as a document-read failure.

Class	Description
CodecFailureCategory	Stable decoding or validation stage for a JsonApiDocumentReadException.
JsonApiDocumentReadException	Failure while decoding or validating a JSON:API document.
JsonApiMappingException	Backend-independent domain mapping, binding, registry, decoration, or representation failure.
MappingDiagnostic	Stable semantic codes for mapping, binding, registry, decoration, and representation failures.
MappingLocation	A validated mapping-diagnostic location: a JSON Pointer (RFC 6901) that is absent (null) on the owning JsonApiMappingException when no member location applies.
SourceLocation	Backend-independent payload-safe source position for a document-read diagnostic.