Ncats Arax

ARAX artifact and output contract

Contents

• Artifact sets

• Exact byte preservation

• Query summary

• Normalization and preflight summaries

• Provenance interpretation

• Truncation and completeness

• Manifest

• Warnings and exit codes

Artifact sets

Every graph query requires a new or empty output directory and writes:

request.json
response.json
summary.json
manifest.json

Normalization writes the exact entity response, a bounded normalization summary, and a manifest. Preflight writes the exact OpenAPI response, a service summary, and a manifest only when an output directory is requested. GET commands do not create a fictitious request.json; the corresponding manifest file, byte, and hash fields are null. Offline summarize writes nothing.

Reject an existing nonempty directory before network access. Write artifacts through a private temporary file, flush and fsync, set mode 0600 where supported, and atomically replace the final path. Write the manifest last.

Exact byte preservation

Serialize a POST body once with sorted keys, compact separators, UTF-8, and ensure_ascii=False. Save and send that same byte string. Request Accept-Encoding: identity, save the raw response before JSON parsing, and hash request and response bytes with SHA-256.

Read at most 26,214,401 response bytes. If the extra byte exists, treat the response as oversized, save no partial response.json, retain the request when applicable, write a terminal manifest, and exit 6. A bounded HTTP-error body is preserved exactly. A bounded malformed JSON response is also preserved, but no misleading summary is produced.

Query summary

summary.json is a normalized bounded view; response.json remains authoritative.

{
  "schema_version": "1.0",
  "query": {
    "kind": "one-hop|two-hop",
    "mode": "lookup|federated",
    "provider_ids": [],
    "expand_order": "right-first|left-first|null",
    "qnode_ids": {},
    "result_limit": 20
  },
  "service": {
    "base_url": null,
    "arax_version": null,
    "trapi_version": null,
    "biolink_version": null
  },
  "counts": {
    "results_returned": 0,
    "results_summarized": 0,
    "analyses_summarized": 0,
    "bound_edges_summarized": 0,
    "knowledge_graph_nodes": 0,
    "knowledge_graph_edges": 0,
    "server_total_results_count": null
  },
  "truncation_status": "no|possible|confirmed",
  "completeness": "complete|partial|unknown",
  "results": [],
  "warnings": []
}

Keep response order. A result contains its one-based unscored position, bounded description, normalized node bindings, and separate analyses. Each analysis contains its resource ID, returned score, support-graph IDs, and bound-edge objects grouped by query-edge key.

A bound-edge object contains the returned edge ID, physical subject/predicate/object and names, query-direction match flag, qualifiers, full source objects, role-derived source ID lists, publication IDs and availability, and support-graph IDs and status.

Normalization and preflight summaries

A normalization summary records the input, expected category, whether free-text confirmation is required, service versions, canonical identifier/name/category, category-count mapping, total synonym count, bounded candidate preview, and warnings.

A preflight summary records service versions plus Boolean checks for ARAX identity, /query, and version compatibility. Preflight also requires POST /query and GET /entity in OpenAPI. Neither summary claims graph results. Normalization retains preflight version/endpoint warnings.

Provenance interpretation

Use each analysis's edge_bindings to select knowledge-graph edges. Do not include unrelated graph edges. Preserve multiple analyses separately and retain all entries from each bound edge's sources, including resource_id, resource_role, upstream_resource_ids, and source_record_urls. Derive unique, first-seen resource ID lists for primary, aggregator, and supporting-data roles without discarding the full objects.

Preserve returned qualifiers as type/value pairs. Preserve physical edge direction and set matches_query_direction: false rather than rewriting a reversed edge.

V1 recognizes biolink:publications edge attributes. Accept a string or list of strings and deduplicate in first-seen order. Missing recognized metadata means:

publication_ids: []
publication_availability: not_returned

It never means that no publications exist.

Use analysis.support_graphs as the support-graph references. If none are returned, report not_returned; if all appear in message.auxiliary_graphs, report available; if a referenced ID is absent, report missing and warn.

Truncation and completeness

• Fewer results than the requested limit: no, unless logs or counts show removal.

• Exactly the limit: possible and RESULT_LIMIT_REACHED.

• More than the limit, an explicit pruning/removal log, or a larger server total: confirmed.

Keep only the first requested number of results in the normalized summary while preserving the entire size-bounded raw response.

KP timeout, provider error, or malformed-provider evidence in warning/error logs yields completeness: partial, result_status: partial, retained artifacts, and exit 7 in either lookup or federated mode. Informational timeout configuration and advisory CURIE warnings do not alone indicate provider failure. This classification depends on returned logs; complete means no recognized failure was reported, not that every possible biomedical relationship was searched.

HTTP 200 alone is not success. ARAX can return an application error in status (for example, InvalidKP or QueryNotTraversable). An explicit status other than Success or legacy OK produces exit 6 with the raw response and failure manifest retained, but no success summary. Absent/null status is allowed by TRAPI and still requires the graph/results checks. A valid successful results: [] remains a zero-result lookup. Malformed responses also produce no summary. This behavior follows the ARAX query envelope handling and provider response handling.

Manifest

The manifest records run UUID, UTC timestamps, command, execution/result status, privacy acknowledgment, fixed client identity, service versions, request/response method, URL, filenames, byte counts, hashes, elapsed time, applied limits, attempt counts, artifact names, bounded error, and warnings. Fields for artifacts that do not exist are null rather than false filenames.

Execution statuses are success, http_error, and client_error. Result statuses are results, no_results, partial, and not_available.

Warnings and exit codes

Warnings are objects with a stable code, bounded sanitized message, and a small scalar context. Supported codes:

PUBLIC_QUERY
NORMALIZATION_REQUIRES_CONFIRMATION
NORMALIZATION_CATEGORY_MISMATCH
NO_RESULTS
NO_PUBLICATIONS_RETURNED
NO_PRIMARY_SOURCE_RETURNED
UNSCORED_RESPONSE_ORDER
RESULT_LIMIT_REACHED
INTERNAL_PRUNING_DETECTED
KP_TIMEOUT
KP_ERROR
MALFORMED_KP_RESPONSE
MISSING_AUXILIARY_GRAPH
REVERSED_EDGE_BINDING
UNTESTED_SERVICE_VERSION
NONPRODUCTION_ENDPOINT

Exit codes:

Text output prints at most the bounded result set and ten publication IDs per edge, labels every position unscored, includes all source-role IDs, and points to summary.json and response.json. Use "ARAX returned" and "not returned under these constraints," never proof, absence, or ranking language.