Skip to content

Commit 75df910

Browse files
edeutschedeutsch
committed
Merge remote-tracking branch 'origin/2.0'
2 parents 8fed075 + 33dcf38 commit 75df910

25 files changed

Lines changed: 3065 additions & 1297 deletions

‎.github/workflows/docgen.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Generate Reference
3+
on:
4+
pull_request:
5+
push:
6+
branches: [master, main, 'v?[0-9]+.[0-9]+']
7+
jobs:
8+
docgen:
9+
name: Run generator script
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout the repository
13+
uses: actions/checkout@v4
14+
with:
15+
ref: ${{ github.event.pull_request.head.ref }}
16+
repository: ${{ github.event.pull_request.head.repo.full_name }}
17+
- name: Set up Python 3.13
18+
uses: actions/setup-python@v6
19+
with:
20+
python-version: '3.13'
21+
- name: Install deps
22+
run: |
23+
pip install -r docs/requirements.txt
24+
- name: Run script
25+
run: python docs/generate_reference.py ${{ github.head_ref || github.ref_name }}
26+
- name: commit changes
27+
uses: stefanzweifel/git-auto-commit-action@v7
28+
with:
29+
commit_message: Update docs/reference.md [no ci]
30+
file_pattern: docs/reference.md

‎.github/workflows/pr-checks.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: PR checks
3+
on:
4+
pull_request:
5+
push:
6+
branches: [master, main, 'v?[0-9]+.[0-9]+']
7+
jobs:
8+
linting:
9+
name: Check Yamllint
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout the repository
13+
uses: actions/checkout@v4
14+
with:
15+
ref: ${{ github.event.pull_request.head.ref }}
16+
repository: ${{ github.event.pull_request.head.repo.full_name }}
17+
- name: Set up Python 3.13
18+
uses: actions/setup-python@v6
19+
with:
20+
python-version: '3.13'
21+
- name: Install deps
22+
run: |
23+
pip install yamllint yamlfix
24+
- name: Add yamllint annotator
25+
uses: pr-annotators/yamllint-pr-annotator@v1.0.0
26+
- name: Run yamllint
27+
run: |-
28+
yamllint -f parsable TranslatorReasonerAPI.yaml
29+
format_check:
30+
name: Check Yamlfix
31+
runs-on: ubuntu-latest
32+
steps:
33+
- name: Checkout the repository
34+
uses: actions/checkout@v4
35+
with:
36+
ref: ${{ github.event.pull_request.head.ref }}
37+
repository: ${{ github.event.pull_request.head.repo.full_name }}
38+
- name: Set up Python 3.13
39+
uses: actions/setup-python@v6
40+
with:
41+
python-version: '3.13'
42+
- name: Install deps
43+
run: |
44+
pip install yamllint yamlfix
45+
- name: Run yamlfix
46+
run: |-
47+
yamlfix TranslatorReasonerAPI.yaml
48+
- name: Verify no format changes
49+
uses: tj-actions/verify-changed-files@v20.0.4
50+
id: verify-changed-files
51+
with:
52+
files: |
53+
TranslatorReasonerAPI.yaml
54+
- name: Log diff after yamlfix
55+
if: steps.verify-changed-files.outputs.files_changed == 'true'
56+
run: |-
57+
git diff --unified=0 TranslatorReasonerAPI.yaml
58+
echo '::error::Yamlfix would make changes, see logs for details.'
59+
exit 1

‎.yamlfix.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sequence_style = "keep_style"
2+
line_length = 75

‎.yamllint.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1+
---
12
extends: default
2-
33
rules:
44
document-start: disable
55
empty-values:
66
forbid-in-block-mappings: true
77
line-length:
8-
max: 79
8+
max: 88
99
quoted-strings:
1010
quote-type: single
1111
required: only-when-needed

