Skip to content

Relation extraction output

The API resource performing relation extraction returns a JSON object with this format:

{
    "success": Boolean success flag,
    "data": {
        "content": analyzed text,
        "language": language code,
        "version": technology version info,
        "paragraphs": [],
        "sentences": [],
        "phrases": [],
        "tokens": [],
        "knowledge": [],
        "relations": []
    }
}

Tip

Use the live demo to see how API responses look like. Run an analysis, select Relations on the left menu then select the {...} json tab.

For the description of the contents, language and version properties, see the API resources output overview.

The paragraphs, sentences, phrases and tokens arrays are produced by the text subdivision process. These sections are described in the article about the output of the deep linguistic analysis.

The knowledge array contains Knowledge Graph data about the relations elements, as a result of the semantic analysis process. Its contents are described in the article about the output of full analysis.

relations

Each item of the relations array represents a verb plus the text elements that are in a semantic relation with it. These elements may specify arguments, adjuncts or subordinate clauses. For example, given this input text:

John sent a letter to Mary.

the relations array can contain an item like this:

{
    "verb": {
        "text": "sent",
        "lemma": "send",
        "syncon": 68296,
        "phrase": 1,
        "type": "",
        "relevance": 15
    },
    "related": [
        {
            "relation": "sbj_who",
            "text": "John",
            "lemma": "John",
            "syncon": -1,
            "type": "NPH",
            "phrase": 0,
            "relevance": 15
        },
        {
            "relation": "obj_what",
            "text": "a letter",
            "lemma": "letter",
            "syncon": 29131,
            "type": "wrk",
            "phrase": 2,
            "relevance": 10
        },
        {
            "relation": "to_who",
            "text": "to Mary",
            "lemma": "Mary",
            "syncon": -1,
            "type": "NPH",
            "phrase": 3,
            "relevance": 10
        }
    ]
}

Common properties

The verb object and the items of the related array share some properties.

text if the portion of text corresponding to the element.

phrase is the index of the phrase containing the element. The value must be interpreted as a pointer to an item of the phrases array, where the positions of the first and the last character of the phrase can be found. This information can be used for text highlighting.
From the phrase it is possible to go back to the sentence it belongs to—using the sentences array—and from the sentence to the paragraph—using the paragraphs array—,or, going in the opposite direction, to find the tokens contained in the phrase —using the tokens array.
Subordinate clauses—related items having the relation property set to sub—do not have a one-to-one correspondence with a phrase. In that case, phrase has the conventional value -1.

The syncon and lemma properties are the outcome of semantic analysis and lemmatization respectively. These are exactly the same processes carried out during deep linguistic analysis. Value -1 for syncon means the concept doesn't have a correspondent in the expert.ai Knowledge Graph. This can happen with:

  1. entities having a proper noun that are recognized through heuristics (e.g. John Smith)
  2. parts-of-speech that ar not mapped in the Knowledge Graph like pronouns (e.g., them)
  3. subordinate clauses like quotes (e.g., John said: "I will do it!")

In cases 1 and 2 lemma is an empty string.

relevance is an indicator of the importance of the element in text. Its values ranges from 1 to 15. When element importance cannot be determined, relevance has the conventional value -1.

verb

The verb object is always present and it represents the verb.

type is the verb type. When set, it can be one of the following:

Verb type Description
CPL to be used as a connection as in John is a smart guy
MOV Verb of movement like to go
SAY Verb of communication like to say

The items of the related array represent text elements that are related to the verb.

relation is the type of relation and can be one of the following:

Possible values of relation
sbj_who
sbj_what
obj_who
obj_what
is_who
is_what
to_who
to_what
using_what
preposition* + _what
preposition* + _who
sub**
when
where
to_where
from_where
in_where
which_way
how
of_age
limited_to

* Prepositions are expressed in the language specified for the analysis, so, for example, a possible value in the case of German language could be auf_what. Multi-word prepositional expressions like according to, in front of, ecc., are written in compact form (accordingto, infrontof).

** The sub relation type is used for subordinate clauses.

type identifies the kind of element. Possible values can be uppercase or lowercase. Uppercase corresponds to named entities, lowercase to generic entities.

Relations can be recursive: a related item can be related to another item and so on. In this case an item of the related array can contain a related array.
For example, given this input text:

Mireille placed the plant pot on the landing at the top of the stairs.

relations can be like this:

"relations": [
    {
        "related": [
            {
                "lemma": "Mireille",
                "phrase": 0,
                "relation": "sbj_who",
                "relevance": 14,
                "syncon": -1,
                "text": "Mireille",
                "type": "NPH"
            },
            {
                "lemma": "pot",
                "phrase": 2,
                "relation": "obj_what",
                "relevance": 15,
                "syncon": 18506,
                "text": "the plant pot",
                "type": "prd"
            },
            {
                "lemma": "landing",
                "phrase": 3,
                "relation": "on_what",
                "relevance": 5,
                "syncon": 16859,
                "text": "on the landing",
                "type": "bld"
            },
            {
                "lemma": "top",
                "phrase": 4,
                "related": [
                    {
                        "lemma": "stairs",
                        "phrase": 5,
                        "relation": "of_what",
                        "relevance": 1,
                        "syncon": 20016,
                        "text": "of the stairs",
                        "type": "bld"
                    }
                ],
                "relation": "at_what",
                "relevance": -1,
                "syncon": 37732,
                "text": "at the top",
                "type": ""
            }
        ],
        "verb": {
            "lemma": "place",
            "phrase": 1,
            "relevance": 15,
            "syncon": 68498,
            "text": "placed",
            "type": ""
        }
    }
]

knowledge

The knowledge array contains Knowledge Graph data for the items of the relations array. Its contents are described in the article about the output of full analysis.