Skip to main content

Edges

List schema graph edges: computed relationships between document classes based on shared field overlap and embedding similarity, each with a 0-1 weight.

Edges are computed relationships between schema graph classes that quantify how two document types relate. Talonic computes two edge types: overlaps_with, based on Jaccard similarity over the field registry IDs the two classes share, and similar_to, based on cosine similarity between the classes' schema embeddings. Each edge carries a weight between 0 and 1 indicating relationship strength.

Use edges to understand the shape of your document landscape: which document types share fields (candidates for a shared user schema), and which are semantically close even without direct field overlap. Edges reference classes by UUID via source_schema_id and target_schema_id.

Weak relationships are pruned at computation time: overlaps_with edges are kept when field overlap exceeds 0.1 Jaccard, similar_to edges when embedding cosine similarity exceeds 0.5. Absent edge means below threshold, not zero similarity.
GET/v1/schema-graph/edges

Query parameters

edge_typestringFilter by edge type: overlaps_with or similar_to.

curl

curl -s "https://api.talonic.com/v1/schema-graph/edges?edge_type=overlaps_with" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

dataarrayArray of edge objects.
data[].idstringEdge UUID.
data[].source_schema_idstringUUID of the source schema class.
data[].target_schema_idstringUUID of the target schema class.
data[].edge_typestringRelationship type: overlaps_with (shared fields) or similar_to (embedding similarity).
data[].weightnumberEdge weight between 0 and 1 indicating relationship strength.
data[].computed_atstringISO 8601 timestamp when the edge was computed.

Response

{
  "data": [
    {
      "id": "edge-uuid-1",
      "source_schema_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "edge_type": "overlaps_with",
      "weight": 0.87,
      "computed_at": "2024-09-14T00:00:00.000Z"
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Pair this with GET /v1/schema-graph/classes to build relationship maps between document types. High-weight overlaps_with edges (e.g. weight > 0.7) indicate strong field overlap, useful for identifying document types that should share user schema fields or be linked in cases. Feed the results directly into GET /v1/schema-graph/visualize for a D3-ready graph payload.

Frequently asked questions

How are edge weights computed?+
An `overlaps_with` weight is the Jaccard similarity of the two classes' field registry ID sets: how many canonical fields they share relative to their union. A `similar_to` weight is the cosine similarity of the two classes' schema embeddings.
What is the difference between overlaps_with and similar_to?+
`overlaps_with` measures concrete shared fields between two document types. `similar_to` measures semantic closeness via embeddings, which can be high even when the exact field sets differ. Read both to decide whether two types belong together.
Why is an edge missing between two classes?+
Edges below the computation thresholds are not stored: 0.1 Jaccard for `overlaps_with` and 0.5 cosine for `similar_to`. A missing edge means the relationship was too weak to keep, not that it was never evaluated.

Related

List Classes
Visualize
Field Registry