Record schema

The Record is obslog's central data contract. The canonical, machine-readable schema is published at schemas/obslog.record.schema.json; the diagnostic bundle schema is at schemas/obslog.bundle.schema.json. This page is the human-readable companion.

Fields split into reserved (a frozen, well-known set — the semantic conventions) and the open metadata namespace owned by the application. The SDK carries but never interprets application data (PRIN-002, SCHEMA-002).

Field	Type	Notes
schema_version	string	Record schema version (independent of the package version).
timestamp	string	UTC, ISO-8601.
timestamp_monotonic_ns	int	Monotonic reading for ordering/duration.
event	string	Stable dotted name (e.g. order.completed).
message	string	Optional human text; never a join key.
level / severity_number / severity_text	string / int / string	OpenTelemetry-aligned.
component / module / function	string	Subsystem / module / function.
caller	object	{file, line, function?} — opt-in (stack inspection cost).
execution_id / request_id / trace_id / span_id / parent_execution	string	Correlation.
operation / phase	string	From operation() or explicit.
duration_ns	int	Operation duration.
error	object	{type, message, stack?, code?}.
error_code	string	Stable, namespaced identifier (AI join key).
tags	array	Flat labels.
metadata	object	Arbitrary app-defined data (the open namespace).
hint	object	App-supplied diagnostic hint, carried verbatim.
resource	object	service.name, service.version, deployment.environment, host.name, process.pid.

Severity mapping

Level	severity_number
TRACE	1
DEBUG	5
INFO	9
WARNING	13
ERROR	17
CRITICAL	21

Evolution rules

• Within schema major version 1, only additive changes (new optional fields) are permitted (SCHEMA-008).
• Removing, renaming, or retyping a reserved field requires a schema major bump and an ADR.
• Serialization is deterministic (sorted keys) for identical inputs (SCHEMA-005).