Annotation Configuration

Creating and managing annotation schemas and configurations

Creating Annotation Configurations

Annotation configurations define the schema for your annotations. Only organization admins can create and manage configurations.

Creating a New Configuration

  1. Navigate to "Annotation Configs" in the sidebar (admin only)
  2. Click "Create Configuration"
  3. Fill in the configuration details:
    • Name: A descriptive name for your configuration (e.g., "NER for Medical Texts")
    • Version: Starting version (default: "1.0.0")
    • Public: Toggle to make the configuration available to other organizations
  4. Click "Create"

After creation, you'll be redirected to the configuration editor where you can define entity types, relation types, and more.

Configuration Visibility

  • Private: Only accessible to your organization
  • Public: Available to all organizations, useful for sharing standard schemas

Entity Types

Entity types define the categories of named entities that can be annotated in documents (e.g., PERSON, ORGANIZATION, LOCATION).

Creating Entity Types

  1. Open your annotation configuration
  2. Navigate to the "Entity Types" section
  3. Click "Add Entity Type"
  4. Fill in the entity type details:
    • Name: Internal identifier (e.g., "PERSON", "ORG") - must be unique
    • Label: Display name (e.g., "Person", "Organization")
    • Color: Color picker for annotation highlights
    • Hotkey: Optional keyboard shortcut (1-9, A-Z)
    • Parent: Optional parent entity type for hierarchical types
    • Abstract: Check if this is an abstract type (cannot be used directly for annotation)
  5. Click "Save"

Hierarchical Entity Types

You can create hierarchical entity type structures:

  • Parent types can be abstract (e.g., "Entity")
  • Child types inherit properties from parents
  • Useful for organizing related entity types (e.g., "Person" and "Organization" under "Named Entity")

Keyboard Shortcuts

Assigning hotkeys to entity types allows annotators to quickly create annotations:

  • Select text in a document
  • Press the hotkey (e.g., "1" for PERSON)
  • The annotation is created immediately

Relation Types

Relation types define relationships between entities (e.g., "works_for", "located_in", "part_of").

Creating Relation Types

  1. Open your annotation configuration
  2. Navigate to the "Relation Types" section
  3. Click "Add Relation Type"
  4. Fill in the relation type details:
    • Name: Internal identifier (e.g., "WORKS_FOR")
    • Label: Display name (e.g., "Works For")
    • Arg1 Type: Entity type for the first argument (source)
    • Arg2 Type: Entity type for the second argument (target)
    • Symmetric: Check if the relation is bidirectional (e.g., "spouse_of")
    • Color: Color for relation arrows
  5. Click "Save"

Argument Constraints

You can constrain which entity types can participate in relations:

  • Arg1 and Arg2 can be set to specific entity types
  • Leave empty to allow any entity type
  • Helps ensure annotation quality and consistency

Symmetric Relations

Symmetric relations are bidirectional (e.g., "colleague_of", "spouse_of"):

  • Only one relation needs to be created (not two)
  • The system handles both directions automatically
  • Visualized with double-headed arrows

Event Types

Event types define complex events with triggers and arguments (e.g., "Acquisition", "Meeting", "Transaction").

Creating Event Types

  1. Open your annotation configuration
  2. Navigate to the "Event Types" section
  3. Click "Add Event Type"
  4. Fill in the event type details:
    • Name: Internal identifier (e.g., "ACQUISITION")
    • Label: Display name (e.g., "Acquisition")
    • Trigger Entity Type: Entity type that triggers the event (e.g., "acquired" verb)
    • Argument Roles: Define roles like "Buyer", "Target", "Date", etc.
    • Required Arguments: Mark which roles are required
  5. Click "Save"

Event Arguments

Event arguments link entities to events in specific roles:

  • Each argument role can have type constraints
  • Arguments can be required or optional
  • Multiple entities can fill the same role (e.g., multiple attendees)

Attribute Types

Attribute types add metadata to entities, relations, or events (e.g., "Negation", "Certainty", "Temporal").

Creating Attribute Types

  1. Open your annotation configuration
  2. Navigate to the "Attribute Types" section
  3. Click "Add Attribute Type"
  4. Fill in the attribute type details:
    • Name: Internal identifier (e.g., "NEGATION")
    • Label: Display name (e.g., "Negation")
    • Value Type: Boolean, Enum, Text, or Number
    • Applicable To: Entity, Relation, Event, or any combination
    • Default Value: Optional default value
    • Enum Values: If value type is Enum, define allowed values
  5. Click "Save"

Value Types

  • Boolean: True/false values (e.g., "Negation: true")
  • Enum: Predefined list of values (e.g., "Certainty: high, medium, low")
  • Text: Free-form text values
  • Number: Numeric values

Cloning Configurations

You can clone existing configurations to create variants without starting from scratch.

How to Clone

  1. Open the configuration you want to clone
  2. Click "Clone" or "Duplicate"
  3. A new configuration is created with:
    • Name automatically set to "original name - Copy" (with the original name substituted)
    • All entity types, relation types, event types, and attribute types copied
    • Parent configuration ID set to link back to the original
  4. You'll be redirected to the new configuration where you can make modifications

Use Cases

  • Creating domain-specific variants (e.g., "Medical NER" from "General NER")
  • Experimenting with schema changes
  • Creating configurations for different annotation projects

Import & Export

You can import configurations from JSON files and export configurations for sharing.

Exporting Configurations

  1. Open the configuration you want to export
  2. Click "Export" or "Download JSON"
  3. A JSON file will be downloaded containing:
    • All entity types, relation types, event types, and attribute types
    • Configuration metadata (name, version)
    • Compatible with BRAT format

Importing Configurations

  1. Navigate to Annotation Configs
  2. Click "Import Configuration"
  3. Upload a JSON file in the supported format
  4. Preview the configuration before importing
  5. Click "Import" to create the configuration

The system validates the JSON structure and maps it to the internal schema. Supported formats include BRAT configuration files.

Configuration Versioning

Annotation configurations are versioned to track schema evolution and maintain compatibility with existing annotations.

Automatic Versioning

When you modify a configuration:

  • A new version snapshot is automatically created
  • The version number increments (e.g., 1.0.0 → 1.1.0)
  • You can optionally provide a description of changes
  • The full configuration state is saved in the snapshot

Viewing Version History

  1. Open the configuration
  2. Navigate to the "Versions" tab
  3. View all versions with:
    • Version string and number
    • Who created the version
    • When it was created
    • Description of changes

Comparing Versions

You can compare different versions side-by-side to see:

  • Added, removed, or modified entity types
  • Changes to relation types, event types, and attribute types
  • Color and label changes

Reverting to Previous Versions

  1. View the version history
  2. Select the version you want to revert to
  3. Click "Revert to This Version"
  4. Confirm the revert

Reverting creates a new version with the restored configuration, preserving the version history.

Annotation Set Compatibility

Annotation sets track which configuration version was used when they were created:

  • This ensures annotations remain valid even if the configuration changes
  • You can see which version each annotation set uses
  • When viewing annotations, the system uses the correct version's schema
PreviousDocument ManagementUp nextCore Annotation Features