TranslatorReasonerAPI.yaml

openapi: 3.0.1
info:
  description: INSERT-DESCRIPTION-OF-YOUR-SERVICE-HERE
  version: INSERT-VERSION-OF-YOUR-SERVICE-HERE
  title: INSERT-TITLE-OF-YOUR-SERVICE-HERE
  contact:
    email: INSERT@EMAIL-ADDRESS-OF-IMPLEMENTER-HERE.ORG
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: INSERT-URL-HERE
  x-translator:
    component: INSERT-EITHER-ARA-OR-KP-OR-ARS-OR-Utility-HERE
    team:
      - INSERT-ONE-TRANSLATOR-TEAM-NAME-PER-ELEMENT-HERE
    biolink-version: INSERT-BIOLINK-MODEL-VERSION-HERE
    externalDocs:
      description: >-
        The values for component and team are restricted according to this
        external JSON schema. See schema and examples at url
      url: https://github.com/NCATSTranslator/translator_extensions/blob/\
        production/x-translator/
  x-trapi:
    version: 1.1.2
    externalDocs:
      description: >-
        The values for version are restricted according to the regex in
        this external JSON schema. See schema and examples at url
      url: https://github.com/NCATSTranslator/translator_extensions/blob/\
        production/x-trapi/
servers:
  - url: INSERT-URL-HERE
    description: INSERT-SERVER-DESCRIPTION-HERE
externalDocs:
  description: >-
    Documentation for the NCATS Biomedical Translator Reasoners web services
  url: https://github.com/NCATSTranslator/ReasonerAPI
tags:
  - name: predicates
    description: Get supported relationships by source and target
    externalDocs:
      description: Documentation for the reasoner predicates function
      url: INSERT-URL-HERE-OR-REMOVE-EXTERNALDOCS-IF-NA
  - name: query
    description: Query reasoner using a predefined question type
    externalDocs:
      description: Documentation for the reasoner query function
      url: INSERT-URL-HERE-OR-REMOVE-EXTERNALDOCS-IF-NA
  - name: translator
    description: Required for SmartAPI validation of x-translator
  - name: trapi
    description: Required for SmartAPI validation of x-trapi
