Semantiva Contracts

Semantiva components follow a set of metadata and type-contract rules. The semantiva dev lint command audits components against these rules and prints diagnostics with stable Semantiva Validation Assertions (SVA) codes.

Rule catalog

| Semantiva Validation Assertions (SVA) enumerate contract checks enforced by semantiva dev lint. |

Code	Severity	Applies To	Summary	Trigger	Hint
SVA001	error	Any class defining input_data_type	input_data_type must be @classmethod	Method exists; inspect.getattr_static not classmethod	Add @classmethod and use cls
SVA002	error	Any class defining output_data_type	output_data_type must be @classmethod	Method exists; inspect.getattr_static not classmethod	Add @classmethod and use cls
SVA003	error	Any class defining *_data_type	*_data_type must be @classmethod	Name matches .*_data_type$	Add @classmethod and use cls
SVA004	error	Any class defining *_data_type	*_data_type returns a type	Return is non-type or call raises	Return a type (e.g., MyType)
SVA100	error	All components	_define_metadata/get_metadata return dict	Returned value not dict or raised	Return dict
SVA101	error	All components	Required metadata keys present	Missing any of class_name, docstring, component_type	Add missing keys
SVA102	warn	All components	Docstring too long	len(docstring) > LIMIT	Shorten summary
SVA103	error	All components (if parameters present)	parameters shape	Not in {dict, list, ‘None’, {}}	Normalize params
SVA104	error	All components (if present)	injected_context_keys list[str] unique	Not list of unique strings	Fix list
SVA105	error	All components (if present)	suppressed_context_keys list[str] unique	Not list of unique strings	Fix list
SVA106	warn	All components (if both present)	Injected vs suppressed overlap	set(injected) ∩ set(suppressed) non-empty	Reconcile keys
SVA107	error	All components	Registry/category coherence	Not present under its component_type in registry	Fix registration
SVA200	error	DataSource / PayloadSource (component)	Require output_data_type	Metadata lacks output_data_type	Add method/meta
SVA201	warn	DataSource / PayloadSource (component)	Forbid input_data_type	Metadata has input_data_type	Remove it
SVA210	error	DataSink / PayloadSink (component)	Require input_data_type	Metadata lacks input_data_type	Add method/meta
SVA211	warn	DataSink / PayloadSink (component)	Forbid output_data_type	Metadata has output_data_type	Remove it
SVA220	error	DataOperation (component)	Require both input & output	One or both missing	Add both
SVA221	error	DataOperation (component)	Parameters shape valid	Same validator as SVA103	Fix params
SVA230	error	DataProbe (component)	Require input_data_type	Missing input	Add method/meta
SVA231	warn	DataProbe (component)	Discourage output_data_type	Has output	Remove it (node enforces pass-through)
SVA232	error	DataProbe (component)	Parameters shape valid	Same validator as SVA103	Fix params
SVA240	info	ContextProcessor (component)	No IO req; classmethod rules still apply if present	—	—
SVA250	error	DataOperation / DataProbe / ContextProcessor (component)	_process_logic must not accept ContextType	Parameter named context or annotated as ContextType in _process_logic	Remove ContextType parameter; use node/observer wiring
SVA300	error	DataSourceNode / PayloadSourceNode (node)	Node input is NoDataType	Node metadata input != NoDataType	Set to NoDataType
SVA301	error	DataSourceNode / PayloadSourceNode (node)	Node out == processor out	If processor available, mismatch	Mirror processor
SVA310	error	DataSinkNode / PayloadSinkNode (node)	Node input==output (pass-through)	Mismatch	Make equal
SVA311	error	DataSinkNode / PayloadSinkNode (node)	Node I/O == processor input	If processor available, mismatch	Mirror processor
SVA320	error	Probe Nodes (node)	Node input==output (pass-through)	Mismatch	Make equal
SVA321	error	Probe Nodes (node)	Node I/O == processor input	If processor available, mismatch	Mirror processor

Fixing common SVA errors

• SVA001-SVA003: ensure all *_data_type methods are declared with @classmethod and use cls as the first argument.

• SVA102: keep component docstrings concise (under the configured character limit).

• SVA104-SVA106: injected_context_keys and suppressed_context_keys must be lists of unique strings without overlap.

Probe node contract (mandatory)

• Any pipeline node wrapping a DataProbe must declare a non-empty context_key.

• The probe result is written to that key by the node—components stay context-agnostic.

• Pipelines that omit context_key for probes fail validation via semantiva inspect.

Examples

For concrete examples of probe nodes that satisfy this contract, see:

• The YAML-based probe pipeline in Pipelines - YAML & CLI.

• The corresponding Python-based example in Pipelines in Python (intended for R&D and component development).

These examples illustrate the rules; the authoritative specification remains the SVA catalogue above.

Context argument contract (processors)

• SVA250 enforces that _process_logic implementations for DataOperation, DataProbe, and ContextProcessor must not accept ContextType.

• Context reads and writes are mediated by pipeline nodes and context observers; processors receive only their runtime parameters and (for data processors) the data payload.

CI integration

Use semantiva dev lint in CI pipelines to block merges when contracts are violated. The command exits with code 3 (EXIT_CONFIG_ERROR) when any SVA error diagnostics are present; warnings do not affect the exit code.