Chart schema and identifiers

The i2 Notebook SDK exposes schema information through the chart.schema property. The chart schema acts as a structural blueprint for the data currently present in a specific chart. It describes the available item types (entity types and link types), the properties those records can contain, visual characteristics (such as icons and labels), and the constraints that dictate how records relate to each other.

Additionally, the schema defines the rules for other record features, including notes, source identifiers, source references, and the security dimensions that govern access control.

This guide explains why the chart schema is important and how to use it alongside identifiers when interacting with chart data.

Why do you need the schema?

You typically use the schema to:

  • Discover which entity and link types are available on the current chart.
  • Resolve item types and property types before reading or writing property values.
  • Choose the appropriate identifier for lookups, cached state, and mutations.

Imagine writing a plug-in that imports data from an external source and places it on the chart. To do this, you cannot simply drop raw JSON onto the chart; you must translate your external data into a format the chart understands.

The schema provides the answers to critical questions:

  • What entity types are available to represent a "Person"?
  • What properties are valid for that "Person" entity?
  • Can a "Vehicle" link directly to a "Location"?

By validating your operations against the schema, you ensure that the chart remains consistent and functions correctly.

Link constraints

Link types define which entity types are valid at each end of the link. The schema exposes those rules through fromEntityTypes and toEntityTypes, but the SDK does not prevent you from constructing links that fall outside them. Ignoring these rules may cause errors if those links are then passed to stores that strictly validate link constraints, so verify the constraints before creating links.

Accessing the chart schema

You can access the active chart's schema through the chart.schema property. This property is available on the root api object in your plug-in's entry point (as well as the tool view), and on the applicationContents object passed to command and mutation handlers.

Here is an example that retrieves a specific entity type by its analyzeId and lists the available properties for records of that type:

// Look up a known entity type by its i2 Analyze identifier
const personType = api.chart.schema.entityTypes.get('ET5');

if (personType) {
  // List the property types that a "Person" entity can have
  for (const propertyType of personType.propertyTypes) {
    console.log(`${propertyType.displayName} (${propertyType.logicalType})`);
  }
}

Looking up types and properties

When your plug-in needs to interact with specific data, you will often look up individual entity, link, and property types from the schema.

The SDK collections (schema.entityTypes, schema.linkTypes, schema.itemTypes, and an item type's propertyTypes) are IKeyedReadOnlyCollection objects. These collections allow you to look up a type using any of three distinct keys:

  1. analyzeId: The unique identifier assigned by the i2 Analyze server (e.g., 'ET1'). Use this when your plug-in relies on a known server data model.
  2. displayName: The display name of the type (e.g., 'Address'). Note that display names are not guaranteed to be unique: you can create custom types that share the same display name.
  3. id: The internal, chart-specific integer identifier (e.g., 558). You will usually encounter these when reading from existing records directly on the chart, or when reading payloads such as removed type identifiers in schema change events.

Because the collection routes all three keys to the exact same value, here are three completely equivalent ways to retrieve the "Address" entity type from the schema:

const schema = api.chart.schema;
const addressByAnalyzeId = schema.entityTypes.get('ET1');
const addressByDisplayName = schema.entityTypes.get('Address');
const addressByChartId = schema.entityTypes.get(558);

The schema also provides direct helper methods. Methods like getItemType() and getPropertyType() expect an AnalyzeItemTypeId and make it clear that your plug-in expects a matching type to exist:

const addressType = schema.getItemType('ET1');
const locationProperty = addressType.getPropertyType('PT1');

Responding to schema changes

Listen for the chartschemachange event when your plug-in needs to react to schema updates.

This event fires whenever the schema definition changes. These changes might be triggered by your plug-in, by other plug-ins, or by the user modifying the schema.

For example, a plug-in can trigger schema changes when it performs operations such as:

Here is an example of an event handler that listens for schema changes and logs the added, changed, and removed types:

api.addEventListener('chartschemachange', (change, application) => {
  const addedTypes = change.addedTypes.toArray();
  const changedTypes = change.changedTypes.toArray();
  const removedTypeIds = change.removedTypes.toArray();

  console.log({ addedTypes, changedTypes, removedTypeIds });

  // After the event, treat application.chart.schema as the source of truth.
  const currentSchema = application.chart.schema;
  console.log(currentSchema.itemTypes.size);
});

Other parts of the schema

The schema also describes other chart features, not just entity and link types. You will use these parts of the schema when you need to validate or populate richer record data: