Data Model¶

Jayrun separates reusable declarations from graph-local descriptions and runtime values. This separation is the key to understanding artifacts, configuration, resources, operators, and graphs without treating them as one object.

The same concept normally passes through these layers:

Declaration
    A reusable Artifact, ConfigField, ResourceField, or BaseResource
        ↓ bound to an operator or registered in a graph
Graph-local definition
    An immutable description with a graph-local integer ID
        ↓ resolved for one submission or runtime load
Runtime data
    Data(value, placement)

No single page can remove every relationship between these layers. Instead, each data-model page describes the object itself and links to the component that gives it its wider meaning:

Layer	Objects	What can be understood independently	Where the relationship is completed
Runtime value	`jayrun.Data`	Payload and placement metadata	Artifact values, resolved configuration, and loaded resources
Artifact declaration	`jayrun.Artifact`	Identity of flowing data	operator ports and artifact flows
Configuration declaration	`jayrun.ConfigField`	Typed, context-scoped input	Its operator or resource owner and the confirmed graph
Resource declaration	`jayrun.BaseResource`, `jayrun.ResourceField`	Setup, teardown, and dependency requirements	resource binding and runtime acquisition
Graph definition	`jayrun.core.graph.definition.ArtifactDefinition`, `jayrun.core.graph.definition.ConfigDefinition`, `jayrun.core.graph.definition.ResourceDefinition`	Immutable graph-local identity and metadata	Graph inspection

Declarations¶

Declarations are the objects application code creates and connects:

an jayrun.Artifact identifies data that can flow through operators;
an jayrun.ArtifactField declares an operator artifact port;
a jayrun.ConfigField declares a typed configuration requirement;
a jayrun.ResourceField declares an operator resource dependency; and
a jayrun.BaseResource declares how runtime-managed data is loaded and torn down.

Declarations are reusable Python objects. Their names are descriptive labels, not graph-wide identifiers.

Bindings¶

A binding gives a declaration a relationship:

constructing an operator binds artifacts or None to its artifact fields;
constructing a graph registers artifacts and every field owned by its operators;
binding resources associates graph resource fields with resource declarations.

An jayrun.ArtifactField, jayrun.ConfigField, or jayrun.ResourceField belongs to its operator or resource declaration. It is not a standalone graph value. See Operators and Executions for field ownership and runtime injection.

Graph-local definitions and IDs¶

When Jayrun registers a declaration in a graph, it creates an immutable definition:

Source declaration	Graph-local definition	ID attribute
`jayrun.Artifact`	`jayrun.core.graph.definition.ArtifactDefinition`	`artifact_id`
`jayrun.ConfigField`	`jayrun.core.graph.definition.ConfigDefinition`	`config_id`
`jayrun.ResourceField`	`jayrun.core.graph.definition.ResourceDefinition`	`resource_id`

A definition is a graph-owned description of its source declaration. It does not replace the declaration, carry runtime data, or have global identity. Its integer ID is meaningful only within the graph that created it.

Definitions make graph inspection stable and serializable. They record names, ownership, layout position, required status, and type-specific metadata without exposing mutable framework internals. See Graph inspection for the inspection collections that return them.

Choosing a reference form¶

Some graph-bound APIs accept a source declaration or field, its definition, or its integer ID. All three resolve to the same registered object:

definition = graph.inspect.artifacts.entry[0]

artifacts.set({input_artifact: value})
artifacts.set({definition: value})
artifacts.set({definition.artifact_id: value})

Choose the form that matches the caller:

use declarations and fields in ordinary Python application code;
use definitions while working with graph inspection results;
use integer IDs in serialized documents, generated forms, or external tools.

Definitions and IDs are graph-local. A foreign definition or unknown ID is rejected. Supplying two aliases for the same declaration in one mapping is also rejected because the intended value would be ambiguous.

Important

An operator field is not interchangeable with every other declaration. jayrun.ArtifactContext.set() accepts an Artifact, not an operator’s ArtifactField; jayrun.ConfigContext.set() accepts a ConfigField; and jayrun.GraphDefinition.bind_resources() accepts a ResourceField.

Runtime `Data`¶

jayrun.Data is the common runtime container. It pairs a payload with placement metadata and is used for artifact values, resolved configuration, and loaded resources.

Data does not identify what the value means in the graph. That meaning still comes from the artifact, config field, or resource field through which the container is accessed. See Data for its complete contract.

Reading order¶

Read the remaining data-model pages in this order:

Data for the common runtime container.
Artifacts and Data Flow for flowing graph data.
Configuration for context-scoped values.
Resources for runtime-managed shared data.

Then read Operators and Executions and Graph Construction. The separate Graph Validation chapter explains artifact-property compatibility in depth.