Schema Configuration

The Working Context package uses a schema-driven configuration approach to define what contextual data to track and where to find it. This guide explains how to structure your configuration to collect data from multiple sources within io.Connect.

Schema-Driven Configuration

The Working Context operates on a configuration object that defines:

1. Properties to track: Each property has a name and expected data type
2. Source locations: Where to find the data (global context, workspace, channel, etc.)
3. Data paths: The specific path within each source to extract values

This declarative approach allows the package to automatically collect and manage contextual information without requiring manual context subscription management.

Configuration Object Structure

The configuration consists of nested interfaces that define the complete structure of your Working Context schema.

Config Interface

The root configuration object containing the schema definition.

interface Config {
  schema: Schema;
}

Properties:

Property	Type	Required	Description
schema	Schema	Yes	The schema definition containing all tracked properties

Schema Interface

A record of property names mapped to their schema definitions.

interface Schema {
  [key: string]: PropertySchema;
}

Each key in the schema represents a property name that will be tracked and exposed in the Working Context.

PropertySchema Interface

Defines the structure and source of a tracked property.

interface PropertySchema {
  type: "string" | "number" | "boolean" | "object" | "array";
  description?: string;
  source: Source;
}

Properties:

Property	Type	Required	Description
type	"string" | "number" | "boolean" | "object" | "array"	Yes	The expected data type for this property
description	string	No	Human-readable description of the property's purpose
source	Source	Yes	Defines where to retrieve the property value

Source Interface

Specifies the context source for a property.

interface Source {
  context: {
    location: SourceLocation;
    path: string;
  };
}

Properties:

Property	Type	Required	Description
location	SourceLocation	Yes	The source location to retrieve data from
path	string	Yes	Dot notation path to the data within the source

SourceLocation Interface

Defines the specific context source to track. Each property must specify exactly one source location.

interface SourceLocation {
  global?: { names: string[] };
  workspace?: { target: "my" | "focused" | "hybrid" };
  appInstance?: { appNames: string[] };
  channel?: { target: "my" | string };
}

Properties:

Property	Type	Description
global	{ names: string[] }	Track data from global io.Connect contexts
workspace	{ target: "my" | "focused" | "hybrid" }	Track data from workspace contexts
appInstance	{ appNames: string[] }	Track data from specific application instances
channel	{ target: "my" | string }	Track data from channel contexts

Context Sources

The Working Context package supports four types of context sources, each serving different use cases for tracking contextual data.

Global Context

Global io.Connect shared contexts are accessible across the entire io.Connect environment. Use this source for data that should be available to all applications.

global: {
  names: string[]  // Array of global context names to monitor
}

Example:

userName: {
  type: "string",
  description: "User's display name",
  source: {
    context: {
      location: {
        global: { names: ["UserSession", "UserProfile"] }
      },
      path: "name"
    }
  }
}

The package monitors all specified context names and retrieves the value from the first context where the path exists.

Workspace Context

Track data specific to workspaces. The workspace source supports three targeting modes:

workspace: {
  target: "my" | "focused" | "hybrid"
}

Target Options:

• "my": Track the user's own workspace
• "focused": Track the currently focused workspace
• "hybrid": Combine data from both workspaces

Note: The "focused" and "hybrid" targets are currently supported only in io.Connect Desktop.

Example:

activeDocument: {
  type: "object",
  description: "Currently open document",
  source: {
    context: {
      location: {
        workspace: { target: "my" }
      },
      path: "document.current"
    }
  }
}

Channel Context

Track data from specific channels. Channels enable applications to share data within a named channel.

channel: {
  target: "my" | string  // "my" for user's current channel or specific channel name
}

Target Options:

• "my": Track the user's current channel
• string: Track a specific channel by name (e.g., "MarketData")

Example:

marketData: {
  type: "object",
  description: "Real-time market data from channel",
  source: {
    context: {
      location: {
        channel: { target: "MarketData" }
      },
      path: "data"
    }
  }
}

Application Instance Context

Track context from specific application instances. This source monitors data exposed by particular applications.

