API Lineage Tracking
Trace data from REST API endpoints through schemas to model entities. Each endpoint references schemas, and those schemas track lineage to properties in the data model.
API lineage tracking connects REST endpoints to the data model. Every endpoint references schemas for its request and response payloads, and those schemas track lineage to entity properties in model.neoarc. This creates full traceability from API contract to canonical data model.
The Lineage Chain
Lineage flows through three layers:
How It Works
The connection between endpoints and the data model is indirect but fully traceable. Endpoints reference schemas via schemaRef. Each schema field contains lineage entries that map to model entity properties using sourceType: "graph".
{
"sourceType": "graph",
"graphFilePath": "model.neoarc",
"nodeName": "Book",
"nodeId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
"propertyName": "Title"
}Tracing an Endpoint to the Model
To trace data from a REST endpoint to its model source:
Example: Schema Field to Model Property
A Book schema might trace its fields to properties on the Book entity in the model:
| Schema Field | Model Entity | Model Property | Notes |
|---|---|---|---|
| id | Book | BookId | Primary identifier |
| title | Book | Title | Book title |
| author | Book | Author | Author name |
| isbn | Book | ISBN | Unique ISBN identifier |
| publishedYear | Book | PublishedYear | Publication year |
| copiesAvailable | Book | CopiesAvailable | Current inventory count |
Cross-Entity Lineage
Schemas that reference multiple entities create lineage entries across different model nodes. For example, a Loan schema might map its fields to properties on both the Loan entity and related entities:
| Schema Field | Model Entity | Model Property | Notes |
|---|---|---|---|
| id | Loan | LoanId | Primary identifier |
| memberId | Member | MemberId | Reference to the Member entity |
| bookId | Book | BookId | Reference to the Book entity |
| loanDate | Loan | LoanDate | Date the loan was created |
| returnDate | Loan | ReturnDate | Expected or actual return date |
Lineage in Path Parameters
Path parameters such as /books/{bookId} also have lineage. Path parameter schemas extend a generic IdPathParam and override lineage to point to the correct model entity.
| Path Parameter Schema | Model Entity | Model Property |
|---|---|---|
| BookIdPathParam | Book | BookId |
| OrderIdPathParam | Order | OrderId |
| CustomerIdPathParam | Customer | CustomerId |
Visualising the Chain in the Intent Graph
The Intent Graph captures the full lineage chain as edges:
| Edge | From | To | Meaning |
|---|---|---|---|
| depends-on | REST Endpoint | Schema | Endpoint uses this schema for request or response |
| maps-to | Schema Field | Model Property | Field traces to this model entity property |
| derived-from | Schema Field | Schema Field | Inherited field from parent schema |
Querying the Intent Graph reveals the complete dependency chain. Before modifying a model entity property, query to find all schema fields that map to it, then find all endpoints that depend on those schemas.