paths:
  /predicates:
    get:
      deprecated: true
      tags:
        - predicates
      summary: Get supported relationships by source and target
      responses:
        '200':
          description: Predicates by source and target
          content:
            application/json:
              schema:
                description: Source map
                type: object
                additionalProperties:
                  description: Target map
                  type: object
                  additionalProperties:
                    description: Array of predicates
                    type: array
                    items:
                      type: string
                example:
                  'biolink:ChemicalSubstance':
                    'biolink:Gene':
                      - biolink:directly_interacts_with
                      - biolink:decreases_activity_of
  /meta_knowledge_graph:
    get:
      tags:
        - meta_knowledge_graph
      summary: Meta knowledge graph representation of this TRAPI web service.
      responses:
        '200':
          description: >-
            Returns meta knowledge graph representation of this TRAPI web
            service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaKnowledgeGraph'
  /query:
    post:
      tags:
        - query
      summary: Query reasoner via one of several inputs
      description: ''
      requestBody:
        description: Query information to be submitted
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: >-
            OK. There may or may not be results. Note that some of the provided
            identifiers may not have been recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: >-
            Bad request. The request is invalid according to this OpenAPI
            schema OR a specific identifier is believed to be invalid somehow
            (not just unrecognized).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: >-
            Internal server error.
          content:
            application/json:
              schema:
                type: string
        '501':
          description: >-
            Not implemented.
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    Query:
      description: >-
        The Query class is used to package a user request for information. A
        Query object consists of a required Message object with optional
        additional properties. Additional properties are intended to convey
        implementation-specific or query-independent parameters. For example,
        an additional property specifying a log level could allow a user to
        override the default log level in order to receive more fine-grained
        log information when debugging an issue.
      x-body-name: request_body
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
          description: >-
            The query Message is a serialization of the user request. Content
            of the Message object depends on the intended TRAPI operation. For
            example, the fill operation requires a non-empty query_graph field
            as part of the Message, whereas other operations, e.g. overlay,
            require non-empty results and knowledge_graph fields.
        log_level:
          description: The least critical level of logs to return
          allOf:
            - $ref: '#/components/schemas/LogLevel'
          nullable: true
      additionalProperties: true
      required:
        - message
    Response:
      type: object
      description: >-
        The Response object contains the main payload when a TRAPI query
        endpoint interprets and responds to the submitted query successfully
        (i.e., HTTP Status Code 200). The message property contains the
        knowledge of the response (query graph, knowledge graph, and results).
        The status, description, and logs properties provide additional details
        about the response.
      properties:
        message:
          description: >-
            Contains the knowledge of the response (query graph, knowledge
            graph, and results).
          $ref: '#/components/schemas/Message'
        status:
          description: >-
            One of a standardized set of short codes,
            e.g. Success, QueryNotTraversable, KPsNotAvailable
          type: string
          example: Success
          nullable: true
        description:
          description: A brief human-readable description of the outcome
          type: string
          example: Success. 42 results found.
          nullable: true
        logs:
          description: >-
            Log entries containing errors, warnings, debugging information, etc
          type: array
          items:
            $ref: '#/components/schemas/LogEntry'
          nullable: true
      additionalProperties: true
      required:
        - message
    Message:
      description: >-
        The message object holds the main content of a Query or a Response in
        three properties: query_graph, results, and knowledge_graph.
        The query_graph property contains the query configuration, the results
        property contains any answers that are returned by the service,
        and knowledge_graph property contains lists of edges and nodes in the
        thought graph corresponding to this message. The content of these
        properties is context-dependent to the encompassing object and
        the TRAPI operation requested.
      type: object
      properties:
        results:
          description: >-
            List of all returned Result objects for the query posed.
            The list SHOULD NOT be assumed to be ordered. The 'score' property,
             if present, MAY be used to infer result rankings.
          type: array
          items:
            $ref: '#/components/schemas/Result'
          nullable: true
        query_graph:
          description: >-
            QueryGraph object that contains a serialization of a query in the
            form of a graph
          allOf:
            - $ref: '#/components/schemas/QueryGraph'
          nullable: true
        knowledge_graph:
          description: >-
            KnowledgeGraph object that contains lists of nodes and edges
            in the thought graph corresponding to the message
          allOf:
            - $ref: '#/components/schemas/KnowledgeGraph'
          nullable: true
      additionalProperties: false
    LogEntry:
      description: >-
        The LogEntry object contains information useful for tracing
        and debugging across Translator components.  Although an
        individual component (for example, an ARA or KP) may have its
        own logging and debugging infrastructure, this internal
        information is not, in general, available to other components.
        In addition to a timestamp and logging level, LogEntry
        includes a string intended to be read by a human, along with
        one of a standardized set of codes describing the condition of
        the component sending the message.
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp in ISO 8601 format
          example: '2020-09-03T18:13:49+00:00'
          nullable: true
        level:
          allOf:
            - $ref: '#/components/schemas/LogLevel'
          nullable: true
        code:
          type: string
          description: >-
            One of a standardized set of short codes
            e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed
          nullable: true
        message:
          type: string
          description: A human-readable log message
          nullable: true
      additionalProperties: true
    LogLevel:
      type: string
      description: Logging level
      enum:
        - ERROR
        - WARNING
        - INFO
        - DEBUG
    Result:
      type: object
      description: >-
        A Result object specifies the nodes and edges in the knowledge graph
        that satisfy the structure or conditions of a user-submitted query
        graph. It must contain a NodeBindings object (list of query graph node
        to knowledge graph node mappings) and an EdgeBindings object (list of
        query graph edge to knowledge graph edge mappings).
      properties:
        node_bindings:
          type: object
          description: >-
            The dictionary of Input Query Graph to Result Knowledge Graph node
            bindings where the dictionary keys are the key identifiers of the
            Query Graph nodes and the associated values of those keys are
            instances of NodeBinding schema type (see below). This value is an
            array of NodeBindings since a given query node may have multiple
            knowledge graph Node bindings in the result.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/NodeBinding'
        edge_bindings:
          type: object
          description: >-
            The dictionary of Input Query Graph to Result Knowledge Graph edge
            bindings where the dictionary keys are the key identifiers of the
            Query Graph edges and the associated values of those keys are
            instances of EdgeBinding schema type (see below). This value is an
            array of EdgeBindings since a given query edge may resolve to
            multiple knowledge graph edges in the result.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EdgeBinding'
        score:
          type: number
          format: float
          example: 163.233
          description: >-
            A numerical score associated with this result indicating the
            relevance or confidence of this result relative to others in the
            returned set. Higher MUST be better.
      additionalProperties: true
      required:
        - node_bindings
        - edge_bindings
    NodeBinding:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CURIE'
          description: >-
            An instance of NodeBinding is a single KnowledgeGraph Node mapping,
            identified by the corresponding 'id' object key identifier of the
            Node within the Knowledge Graph. Instances of NodeBinding may
            include extra annotation (such annotation is not yet fully
            standardized).
      additionalProperties: true
      required:
        - id
    EdgeBinding:
      type: object
      description: >-
        A instance of EdgeBinding is a single KnowledgeGraph Edge mapping,
        identified by the corresponding 'id' object key identifier of the
        Edge within the Knowledge Graph. Instances of EdgeBinding may include
        extra annotation (such annotation is not yet fully standardized).
      properties:
        id:
          type: string
          description: The key identifier of a specific KnowledgeGraph Edge.
      additionalProperties: true
      required:
        - id
    KnowledgeGraph:
      type: object
      description: >-
        The knowledge graph associated with a set of results. The instances
        of Node and Edge defining this graph represent instances of
        biolink:NamedThing (concept nodes) and biolink:Association
        (relationship edges) representing (Attribute) annotated knowledge
        returned from the knowledge sources and inference agents wrapped by
        the given TRAPI implementation.
      properties:
        nodes:
          type: object
          description: >-
            Dictionary of Node instances used in the KnowledgeGraph,
            referenced elsewhere in the TRAPI output by the dictionary key.
          additionalProperties:
            $ref: '#/components/schemas/Node'
        edges:
          type: object
          description: >-
            Dictionary of Edge instances used in the KnowledgeGraph,
            referenced elsewhere in the TRAPI output by the dictionary key.
          additionalProperties:
            $ref: '#/components/schemas/Edge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QueryGraph:
      type: object
      description: >-
        A graph representing a biomedical question. It serves as a template for
        each result (answer), where each bound knowledge graph node/edge is
        expected to obey the constraints of the associated query graph element.
      properties:
        nodes:
          type: object
          description: >-
            The node specifications. The keys of this map are unique node
            identifiers and the corresponding values include the constraints
            on bound nodes.
          additionalProperties:
            $ref: '#/components/schemas/QNode'
        edges:
          type: object
          description: >-
            The edge specifications. The keys of this map are unique edge
            identifiers and the corresponding values include the constraints
            on bound edges, in addition to specifying the subject and object
            QNodes.
          additionalProperties:
            $ref: '#/components/schemas/QEdge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QNode:
      type: object
      description: A node in the QueryGraph used to represent an entity in a
        query. If a CURIE is not specified, any nodes matching the category
        of the QNode will be returned in the Results.
      properties:
        ids:
          type: array
          items:
            $ref: '#/components/schemas/CURIE'
          minItems: 1
          example: [OMIM:603903]
          description: CURIE identifier for this node
          nullable: true
        categories:
          type: array
          items:
            $ref: '#/components/schemas/BiolinkEntity'
          minItems: 1
          nullable: true
        is_set:
          type: boolean
          description: >-
            Boolean that if set to true, indicates that this QNode MAY have
            multiple KnowledgeGraph Nodes bound to it within each Result.
            The nodes in a set should be considered as a set of independent
            nodes, rather than a set of dependent nodes, i.e., the answer
            would still be valid if the nodes in the set were instead returned
            individually. Multiple QNodes may have is_set=True. If a QNode
            (n1) with is_set=True is connected to a QNode (n2) with
            is_set=False, each n1 must be connected to n2. If a QNode (n1)
            with is_set=True is connected to a QNode (n2) with is_set=True,
            each n1 must be connected to at least one n2.
          default: false
        constraints:
          type: array
          description: >-
            A list of contraints applied to a query node.
            If there are multiple items, they must all be true (equivalent
            to AND)
          items:
            $ref: '#/components/schemas/QueryConstraint'
          nullable: true
      additionalProperties: true
    QEdge:
      type: object
      description: >-
        An edge in the QueryGraph used as an filter pattern specification in a
        query. If optional predicate or relation properties are not specified,
        they are assumed to be wildcard matches to the target knowledge space.
        If specified, the ontological inheritance hierarchy associated with
        the terms provided is assumed, such that edge bindings returned may be
        an exact match to the given QEdge predicate or relation term ('class'),
        or to a term which is a subclass of the QEdge specified term.
      properties:
        predicates:
          type: array
          items:
            $ref: '#/components/schemas/BiolinkPredicate'
          minItems: 1
          nullable: true
        relation:
          type: string
          example: RO:0002447
          description: >-
            Query constraint against the relationship type term of this edge,
            as originally specified by, or curated by inference from, the
            original external source of knowledge. Note that this should
            often be specified as predicate ontology term CURIE, although
            this may not be strictly enforced.
          nullable: true
        subject:
          type: string
          example: https://omim.org/entry/603903
          description: >-
            Corresponds to the map key identifier of the
            subject concept node anchoring the query filter
            pattern for the query relationship edge.
        object:
          type: string
          example: https://www.uniprot.org/uniprot/P00738
          description: >-
            Corresponds to the map key identifier of the
            object concept node anchoring the query filter
            pattern for the query relationship edge.
        constraints:
          type: array
          description: >-
            A list of contraints applied to a query edge.
            If there are multiple items, they must all be true (equivalent
            to AND)
          items:
            $ref: '#/components/schemas/QueryConstraint'
          nullable: true
      additionalProperties: true
      required:
        - subject
        - object
    Node:
      type: object
      description: >-
        A node in the KnowledgeGraph which represents some biomedical
        concept. Nodes are identified by the keys in the KnowledgeGraph
        Node mapping.
      properties:
        name:
          type: string
          example: Haptoglobin
          description: Formal name of the entity
          nullable: true
        categories:
          type: array
          items:
            $ref: '#/components/schemas/BiolinkEntity'
          nullable: true
        attributes:
          type: array
          description: A list of attributes describing the node
          items:
            $ref: '#/components/schemas/Attribute'
          nullable: true
      additionalProperties: false
    Attribute:
      type: object
      description: >-
        Generic attribute for a node or an edge that expands the key-value
        pair concept by including fields for additional metadata. These fields
        can be used to describe the source of the statement made in key-value
        pair of the attribute object, or describe the attribute's value itself
        including its semantic type, or a url providing additional information
        about it.
      properties:
        attribute_type_id:
          $ref: '#/components/schemas/CURIE'
          description: >-
            The 'key' of the attribute object, holding a CURIE of an ontology
            property defining the attribute (preferably the CURIE of a
            Biolink association slot). This property captures the relationship
            asserted to hold between the value of the attribute, and the node
            or edge from  which it hangs. For example, that a value of
            '0.000153' represents a p-value supporting an edge, or that
            a value of 'ChEMBL' represents the original source of the knowledge
            expressed in the edge.
          example: Biolink:has_p-value_evidence, Biolink:has_original_source
        original_attribute_name:
          type: string
          description: >-
            The term used by the original source of an attribute to describe
            the meaning or significance of the value it captures. This may be
            a column name in a source tsv file, or a key in a source json
            document for the field in the data that held the attribute's
            value. Capturing this information  where possible lets us preserve
            what the original source said. Note that the data type is string'
            but the contents of the field could also be a CURIE of a third
            party ontology term.
          example: p-value
          nullable: true
        value:
          description: >-
            Value of the attribute. May be any data type, including a list.
          example: 0.000153
        value_type_id:
          allOf:
            - $ref: '#/components/schemas/CURIE'
          description: >-
            CURIE describing the semantic type of an  attribute's value. Use
            a Biolink class if possible, otherwise a term from an external
            ontology. If a suitable CURIE/identifier does not exist, enter a
            descriptive phrase here and submit the new type for consideration
            by the appropriate authority.
          example: EDAM:data_1187
          nullable: true
        attribute_source:
          type: string
          description: >-
            The source of the core assertion made by the key-value pair of an
            attribute object. Use a CURIE or namespace designator for this
            resource where possible.
          example: UniProtKB
          nullable: true
        value_url:
          type: string
          description: >-
            Human-consumable URL linking to a web document that provides
            additional information about an  attribute's value (not the node
            or the edge fom which it hangs).
          example: https://pubmed.ncbi.nlm.nih.gov/32529952
          nullable: true
        description:
          type: string
          description: >-
            Human-readable description for the attribute and its value.
          example: Assertion Authored By Dr. Trans L. Ator
          nullable: true
      required:
        - attribute_type_id
        - value
      additionalProperties: false
    Edge:
      type: object
      description: >-
        A specification of the semantic relationship linking two concepts
        that are expressed as nodes in the knowledge "thought" graph
        resulting from a query upon the underlying knowledge source.
      properties:
        predicate:
          allOf:
            - $ref: '#/components/schemas/BiolinkPredicate'
          nullable: true
        relation:
          type: string
          example: RO:0002447
          description: >-
            The relationship type term of this edge, originally specified by,
            or curated by inference from, the original source of knowledge.
            This should generally be specified as predicate ontology CURIE.
          nullable: true
        subject:
          $ref: '#/components/schemas/CURIE'
          example: OMIM:603903
          description: >-
            Corresponds to the map key CURIE of the
            subject concept node of this relationship edge.
        object:
          $ref: '#/components/schemas/CURIE'
          example: UniProtKB:P00738
          description: >-
            Corresponds to the map key CURIE of the
            object concept node of this relationship edge.
        attributes:
          type: array
          description: A list of additional attributes for this edge
          items:
            $ref: '#/components/schemas/Attribute'
          nullable: true
      additionalProperties: false
      required:
        - subject
        - object
    BiolinkEntity:
      description: >-
        Compact URI (CURIE) for a Biolink class, biolink:NamedThing
        or a child thereof. The CURIE must use the prefix 'biolink:'
        followed by the PascalCase class name.
      type: string
      pattern: ^biolink:[A-Z][a-zA-Z]*$
      externalDocs:
        description: Biolink model entities
        url: https://biolink.github.io/biolink-model/docs/NamedThing.html
      example: biolink:PhenotypicFeature
    BiolinkPredicate:
      description: >-
        CURIE for a Biolink 'predicate' slot, taken from the Biolink slot
        ('is_a') hierarchy rooted in biolink:related_to (snake_case). This
        predicate defines the Biolink relationship between the subject and
        object nodes of a biolink:Association defining a knowledge graph edge.
      type: string
      pattern: ^biolink:[a-z][a-z_]*$
      externalDocs:
        description: Biolink model predicates
        url: https://biolink.github.io/biolink-model/docs/related_to.html
      example: biolink:interacts_with
    CURIE:
      type: string
      description: >-
        A Compact URI, consisting of a prefix and a reference separated
        by a colon, such as UniProtKB:P00738. Via an external context
        definition, the CURIE prefix and colon may be replaced by a URI
        prefix, such as http://identifiers.org/uniprot/, to form a full
        URI.
      externalDocs:
        url: https://www.w3.org/TR/2010/NOTE-curie-20101216/
    MetaKnowledgeGraph:
      type: object
      description: >-
        Knowledge-map representation of this TRAPI web service. The meta
        knowledge graph is composed of the union of most specific categories
        and predicates for each node and edge.
      properties:
        nodes:
          type: object
          description: >-
            Collection of the most specific node categories provided by
            this TRAPI web service, indexed by Biolink class CURIEs.
            A node category is only exposed here if there is
            node for which that is the most specific category available.
          additionalProperties:
            $ref: '#/components/schemas/MetaNode'
        edges:
          type: array
          description: >-
            List of the most specific edges/predicates provided by this TRAPI
            web service. A predicate is only exposed here if there is an edge
            for which the predicate is the most specific available.
          items:
            $ref: '#/components/schemas/MetaEdge'
          minItems: 1
    MetaNode:
      type: object
      description: >-
        Description of a node category provided by this TRAPI web service.
      properties:
        id_prefixes:
          type: array
          description: >-
            List of CURIE prefixes for the node category that this TRAPI web
            service understands and accepts on the input.
          items:
            type: string
          minItems: 1
          example: [CHEMBL.COMPOUND, INCHIKEY]
      required:
        - id_prefixes
      additionalProperties: false
    MetaEdge:
      type: object
      description: >-
        Edge in a meta knowledge map describing relationship between a subject
        Biolink class and an object Biolink class.
      properties:
        subject:
          $ref: '#/components/schemas/BiolinkEntity'
          description: >-
            Subject node category of this relationship edge.
          example: biolink:ChemicalSubstance
        predicate:
          $ref: '#/components/schemas/BiolinkPredicate'
          description: >-
            Biolink relationship between the subject and object categories.
          example: biolink:affects
        object:
          $ref: '#/components/schemas/BiolinkEntity'
          description: >-
            Object node category of this relationship edge.
          example: biolink:Protein
        relations:
          type: array
          description: >-
            Low-level relations from the underlying source.
          items:
            type: string
          example: [inhibits, activates]
      required:
        - subject
        - predicate
        - object
      additionalProperties: false
    QueryConstraint:
      type: object
      description: >-
        Generic query constraint for a query node or query edge
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/CURIE'
          description: >-
            CURIE of the concept being constrained. For properties
            defined by the Biolink model this SHOULD be a biolink CURIE.
            otherwise, if possible, from the EDAM ontology. If a suitable
            CURIE does not exist, enter a descriptive phrase here and
            submit the new type for consideration by the appropriate
            authority.
          example: EDAM:data_0844
          nullable: false
        name:
          type: string
          description: >-
            Human-readable name or label for the constraint concept.
            If appropriate, it SHOULD be the term name of the CURIE used
            as the 'id'. This is redundant but required for human
            readability.
          example: molecular mass
          nullable: false
        not:
          type: boolean
          default: false
        operator:
          type: string
          description: >-
            Relationship between the database value and the constraint value
            for the specified id. The operators ==, >, and < mean
            is exactly equal to, is greater than, and is less than,
            respectively. The 'matches' operator indicates that the value
            is a regular expression to be evaluated. If value is a list type,
            then at least one evaluation must be true (equivalent to OR).
            This means that the == operator with a list acts like a SQL 'IN'
            clause. The 'not' property negates the operator such that not
            and == means 'not equal to' (or 'not in' for a list), and not >
            means <=, and not < means >=, and not matches means does not
            match. The '==' operator SHOULD NOT be used in a manner that
            describes an "is a" subclass relationship for the parent QNode.
          enum:
            - ==
            - '>'
            - <
            - matches
        value:
          example: 57.0
          description: >-
            Value of the attribute. May be any data type, including a list.
            If the value is a list and there are multiple items, at least one
            comparison must be true (equivalent to OR). If 'value' is of data
            type 'object', the keys of the object MAY be treated as a list.
            A 'list' data type paired with the '>' or '<' operators will
            encode extraneous comparisons, but this is permitted as it is in
            SQL and other languages.
        unit_id:
          example: UO:0000222
          description: >-
            CURIE of the units of the value or list of values in the 'value'
            property. The Units of Measurement Ontology (UO) should be used
            if possible. The unit_id MUST be provided for (lists of)
            numerical values that correspond to a quantity that has units.
        unit_name:
          example: kilodalton
          description: >-
            Term name that is associated with the CURIE of the units
            of the value or list of values in the 'value'
            property. The Units of Measurement Ontology (UO) SHOULD be used
            if possible. This property SHOULD be provided if a unit_id is
            provided. This is redundant but recommended for human readability.
      required:
        - name
        - id
        - operator
        - value
      additionalProperties: false