xAIF JSON Structure Reference: Fields and Full Example

This page is a complete field-by-field reference for xAIF JSON documents. It covers every key in the top-level envelope, the AIF argument graph object, and each nested array type. A fully worked example drawn from the SNP disagreements dataset is provided at the end.

Top-level fields

`AIF`

Type: object — Required The argument graph. Contains all nodes, directed edges, speaker-to-node mappings, speaker definitions, and optional scheme annotations. See the AIF object fields section below for its sub-keys.

`text`

Type: string or object The original source text. Can be:

A plain string: "text goes here"
An object with a txt key: { "txt": "HTML-annotated text with <span> elements" }

When the object form is used, each text span that corresponds to an argument unit is wrapped in a <span class="highlighted" id="<nodeID>"> element, linking the visible text position back to its L-node in the graph.

`dialog`

Type: boolean Set to true when the document represents a multi-party dialogue (L-nodes are present and attributed to distinct speakers). Set to false for monologue or proposition-only argument structures.

`ova` / `OVA`

Type: object — Optional Visualisation metadata emitted by the OVA (Online Visualisation of Argument) annotation tool. The Python library serialises this key as lowercase ova; data exported directly from the OVA web tool uses uppercase OVA. Both forms are equivalent. Sub-fields:

Sub-field	Type	Description
`firstname`	string	First name of the annotator.
`surname`	string	Surname of the annotator.
`url`	string	URL of the source document in the OVA system.
`nodes`	array	Per-node canvas coordinates and visibility flags (`nodeID`, `visible`, `x`, `y`, `timestamp`).
`edges`	array	Per-edge visibility flags (`fromID`, `toID`, `visible`).

AIF object fields

`nodes`

Type: array of node objects The complete list of graph nodes. See Node object fields.

`edges`

Type: array of edge objects The complete list of directed edges between nodes. See Edge object fields.

`locutions`

Type: array of locution objects Speaker-to-L-node mappings. See Locution object fields.

`participants`

Type: array of participant objects Speaker definitions. See Participant object fields.

`schemefulfillments`

Type: array or null Associates relation nodes (RA, CA, MA, YA, TA) with argument scheme IDs from a scheme ontology. Each entry is { "nodeID": "<id>", "schemeID": "<id>" }. May be null when no scheme annotation has been performed.

`descriptorfulfillments`

Type: array or null Descriptor-level scheme annotations. Each entry maps a node to a descriptor within a fulfillment scheme. May be null or an empty array.

Node object fields

{
  "nodeID": 3,
  "type": "I",
  "text": "disagreements between party members are entirely to be expected.",
  "timestamp": "2077-01-01 12:12:30"
}

Field	Type	Required	Description
`nodeID`	int or string	Yes	Unique identifier within the graph. May be an integer, a numeric string (`"88"`), or an OVA-format string (`"2_164926129380455983"`).
`type`	string	Yes	Node type. One of: `"L"`, `"I"`, `"RA"`, `"CA"`, `"MA"`, `"YA"`, `"TA"`.
`text`	string	Yes	Node content. For L/I nodes: the utterance or proposition text. For relation nodes: the relation label (e.g. `"Default Inference"`, `"Default Conflict"`, `"Default Rephrase"`, `"Default Illocuting"`, `"Default Transition"`).
`timestamp`	string	No	ISO-style datetime string recording when the utterance was made.

Edge object fields

{
  "edgeID": 6,
  "fromID": 3,
  "toID": 9
}

Field	Type	Required	Description
`edgeID`	int or string	Yes	Unique identifier for the edge.
`fromID`	int or string	Yes	`nodeID` of the source node.
`toID`	int or string	Yes	`nodeID` of the target node.

Locution object fields

{
  "nodeID": "1265674",
  "personID": "0",
  "timestamp": "2023-10-11 15:34:32"
}

Field	Type	Required	Description
`nodeID`	int or string	Yes	`nodeID` of the L-node being attributed. Must reference an entry in `AIF.nodes`.
`personID`	int or string	Yes	`participantID` of the speaker. Must reference an entry in `AIF.participants`.
`timestamp`	string	No	Time the utterance was made. Format varies by dataset.

Participant object fields

{
  "participantID": 0,
  "firstname": "Speaker",
  "surname": "1"
}

Field	Type	Required	Description
`participantID`	int or string	Yes	Unique speaker identifier. Referenced by `locutions[].personID`.
`firstname`	string	Yes	First name. Use `""` if unknown.
`surname`	string	Yes	Surname. Use `""` if unknown.

Worked example

The following is the complete xAIF document for a short SNP disagreements exchange. Three speakers make statements about whether disagreements within a party are expected; the graph captures their locutions, the illocutionary links to their propositions, and an inference relation between two of those propositions.

