Diagnostic codes¶

Every defect medh5 validate can report, with the code it reports it under.

Codes are stable API. A code's meaning never changes and codes are never reused, so a pipeline may branch on one and a third-party validator is expected to emit the same code for the same defect. A minor format version may add codes; it may not change what an existing one means (spec §16).

The table below is generated from medh5/errors.py at build time — the same table the validator and the conformance corpus read, so it cannot drift from what the tool actually emits. Its normative statement is specification §15.2.

from medh5 import CODES

CODES["E102"].summary     # "`direction` is not orthonormal to 1e-4"
CODES["E102"].domain      # "geometry"
CODES["E102"].severity    # "error"

Reading a code¶

The first digit is the domain, which is usually enough to know which part of a file to look at:

Range	Domain
`E0xx`	container
`E1xx`	geometry
`E2xx`	images
`E3xx`	label set
`E4xx`	annotations
`E5xx`	transforms
`E6xx`	curation
`E7xx`	integrity
`W9xx`	warnings, across every domain

An error means the file does not conform. A warning means it conforms but something is worth knowing — a suspicious value, a derived object that is stale, a claim nothing corroborates. --level strict is what turns warnings into a non-zero exit; see profiles and validation levels.

Warnings are grouped with the domain they concern rather than in a block of their own, so everything about geometry is in one place.

71 codes: 59 errors and 12 warnings. Every one has a conformance case.

Container¶

Code	Severity	Meaning
`E001`	error	missing or empty `medh5_version`
`E002`	error	unsupported major version
`E003`	error	identifier does not match [A-Za-z0-9_.-]{1,128}
`E004`	error	`meta` is absent or is not valid UTF-8 JSON
`E005`	error	`meta` fails the sample-document JSON Schema
`E006`	error	missing or unknown `medh5_kind`
`E007`	error	missing `medh5_profiles`, or an unknown profile
`E008`	error	a group required by the layout is absent
`E009`	error	declared profile's requirements are not met
`E010`	error	sample root in a `collection` lacks its own `content_id`
`W902`	warning	bulk dataset is unchunked or uncompressed

Geometry¶

Code	Severity	Meaning
`E101`	error	referenced grid does not exist
`E102`	error	`direction` is not orthonormal to 1e-4
`E103`	error	spatial axes are not contiguous and trailing
`E104`	error	`spacing` is not strictly positive
`E105`	error	multiscale level geometry is inconsistent with level 0
`E106`	error	grid has no `timepoint` in a multi-timepoint sample
`E107`	error	grid `timepoint` names an undeclared timepoint
`E108`	error	`timepoints` is empty, or `index` is not dense/increasing
`E109`	error	required grid attribute is missing or has the wrong rank
`E110`	error	`axis_kinds` is invalid for the declared dimensionality
`E111`	error	`grids` contains no grid
`W910`	warning	grids in different timepoints share a `frame_uid`
`W911`	warning	multi-timepoint sample has no transform relating timepoints

Images¶

Code	Severity	Meaning
`E201`	error	`images` contains no image
`E202`	error	image shape does not equal its grid's `shape`
`E203`	error	unknown `value_type`
`E204`	error	`channel_names` length does not match the channel extent
`E205`	error	required image attribute is missing
`W907`	warning	float storage where int16 + rescale would be lossless

Label set¶

Code	Severity	Meaning
`E301`	error	a declared profile requires a label set and none is present
`E302`	error	duplicate class id or key in the label set
`E303`	error	a reserved class id (0 or 65535) was assigned to a class
`E304`	error	the class hierarchy contains a cycle
`E305`	error	`form: ref` label set lacks `uri`/`sha256`, or is unresolvable
`E306`	error	class entry is missing a required field or has a bad id range
`W912`	warning	class id used by an annotation has no ontology binding

Annotations¶

Code	Severity	Meaning
`E401`	error	unknown annotation `kind`
`E402`	error	class id is not present in the label set
`E403`	error	`annotated_class_ids` is not a subset of `class_ids`
`E404`	error	encoding invariant violated
`E405`	error	dataset shape is inconsistent with the grid
`E406`	error	box `lo` exceeds `hi`
`E407`	error	`rotations` is not a proper rotation matrix
`E408`	error	`mask_offsets` are not monotonically increasing
`E409`	error	`timepoints` references an undeclared timepoint
`E410`	error	a dataset required by the annotation `kind` is absent
`E411`	error	dataset dtype is not permitted for the annotation `kind`
`E412`	error	required annotation attribute is missing
`E413`	error	annotation references an object that does not exist
`E414`	error	`space` is invalid for the annotation's grid or frame
`W904`	warning	partial coverage without an ignore region
`W908`	warning	`layers` count is far from the greedy-colouring optimum
`W909`	warning	one `instance_id` carries two different class ids

Transforms¶

Code	Severity	Meaning
`E501`	error	composite frame chain is broken
`E502`	error	unknown transform `kind`
`E503`	error	displacement field grid is not in `from_frame`
`E504`	error	affine last row is not [0 … 0 1]
`E505`	error	`inverse_id` is not mutually consistent

Curation¶

Code	Severity	Meaning
`E601`	error	`prov` names an activity that does not exist
`E602`	error	`quality` names a record that does not exist
`E603`	error	unknown agent or activity type
`E604`	error	timestamp is not RFC 3339
`E605`	error	activity names an agent that does not exist
`W903`	warning	no `deidentification` record
`W906`	warning	conflicting split claims for one `set_id`

Integrity¶

Code	Severity	Meaning
`E701`	error	object digest does not match its content
`E702`	error	`content_id` does not match the file
`E703`	error	malformed digest string
`W901`	warning	no object digests are present
`W905`	warning	`index/` entry is stale for its source annotation

Profiles and validation levels — which of these get checked, and when.
Cohort check codes — the C1xx codes, which are a different space: they describe a cohort, not a file.
Conformance suite — one corpus case per code on this page.