Schema Lineage

Connect schema fields to model properties in the data model, enabling developers to trace data from API contracts through schemas to model entities.

January 23, 2026

Schema lineage connects schema fields to properties in your data model. Each lineage entry maps a field to a specific entity and property in the model.neoarc file, creating a traceable chain from API contracts through schemas to the underlying data model.

How Schema Lineage Works

Lineage entries use sourceType: "graph" with a reference to the model file. Each entry identifies the target entity and property within the model.

Lineage entry fields
Field	Description	Example
sourceType	Always "graph" for model lineage	graph
graphFilePath	Path to the model file	model.neoarc
nodeName	The entity name in the model	Customer
nodeId	Unique identifier of the model entity	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
propertyName	The property on the entity	Email

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

The Lineage Chain

Lineage creates a three-layer traceability chain across your architecture documentation:

1. API Endpoint

REST or GraphQL operation that references request and response schemas

2. Schema

Data contract with fields, types, validation rules, and lineage entries pointing to model properties

3. Data Model

Entities and properties defined in model.neoarc, representing the canonical data model

Multiple Lineage Entries

A single schema field can map to multiple model properties. This handles real-world data scenarios where a field draws from more than one source.

Scenario	Example
Concatenated fields	A schema FullName field maps to both Customer.FirstName and Customer.LastName in the model
Cross-entity references	A field sources from properties across different model entities
Computed fields	Fields with no model source have 0 lineage entries
Foreign key references	An orderId field maps to the Id property on the Order entity

Adding Lineage in the Schema Editor

The lineage picker displays model entities and their properties, allowing you to select the target directly.

Lineage Indicators

In the Schema Editor, fields with lineage display an [L] indicator, making it straightforward to see which fields have documented model sources and which still need mapping.

Tracing from API to Model

To trace data from an API endpoint to its model source:

Lineage Overrides for Inheritance

When using schema inheritance, derived schemas often need different lineage mappings than the parent. Each derived schema can override the lineage for inherited fields to point to the correct model entity and property.

Aspect	Description
Problem	A Base Entity schema has an Id field with no lineage defined
Solution	Each derived schema overrides the lineage for Id to point to its specific model entity
Example	Customer schema maps Id to Customer.CustomerId in the model; Order schema maps Id to Order.OrderId