Exchanged Data Format

In the following section are described the data formats exchanged between client and server for reconciliation, extension and modification requests. The descriptions is presented in Typescript.

Annotation Metadata

The annotation data is modeled following the W3C standard format for the representation of semantic annotations:

Annotation metadata

interface ColumnMetadata = {
  type?: { id: string; name: string; }[];
  property?: { 
    id: string; 
    name: string; 
    obj: string; 
    score: number; 
    match: boolean;
  }[];
  entity?: EntityMetadata[];
}

interface EntityMetadata = {
  id: string;
  match: boolean;
  name: string;
  score: number;
  type?: { id: string; name: string }[];
  description?: string;
}

Reconciliation

Request

The req object of a requestTransformer contains the original request from the client and optionally the processed request (see External services aggregator):

Request (original)

interface ReconciliationRequestOriginal {
  // items to reconcile
  items: Item[];
}

interface Item {
  // cell id
  id: string;
  // label to reconcile
  label: string;
}

Request (processed)

interface ReconciliationRequestProcessed {
  // items to reconcile as map where
  // the key is the label to reconcile
  // and the array contains the ids of the cells with the same label
  items: Record<string, string[]>;
}

Response

type ReconciliationResponseProcessed = Item[];

interface Item {
  // cell id
  id: string;
  // candidate entity annotations
  metadata?: EntityMetadata[];
}

Extension

Request

The req object of a requestTransformer contains the original request from the client and optionally the processed request (see External services aggregator):

Request (original)

interface ExtensionRequestOriginal {
  // items to extend. columnId: { rowId: metadataId }
  items: Record<string, Item>;
  // any properties that may be required by the service
  [serviceProperty]?: any;
}

type Item = {
  // rowId: metadataId
  [rowId]: string;
}

Request (processed)

interface ExtensionRequestProcessed {
  // items to extend as a map
  // columnId: { metadataId: [row1, row2, ...] }
  items: Record<string, Item>;
}

type Item = {
  // metadataId: [row1, row2,...]
  [metadataId]: string[];
}

Response

interface ExtensionResponseProcessed = {
  // columns to add
  columns: Record<string, Column>;
  // map between extended column and original column ids
  meta: Record<string, string>;
};

interface Column {
  label: string;
  metadata?: ColumnMetadata[];
  kind?: 'entity' | 'literal';
  role?: 'sbj' | 'obj';
  cells: Record<string, Cell>;
}

interface Cell = {
  label: string;
  metadata?: EntityMetadata[];
}

Modification

Request

The req object of a requestTransformer contains the original request from the client and optionally the processed request (see External services aggregator):

Request (original)

interface ModificationRequestOriginal {
  // items to modify: columnId -> { rowId -> [value] }
  items: Record<string, Item>;
  // operation properties, may vary depending on operation type
  props: {
    operationType: string;
    selectedColumns: string[];
    [key: string]: any; // other operation-specific props
  };
}

Request (processed)

interface ModificationRequestProcessed {
  // items after any preprocessing
  items: Record<string, Item>;
  // operation properties, may vary depending on operation type
  props: {
    operationType: string;
    selectedColumns: string[];
    [key: string]: any; // other operation-specific props
  };
}

Response

interface ModificationResponseProcessed {
  // resulting columns after modification
  columns: Record<string, Column>;
  meta: {};
}

info

Unlike Reconciliation and Extension, Modification typically only updates cell values in the selected columns and does not add metadata, while operations such as split or join create additional columns.