From bbdf2f491728cb02dedb3d2237a410d38aa7dc5b Mon Sep 17 00:00:00 2001 From: Sunny Aggarwal Date: Thu, 5 Nov 2026 12:30:53 +0530 Subject: [PATCH 1/2] OpenConceptLab/ocl_issues#2943 | Expansion system-version resolves in the owner namespace and allows one version per source --- .../apireference/collectionReferenceEvaluation.md | 5 +++-- docs/source/oclapi/apireference/expansions.md | 14 ++++++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/source/oclapi/apireference/collectionReferenceEvaluation.md b/docs/source/oclapi/apireference/collectionReferenceEvaluation.md index 5fd33f4..5303d0a 100644 --- a/docs/source/oclapi/apireference/collectionReferenceEvaluation.md +++ b/docs/source/oclapi/apireference/collectionReferenceEvaluation.md @@ -194,7 +194,7 @@ After each reference is evaluated, **expansion parameters** are applied to filte | `filter` | Text filter to restrict resources by display name or code (applied via Elasticsearch). | | `date` | Only include resources that existed as of this date (applied via date comparison). | | `exclude-system` | Exclude resources from the specified code system (applied via source URI matching). | -| `system-version` | Specifies a version to use for a system when the reference does not specify one. Multiple systems can be comma-separated. Takes precedence over the expansion's version lock (see [Version Locking](#version-locking)). | +| `system-version` | Specifies a version to use for a system when the reference does not specify one. Multiple systems can be comma-separated, one version per system. Takes precedence over the expansion's version lock (see [Version Locking](#version-locking)). | Parameters are applied in a specific order: `activeOnly` (before filter), then `date`, `exclude-system`, and `filter` (after filters). @@ -230,7 +230,8 @@ For each reference with a `system`, OCL picks the source version as follows. Some details: - OCL compares sources by their URL without the version, so a canonical URL and a relative URL for the same source share one lock. - Exclude references follow the same rules as include references. -- OCL resolves each `system-version` entry with `$resolveReference` in the global namespace. An entry that doesn't resolve is listed in `unresolved_repo_versions` with type `expansion.parameters.system-version`, and references to that source skip step 1. If the parameter names more than one version of a source, OCL evaluates each unversioned reference to that source against every one of them. +- OCL resolves each `system-version` entry with `$resolveReference` in the namespace of the collection's owner, as it resolves the collection's references. With URL registries in use, a canonical URL is looked up in the owner's URL registry, then among the owner's repositories, then in the global URL registry. Otherwise OCL looks for a canonical URL in every namespace. An entry that doesn't resolve is listed in `unresolved_repo_versions` with type `expansion.parameters.system-version`, and references to that source skip step 1. +- `system-version` may name only one version of a source, as in FHIR's `$expand`. Creating an expansion whose `system-version` names two different versions of one source fails with `400 Bad Request`, and no expansion is created. A collection whose own references name both versions is still valid: each of those references uses the version it names (rule 1). ### When a lock carries over diff --git a/docs/source/oclapi/apireference/expansions.md b/docs/source/oclapi/apireference/expansions.md index dc985aa..b93ab4e 100644 --- a/docs/source/oclapi/apireference/expansions.md +++ b/docs/source/oclapi/apireference/expansions.md @@ -65,6 +65,20 @@ POST /user/collections/:collection/:collectionVersion/expansions/ ``` Status: 201 Created ``` + +If `system-version` names two different versions of one source (for example `http://loinc.org|2.56,http://loinc.org|2.57`), the request fails and no expansion is created: +``` +Status: 400 Bad Request +``` +``` +{ + "parameters": { + "system-version": [ + "Names more than one version of /orgs/Regenstrief/sources/LOINC/: http://loinc.org|2.56, http://loinc.org|2.57. Use only one version of a source in system-version." + ] + } +} +``` ``` { "mnemonic": "test", From 1b44fea18c9723ca0b8cf8a44d47333dbcb1aca9 Mon Sep 17 00:00:00 2001 From: Sunny Aggarwal Date: Thu, 5 Nov 2026 12:37:18 +0530 Subject: [PATCH 2/2] OpenConceptLab/ocl_issues#2943 | Keep the 201 example together; note the non-string 400 --- docs/source/oclapi/apireference/expansions.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/source/oclapi/apireference/expansions.md b/docs/source/oclapi/apireference/expansions.md index b93ab4e..0d9d8a4 100644 --- a/docs/source/oclapi/apireference/expansions.md +++ b/docs/source/oclapi/apireference/expansions.md @@ -65,20 +65,6 @@ POST /user/collections/:collection/:collectionVersion/expansions/ ``` Status: 201 Created ``` - -If `system-version` names two different versions of one source (for example `http://loinc.org|2.56,http://loinc.org|2.57`), the request fails and no expansion is created: -``` -Status: 400 Bad Request -``` -``` -{ - "parameters": { - "system-version": [ - "Names more than one version of /orgs/Regenstrief/sources/LOINC/: http://loinc.org|2.56, http://loinc.org|2.57. Use only one version of a source in system-version." - ] - } -} -``` ``` { "mnemonic": "test", @@ -105,6 +91,22 @@ Status: 400 Bad Request } ``` +If `system-version` names two different versions of one source (for example `http://loinc.org|2.56,http://loinc.org|2.57`), the request fails and no expansion is created: +``` +Status: 400 Bad Request +``` +``` +{ + "parameters": { + "system-version": [ + "Names more than one version of /orgs/Regenstrief/sources/LOINC/: http://loinc.org|2.56, http://loinc.org|2.57. Use only one version of a source in system-version." + ] + } +} +``` + +A `system-version` that isn't a string (such as a list) also fails with `400 Bad Request`. + ### Expansion Parameters Adapted from [FHIR’s value set expansion specification](https://www.hl7.org/fhir/valueset-operation-expand.html):