appInstance: {
  appNames: string[]  // Array of application names to monitor
}

Example:

portfolioData: {
  type: "array",
  description: "User's portfolio holdings",
  source: {
    context: {
      location: {
        appInstance: { appNames: ["PortfolioManager"] }
      },
      path: "portfolio.holdings"
    }
  }
}

The package monitors all specified application names and retrieves the value from the first application instance where the path exists.

Property Types

The Working Context package supports five data types for tracked properties. Each property must declare its expected type for proper validation.

Supported Types

• "string": Text values
• "number": Numeric values (integers and floating-point)
• "boolean": True or false values
• "object": Complex objects (non-array)
• "array": Array values of any type

Type Validation

The package validates retrieved values against the declared type. If a value does not match the expected type:

• A warning is logged to the console
• The value is ignored
• The property remains undefined or retains its previous value

Configuration Rules

When creating your schema configuration, follow these rules to ensure proper behavior:

Single Source Location

Each property must define exactly one source location. You cannot combine multiple source types for a single property.

Valid:

userName: {
  type: "string",
  source: {
    context: {
      location: {
        global: { names: ["UserSession"] }
      },
      path: "user.name"
    }
  }
}

Invalid:

userName: {
  type: "string",
  source: {
    context: {
      location: {
        global: { names: ["UserSession"] },
        workspace: { target: "my" }  // Cannot specify multiple locations
      },
      path: "user.name"
    }
  }
}

Dot Notation Paths

Use dot notation to access nested properties within context data. The package traverses the object structure using the specified path.

Examples:

// Top-level property
path: "username"

// Nested property
path: "user.profile.email"

// Deeply nested property
path: "organization.division.department.name"

Type Validation Behavior

Always declare the correct type for your properties. Type mismatches result in lost data and console warnings, but do not throw errors.

Example:

// If context contains { count: "42" } (string instead of number)
userCount: {
  type: "number",  // Expected type
  source: {
    context: {
      location: { global: { names: ["Stats"] } },
      path: "count"
    }
  }
}
// Result: Property remains undefined, warning logged

Complete Configuration Example

This example demonstrates a comprehensive configuration using all four source types:

const config = {
  schema: {
    // Track user name from global context
    userName: {
      type: "string",
      description: "User's display name",
      source: {
        context: {
          location: {
            global: { names: ["UserSession", "UserProfile"] }
          },
          path: "name"
        }
      }
    },

    // Track user role from global context
    userRole: {
      type: "string",
      description: "User's role in the organization",
      source: {
        context: {
          location: {
            global: { names: ["UserSession"] }
          },
          path: "user.role"
        }
      }
    },

    // Track active document from workspace
    activeDocument: {
      type: "object",
      description: "Currently open document in workspace",
      source: {
        context: {
          location: {
            workspace: { target: "my" }
          },
          path: "document.current"
        }
      }
    },

    // Track notification settings from channel
    notificationsEnabled: {
      type: "boolean",
      description: "Whether notifications are enabled",
      source: {
        context: {
          location: {
            channel: { target: "my" }
          },
          path: "settings.notifications.enabled"
        }
      }
    },

    // Track real-time market data from specific channel
    marketData: {
      type: "object",
      description: "Real-time market data",
      source: {
        context: {
          location: {
            channel: { target: "MarketData" }
          },
          path: "data"
        }
      }
    },

    // Track portfolio data from app instance
    portfolioData: {
      type: "array",
      description: "User's portfolio holdings",
      source: {
        context: {
          location: {
            appInstance: { appNames: ["PortfolioManager"] }
          },
          path: "portfolio.holdings"
        }
      }
    },

    // Track budget information with deeply nested path
    budgetRemaining: {
      type: "number",
      description: "Remaining budget for current fiscal year",
      source: {
        context: {
          location: {
            global: { names: ["FinanceData"] }
          },
          path: "department.finance.budget.fiscal2024.remaining"
        }
      }
    }
  }
};

This configuration creates a Working Context that tracks seven properties from different sources, demonstrating the flexibility and power of the schema-driven approach.