{
  "AIF": {
    "descriptorfulfillments": null,
    "edges": [
      { "edgeID": 0, "fromID": 0, "toID": 4 },
      { "edgeID": 1, "fromID": 4, "toID": 3 },
      { "edgeID": 2, "fromID": 1, "toID": 6 },
      { "edgeID": 3, "fromID": 6, "toID": 5 },
      { "edgeID": 4, "fromID": 2, "toID": 8 },
      { "edgeID": 5, "fromID": 8, "toID": 7 },
      { "edgeID": 6, "fromID": 3, "toID": 9 },
      { "edgeID": 7, "fromID": 9, "toID": 7 }
    ],
    "locutions": [
      { "nodeID": 0, "personID": 0 },
      { "nodeID": 1, "personID": 1 },
      { "nodeID": 2, "personID": 2 }
    ],
    "nodes": [
      {
        "nodeID": 0,
        "text": "disagreements between party members are entirely to be expected.",
        "type": "L"
      },
      {
        "nodeID": 1,
        "text": "the SNP has disagreements.",
        "type": "L"
      },
      {
        "nodeID": 2,
        "text": "it's not uncommon for there to be disagreements between party members.",
        "type": "L"
      },
      {
        "nodeID": 3,
        "text": "disagreements between party members are entirely to be expected.",
        "type": "I"
      },
      {
        "nodeID": 4,
        "text": "Default Illocuting",
        "type": "YA"
      },
      {
        "nodeID": 5,
        "text": "the SNP has disagreements.",
        "type": "I"
      },
      {
        "nodeID": 6,
        "text": "Default Illocuting",
        "type": "YA"
      },
      {
        "nodeID": 7,
        "text": "it's not uncommon for there to be disagreements between party members.",
        "type": "I"
      },
      {
        "nodeID": 8,
        "text": "Default Illocuting",
        "type": "YA"
      },
      {
        "nodeID": 9,
        "text": "Default Inference",
        "type": "RA"
      }
    ],
    "participants": [
      { "participantID": 0, "firstname": "Speaker", "surname": "1" },
      { "participantID": 1, "firstname": "Speaker", "surname": "2" }
    ],
    "schemefulfillments": null
  },
  "dialog": true,
  "ova": [],
  "text": {
    "txt": " Speaker 1 <span class=\"highlighted\" id=\"0\">disagreements between party members are entirely to be expected.</span>.<br><br> Speaker 2 <span class=\"highlighted\" id=\"1\">the SNP has disagreements.</span>.<br><br> Speaker 1 <span class=\"highlighted\" id=\"2\">it's not uncommon for there to be disagreements between party members. </span>.<br><br>"
  }
}

What this graph encodes:

Three L-nodes (IDs 0, 1, 2) hold the raw utterances. Each is attributed to a participant via the locutions array.
Three YA-nodes (IDs 4, 6, 8) connect each L-node to its I-node via L → YA → I paths.
Three I-nodes (IDs 3, 5, 7) hold the processed propositional content.
One RA-node (ID 9) creates the inference path I(3) → RA(9) → I(7), meaning that the proposition in node 3 (“disagreements between party members are entirely to be expected”) is used to support the proposition in node 7 (“it’s not uncommon for there to be disagreements between party members”).

Extension field: `actors`

The actors top-level key is populated by NER and entity-linking modules. It stores character-span mentions of people and organisations within I-nodes, linked to external URIs, alongside a deduplicated list of identified participants.

{
  "actors": {
    "nodes": [
      {
        "nodeID": "1",
        "mentions": [
          { "start": 0, "end": 10, "uri": "http://dbpedia.org/resource/Example_Person" }
        ]
      }
    ],
    "participants": [
      { "personID": "http://dbpedia.org/resource/Example_Person", "uri": "http://dbpedia.org/resource/Example_Person" }
    ]
  }
}

The start and end integers are character offsets into the text field of the referenced I-node (end is exclusive). The uri is a globally unique identifier from a knowledge base such as DBpedia or Wikidata.

Get Started

xAIF Format

Guides

xAIF JSON Structure Reference: Fields and Full Example

Top-level fields

`AIF`

`text`

`dialog`

`ova` / `OVA`

AIF object fields

`nodes`

`edges`

`locutions`

`participants`

`schemefulfillments`

`descriptorfulfillments`

Node object fields

Edge object fields

Locution object fields

Participant object fields

Worked example

Extension field: `actors`

Build docs developers (and LLMs) love

Get Started

xAIF Format

Guides

Documentation Index

​Top-level fields

​AIF

​text

​dialog

​ova / OVA

​AIF object fields

​nodes

​edges

​locutions

​participants

​schemefulfillments

​descriptorfulfillments

​Node object fields

​Edge object fields

​Locution object fields

​Participant object fields

​Worked example

​Extension field: actors

Build docs developers (and LLMs) love

Top-level fields

`AIF`

`text`

`dialog`

`ova` / `OVA`

AIF object fields

`nodes`

`edges`

`locutions`

`participants`

`schemefulfillments`

`descriptorfulfillments`

Node object fields

Edge object fields

Locution object fields

Participant object fields

Worked example

Extension field: `actors`