Objects and references

If Payments API appears in several diagrams, copying its box gives you several names to maintain. Create an object for it and put a reference in each document instead.

Objects hold the shared details

An object has a name and a kind, such as a service or a datastore. Its kind can provide document slots. For example, a service can have documents attached to it instead of leaving those documents in an unrelated list.

A reference points to the object's ID. Renaming the object changes the name shown by its references. A label on an ordinary shape has no such connection.

Reference an object in YAML

This example is a node inside a document's nodes list. Replace YOUR_OBJECT_ID with an existing object's ID:

- id: payments
  type: reference
  referenceType: object
  targetId: YOUR_OBJECT_ID
  label: Payments API

You can connect reference nodes with relationships, just as you connect other nodes. Those relationships feed the dependency graph. A reference says which object a document uses; an arrow between references records how the objects relate.

Use the object's Used in view to find documents that reference it before changing the service. A dependency the team hasn't documented won't appear in that view or in the graph.

Find objects through an agent

An MCP client can call list_objects and get_object to find the existing object. Ask it to reuse that ID before it creates anything. list_object_docs finds the object's documents, including documents owned by the object that don't appear in the general document search.