‎ChangeLog.md‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,82 @@
1-
# Change Log TRAPI 1.4.0 (2023-06-23) -> 1.5.0 (2023-05-26)
1+
# Change Log 1.6.0-beta (2025-06-06) -> 2.0.0-dev (2026-03-25)
2+
3+
### 1. QEdge Constraints Refactor (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#1-qedge-constraints-refactor), [reference doc entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#qedge-))
4+
- `QEdge.attribute_constraints` and `QEdge.qualifier_constraints`have been removed and replaced with `QEdge.constraints`, which is an object that can contain constraints for `knowledge_level`, `agent_type`, `sources`, `attributes`, and `qualifiers`
5+
- The new `sources` constraint has ALLOW and DENY constructs with an optional `primary_only` flag
6+
7+
### 2. Add Query.parameters and Response.parameters to contain existing log_level and bypass_cache parameters and add timeout query parameter (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#2-new-queryresponse-parameters), [reference doc entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#queryparameters-))
8+
- Move `Query.log_level` to `Query.parameters.log_level`
9+
- Move `Query.bypass_cache` to `Query.parameters.bypass_cache`
10+
- Add `Query.parameters.timeout`
11+
- Add `Response.parameters` that conveys the same parameters as `Query.parameters`
12+
- Add HTTP 409 code
13+
14+
### 3. Binding Structure Changes (NodeBinding/EdgeBinding/PathBinding) (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#3-binding-structure-changes-nodeedgepath), [PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/546))
15+
- `<node/edge/path>_bindings` are now minProperties: 1 (i.e. when these fields are present, they MUST contain data)
16+
- `id` properties renamed to `ids` and is now a list
17+
- `ids` arrays are minItems: 1 (this property is required)
18+
- `attributes` property completely removed
19+
- `query_id` was removed from NodeBinding (obsolete with the current subclassing behavior)
20+
- Each binding is now an object containing only `ids` (which is a list), instead of a list of objects each with `id` and `attributes`
21+
22+
### 4. KL/AT turned into top-level Edge properties, now required (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#4-klat-turned-into-top-level-edge-properties-now-required), [PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/536/changes/e21490eca92c7f1bf2df5baa6d3711da30d197f4..9d402d20e3fdee360976857fbdbd57c7f09d1a38))
23+
- `Edge.knowledge_level` and `Edge.agent_type` are now required `Edge` properties instead of being located within `attributes`
24+
25+
### 5. Add COLLATE option to QNode.set_interpretation enum (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#5-add-collate-option-to-qnodeset_interpretation), [PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/543/changes))
26+
27+
### 6. null is no longer a valid value in queries and responses (see [migration guide entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md#6-null-is-no-longer-a-valid-value-in-queries-and-responses), [issue for context](https://github.com/NCATSTranslator/ReasonerAPI/issues/527))
28+
- Remove `nullable: true/false` designations for all properties. Properties with no data must now be *absent* from TRAPI JSON or an empty array/object if the schema allows, rather than allowed to be present but with a null value. Some field descriptions explicitly state that the empty array/object MUST be used in certain circumstances.
29+
30+
### 7. Many properties set to <minItems/minProperties>: 1
31+
In the following properties, empty lists are no longer permitted to say "no data here". "No data" is now expressed with an absent property:
32+
- [`QueryGraph.nodes`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#querygraph-): [PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/548)
33+
- `QueryGraph.edges`
34+
- [`Response.logs`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#response-)
35+
- [`Message.auxiliary_graphs`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#message-)
36+
- [`Result.analyses`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#result-)
37+
- [`Analysis.support_graphs`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#analysis-)
38+
- [`QNode.member_ids`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#qnode-)
39+
- `QNode.constraints`
40+
- [`Edge.qualifiers`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#edge-)
41+
- [`MetaKnowledgeGraph.nodes`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#metaknowledgegraph-)
42+
- [`MetaEdge.qualifiers`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#metaedge-)
43+
- [`MetaQualifier.applicable_values`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#metaqualifier-)
44+
- [`RetrievalSource.upstream_resource_ids`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#retrievalsource-)
45+
- `RetrievalSource.source_record_urls`
46+
47+
### 8. Removed AuxiliaryGraph.attributes property ([reference doc entry](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#auxiliarygraph-))
48+
- It was previously required, but never used and its empty arrays bloated responses. Additional undefined properties are still allowed in AuxiliaryGraph objects.
49+
50+
### 9. The following properties changed to not-required
51+
- [`Nodes.attributes`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#node-) (to reduce bloat)
52+
- [`QueryGraph.edges`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#querygraph-) and `QueryGraph.paths` (to accommodate queries with only nodes) (e.g. "what are the attributes of CURIE:123?")
53+
- [`KnowledgeGraph.edges`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#knowledgegraph-) (to accommodate queries with only nodes)
54+
- [`Result.analyses`](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/docs/reference.md#result-) (to accommodate queries with only nodes)
55+
56+
### 10. Analysis is technically allowed to have both edge and path bindings (experimental use, [PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/547))
57+
58+
### 11. YAML specification document migrated from OpenAPI 3.0.1 to OpenAPI 3.1.2 ([PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/533))
59+
- All `example` attributes become `examples` in OpenAPI 3.1.2
60+
61+
### 12. BaseQueryGraph and BaseAnalysis base classes removed in favor of single QueryGraph and Analysis classes that support both pathfinder and regular queries
62+
63+
[PR](https://github.com/NCATSTranslator/ReasonerAPI/pull/544), but look at 2.0 yaml for up-to-date versions of those sub-schemas.
64+
65+
=============
66+
67+
68+
69+
# Change Log TRAPI 1.5.0 (2024-05-26) -> 1.6.0-beta (2025-06-06)
70+
71+
- Diff: https://github.com/NCATSTranslator/ReasonerAPI/compare/1.5...1.6
72+
- TRAPI 1.6.0-beta was designed to be backwards compatible while adding support for Pathfinder queries. Any valid TRAPI 1.5.0 document is also a valid TRAPI 1.6.0 document.
73+
- Split `QueryGraph` into `BaseQueryGraph`, `PathfinderQueryGraph` (for Pathfinder support), and `QueryGraph` (for all other queries). The latter two classes inherit from `BaseQueryGraph`
74+
- Split `Analysis` into `BaseAnalysis`, `PathfinderAnalysis` (for Pathfinder support), and `Analysis` (for all other queries). The latter two classes inherit from `BaseAnalysis`
75+
- Add `PathfinderQueryGraph.QPath` class containing properties `subject`, `object`, `predicates`, and `constraints`
76+
77+
=============
78+
79+
# Change Log TRAPI 1.4.0 (2023-06-23) -> 1.5.0 (2024-05-26)
280

381
https://github.com/NCATSTranslator/ReasonerAPI/compare/v1.4.0...1.5
482

0 commit comments

Comments
 (0)