From 3d82d29d94531f78c063ee79e109d20de3b3e5e7 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Wed, 17 Dec 2025 10:34:50 -0800 Subject: [PATCH 1/6] refactor edge constraints into one nested object --- TranslatorReasonerAPI.yaml | 109 ++++++++++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 26 deletions(-) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index 7865e26..6f38443 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1043,7 +1043,28 @@ components: Corresponds to the map key identifier of the object concept node anchoring the query filter pattern for the query relationship edge. - attribute_constraints: + constraints: + description: >- + An object containing all constraints to be placed on the this QEdge. + ALL edges bound to this QEdge MUST conform to the given constraints; + underlying edges (such as those appearing in supporting graphs) + are not required to conform to the given constraints. + oneOf: + - $ref: '#/components/schemas/QEdgeConstraints' + nullable: true + additionalProperties: true + required: + - subject + - object + QEdgeConstraints: + type: object + description: >- + A container for constraints that might be placed on a given QEdge. + ALL edges bound to the given QEdge MUST conform to the given constraints; + underlying edges (such as those appearing in supporting graphs) + are not required to conform to the given constraints. + properties: + attributes: type: array description: >- A list of attribute constraints applied to a query edge. @@ -1052,7 +1073,7 @@ components: items: $ref: '#/components/schemas/AttributeConstraint' default: [] - qualifier_constraints: + qualifiers: type: array description: >- A list of QualifierConstraints that provide nuance to the QEdge. @@ -1060,15 +1081,59 @@ components: relationship between them. If the QEdge has multiple predicates or if the QNodes that correspond to the subject or object of this QEdge have multiple categories or multiple - curies, then qualifier_constraints MUST NOT be specified + curies, then constraints.qualifiers MUST NOT be specified because these complex use cases are not supported at this time. items: - $ref: '#/components/schemas/QualifierConstraint' + $ref: '#/components/schemas/QualifierSetConstraint' default: [] - additionalProperties: true + sources: + description: >- + A list of infores CURIEs which are to either be allowed or denied. + If `behavior` is set to "ALLOW", then ALL edges bound to the given + QEdge MUST have ANY of the given source inforeses present. + If `behavior` is set to "DENY", then ALL given inforeses MUST NOT + be present on a given edge in order for it to be validly bound in a result. + nullable: true + allOf: + - $ref: '#/components/schemas/AllowDenyConstraint' + - type: object + properties: + values: + type: array + items: + $ref: '#/components/schemas/CURIE' + primary_only: + type: boolean + description: >- + When set to `false` (the default), the ALLOW/DENY constraint + of the given values MUST be applied to ALL RetrievalSources + attached to a given edge in order for that edge to validly be + bound in a result. + When set to `true`, the constraint SHOULD ONLY apply to those + RetrievalSources which are acting as a primary_knowledge_source. + default: false + AllowDenyConstraint: + type: object + description: >- + A list of values which are to either be allowed or denied. + If `behavior` is set to "ALLOW", then ANY (at least 1) of the given values + MUST appear in the constrained property in order for it to meet the + constraint. + If `behavior` is set to "DENY", then ALL of the given values MUST NOT + appear in the constrained property in order for it to meet the constraint. + properties: + behavior: + type: string + enum: + - ALLOW + - DENY + values: + type: array + items: + type: string required: - - subject - - object + - behavior + - values QPath: type: object description: >- @@ -1365,30 +1430,22 @@ components: required: - qualifier_type_id - qualifier_value - QualifierConstraint: - additionalProperties: false + QualifierSetConstraint: + type: object description: >- - Defines a query constraint based on the - qualifier_types and qualifier_values of a set of - Qualifiers attached to an edge. For example, it can constrain a + Defines a constraint based on the Qualifiers attached to an edge. + A given key-pair value defines the required qualifier_type_id + and qualifier_value, respectively. + Multiple type-value pairs have an AND relationship. + For example, a QualifierSetConstraint can constrain a "ChemicalX - affects - ?Gene" query to return only edges where ChemicalX specifically affects the 'expression' of the Gene, by constraining on the qualifier_type "biolink:object_aspect_qualifier" with a qualifier_value of "expression". - properties: - qualifier_set: - type: array - description: >- - A set of Qualifiers that serves to add nuance to a query, - by constraining allowed values held by Qualifiers - on queried Edges. - items: - $ref: '#/components/schemas/Qualifier' - nullable: false - minItems: 1 - required: - - qualifier_set - type: object + minProperties: 1 + additionalProperties: + type: + string BiolinkEntity: description: >- Compact URI (CURIE) for a Biolink class, biolink:NamedThing From f82524f66ae17dd99c4b24897de67c8d1b30c400 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Wed, 17 Dec 2025 22:57:23 -0800 Subject: [PATCH 2/6] constraint description edits --- TranslatorReasonerAPI.yaml | 43 +++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index 6f38443..9568f9f 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1045,7 +1045,7 @@ components: pattern for the query relationship edge. constraints: description: >- - An object containing all constraints to be placed on the this QEdge. + An object containing all constraints placed on the QEdge. ALL edges bound to this QEdge MUST conform to the given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. @@ -1059,7 +1059,7 @@ components: QEdgeConstraints: type: object description: >- - A container for constraints that might be placed on a given QEdge. + A subschema for constraints that may be placed on a given QEdge. ALL edges bound to the given QEdge MUST conform to the given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. @@ -1076,8 +1076,8 @@ components: qualifiers: type: array description: >- - A list of QualifierConstraints that provide nuance to the QEdge. - If multiple QualifierConstraints are provided, there is an OR + A list of QualifierSetConstraints applied to a QEdge. + If multiple QualifierSetConstraints are provided, there is an OR relationship between them. If the QEdge has multiple predicates or if the QNodes that correspond to the subject or object of this QEdge have multiple categories or multiple @@ -1088,11 +1088,12 @@ components: default: [] sources: description: >- - A list of infores CURIEs which are to either be allowed or denied. - If `behavior` is set to "ALLOW", then ALL edges bound to the given - QEdge MUST have ANY of the given source inforeses present. - If `behavior` is set to "DENY", then ALL given inforeses MUST NOT - be present on a given edge in order for it to be validly bound in a result. + A list of infores CURIEs which are either allowed or denied in the + sources (resource_id) of the bound Edge. + If `behavior` is set to "ALLOW", ANY (at least 1) of the given infores + CURIEs MUST be present. + If `behavior` is set to "DENY", then ALL given infores CURIEs MUST NOT + be present. nullable: true allOf: - $ref: '#/components/schemas/AllowDenyConstraint' @@ -1100,17 +1101,20 @@ components: properties: values: type: array + description: >- + These SHOULD be infores CURIEs, so this is a subschema that + is more stringent than the one in AllowDenyConstraint. items: $ref: '#/components/schemas/CURIE' primary_only: type: boolean description: >- When set to `false` (the default), the ALLOW/DENY constraint - of the given values MUST be applied to ALL RetrievalSources - attached to a given edge in order for that edge to validly be + of the given values MUST be applied to ALL RetrievalSources in + the sources of the bound Edge for that edge to validly be bound in a result. - When set to `true`, the constraint SHOULD ONLY apply to those - RetrievalSources which are acting as a primary_knowledge_source. + When set to `true`, the constraint SHOULD ONLY be applied to the + RetrievalSource with the resource_role primary_knowledge_source. default: false AllowDenyConstraint: type: object @@ -1118,9 +1122,10 @@ components: A list of values which are to either be allowed or denied. If `behavior` is set to "ALLOW", then ANY (at least 1) of the given values MUST appear in the constrained property in order for it to meet the - constraint. + constraint (OR relationship). If `behavior` is set to "DENY", then ALL of the given values MUST NOT - appear in the constrained property in order for it to meet the constraint. + appear in the constrained property in order for it to meet the constraint + (NOT (x OR y) relationship). properties: behavior: type: string @@ -1433,15 +1438,15 @@ components: QualifierSetConstraint: type: object description: >- - Defines a constraint based on the Qualifiers attached to an edge. - A given key-pair value defines the required qualifier_type_id - and qualifier_value, respectively. - Multiple type-value pairs have an AND relationship. + A constraint on the qualifiers of a bound Edge (types and values). + A given key-value pair defines the required qualifier_type_id + and qualifier_value of one Qualifier, respectively. For example, a QualifierSetConstraint can constrain a "ChemicalX - affects - ?Gene" query to return only edges where ChemicalX specifically affects the 'expression' of the Gene, by constraining on the qualifier_type "biolink:object_aspect_qualifier" with a qualifier_value of "expression". + Multiple type-value pairs have an AND relationship. minProperties: 1 additionalProperties: type: From f83658dbebcbef691826b5b4128a4dc89c50a06a Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Wed, 17 Dec 2025 22:59:14 -0800 Subject: [PATCH 3/6] add restriction info to QEdgeConstraints --- TranslatorReasonerAPI.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index 9568f9f..22082fb 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1063,6 +1063,8 @@ components: ALL edges bound to the given QEdge MUST conform to the given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. + minProperties: 1 + additionalProperties: true properties: attributes: type: array From e61245889351c292f3954f51199b1d8eb71e2b40 Mon Sep 17 00:00:00 2001 From: tokebe <43009413+tokebe@users.noreply.github.com> Date: Thu, 18 Dec 2025 16:02:46 -0500 Subject: [PATCH 4/6] description consensus clarifications --- TranslatorReasonerAPI.yaml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index 22082fb..f3dd1f3 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1046,7 +1046,7 @@ components: constraints: description: >- An object containing all constraints placed on the QEdge. - ALL edges bound to this QEdge MUST conform to the given constraints; + ALL edges bound to this QEdge MUST conform to ALL given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. oneOf: @@ -1060,7 +1060,7 @@ components: type: object description: >- A subschema for constraints that may be placed on a given QEdge. - ALL edges bound to the given QEdge MUST conform to the given constraints; + ALL edges bound to the given QEdge MUST conform to ALL given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. minProperties: 1 @@ -1074,7 +1074,6 @@ components: to AND) items: $ref: '#/components/schemas/AttributeConstraint' - default: [] qualifiers: type: array description: >- @@ -1087,7 +1086,6 @@ components: because these complex use cases are not supported at this time. items: $ref: '#/components/schemas/QualifierSetConstraint' - default: [] sources: description: >- A list of infores CURIEs which are either allowed or denied in the @@ -1112,10 +1110,9 @@ components: type: boolean description: >- When set to `false` (the default), the ALLOW/DENY constraint - of the given values MUST be applied to ALL RetrievalSources in - the sources of the bound Edge for that edge to validly be - bound in a result. - When set to `true`, the constraint SHOULD ONLY be applied to the + of `values` applies to ALL RetrievalSources in + the sources of the bound Edge. + When set to `true`, the constraint ONLY applies to the RetrievalSource with the resource_role primary_knowledge_source. default: false AllowDenyConstraint: From 87d4bb0b3ff15ec300adf8c0903b27636b69af1f Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 18 Dec 2025 13:07:51 -0800 Subject: [PATCH 5/6] generic constraints: remove nullable lines --- TranslatorReasonerAPI.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index f3dd1f3..ff2dec8 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1051,7 +1051,6 @@ components: are not required to conform to the given constraints. oneOf: - $ref: '#/components/schemas/QEdgeConstraints' - nullable: true additionalProperties: true required: - subject @@ -1094,7 +1093,6 @@ components: CURIEs MUST be present. If `behavior` is set to "DENY", then ALL given infores CURIEs MUST NOT be present. - nullable: true allOf: - $ref: '#/components/schemas/AllowDenyConstraint' - type: object From 0f9d3365d97cbe9b96f4791be2e865c322ca4ba4 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 18 Dec 2025 14:06:16 -0800 Subject: [PATCH 6/6] generic constraints: add minItems:1 to arrays --- TranslatorReasonerAPI.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/TranslatorReasonerAPI.yaml b/TranslatorReasonerAPI.yaml index 66e1c85..a0d8c75 100644 --- a/TranslatorReasonerAPI.yaml +++ b/TranslatorReasonerAPI.yaml @@ -1013,6 +1013,7 @@ components: A list of attribute constraints applied to a query edge. If there are multiple items, they must all be true (equivalent to AND) + minItems: 1 items: $ref: '#/components/schemas/AttributeConstraint' qualifiers: @@ -1025,6 +1026,7 @@ components: object of this QEdge have multiple categories or multiple curies, then constraints.qualifiers MUST NOT be specified because these complex use cases are not supported at this time. + minItems: 1 items: $ref: '#/components/schemas/QualifierSetConstraint' sources: @@ -1044,6 +1046,7 @@ components: description: >- These SHOULD be infores CURIEs, so this is a subschema that is more stringent than the one in AllowDenyConstraint. + minItems: 1 items: $ref: '#/components/schemas/CURIE' primary_only: @@ -1073,6 +1076,7 @@ components: - DENY values: type: array + minItems: 1 items: type: string required: