Schema Lineage Reference

Complete reference for schema lineage tracking, covering the SchemaFieldLineage interface, model-first field mapping, multiple entries, lineage overrides, and Intent Graph integration.

January 23, 2026

Schema lineage maps schema fields to entity properties in the data model (model.neoarc). This reference covers the full lineage interface, all available fields, override behaviour, and how lineage integrates with the Intent Graph.

SchemaFieldLineage Interface

Each lineage entry on a schema field conforms to the following structure:

interface SchemaFieldLineage {
  sourceType: "graph";
  graphFilePath: string;   // Path to the model file, e.g. "model.neoarc"
  nodeName: string;        // Entity name, e.g. "Customer"
  nodeId: string;          // UUID of the entity node
  propertyName: string;    // Property name, e.g. "Email"
  notes?: string;          // Optional transformation notes
}

Field Reference

SchemaFieldLineage fields
Field	Type	Required	Description
sourceType	string	Yes	Set to "graph" for model lineage. This indicates the lineage target is a node property in the model.
graphFilePath	string	Yes	Path to the model file. Typically "model.neoarc". Resolved relative to the workspace root.
nodeName	string	Yes	Display name of the entity in the model (e.g. "Customer", "Order", "Product").
nodeId	string	Yes	UUID of the entity node in the model file. Used for stable references that survive entity renames.
propertyName	string	Yes	Name of the property on the entity (e.g. "Email", "OrderDate", "TotalAmount").
notes	string	No	Free-text notes describing transformations, business rules, or context.

Example Lineage Entry

{
  "sourceType": "graph",
  "graphFilePath": "model.neoarc",
  "nodeName": "Customer",
  "nodeId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "propertyName": "Email"
}

Multiple Lineage Entries

A single schema field can have 0 or more lineage entries. Each entry maps to one model property.

Scenarios requiring multiple lineage entries
Scenario	Example
Concatenation	A FullName schema field maps to both Customer.FirstName and Customer.LastName
Cross-entity references	A schema field sources from properties on different model entities
Foreign key mapping	An orderId field maps to Order.Id in the model
No mapping	Computed or derived fields may have 0 lineage entries

[
  {
    "sourceType": "graph",
    "graphFilePath": "model.neoarc",
    "nodeName": "Customer",
    "nodeId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "propertyName": "FirstName",
    "notes": "Concatenated with LastName, separated by a space"
  },
  {
    "sourceType": "graph",
    "graphFilePath": "model.neoarc",
    "nodeName": "Customer",
    "nodeId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "propertyName": "LastName",
    "notes": "Concatenated with FirstName, separated by a space"
  }
]

Lineage Notes

Each lineage entry supports an optional notes field for documenting transformations or business rules applied to the data.

Transformation documentation examples
Transformation	Example Note
Concatenation	Combined from FirstName and LastName with space separator
Format conversion	Converted from Unix timestamp to ISO 8601
Calculation	Computed as Quantity multiplied by UnitPrice
Enum mapping	Model stores integer code, schema exposes string label
Default value	Defaults to 'active' when model property is null

Lineage Overrides

Lineage overrides allow child schemas to replace inherited lineage with mappings specific to their context.

Inheritance Override Scenario

Object Field Overrides

When a schema uses an Object field that references another schema, you can override lineage for individual fields within that referenced schema. This is useful when the same schema type is reused in different contexts that map to different model entities.

Lineage in the Intent Graph

Each lineage mapping creates a maps-to edge in the Intent Graph:

Edge Component	Description
Source node	Schema Field node, representing the individual field in the schema
Target node	Model Property node, representing the entity property in model.neoarc
Edge type	maps-to
Semantic meaning	The schema field derives its data from this model property

These edges enable querying in both directions:

Query Direction	Question Answered
Forward (schema to model)	Where does this schema field get its data from?
Reverse (model to schema)	Which schema fields depend on this model property?
Transitive (endpoint to model)	Which model properties does this API endpoint ultimately depend on?