AWS healthimaging documentation change
Summary
Added comprehensive documentation for the 'includefield' query parameter in QIDO-RS queries, including syntax, supported values, behavior rules, sequence attribute handling, private tag retrieval, bulkdata handling, and full attribute lists for study/series/instance levels.
Security assessment
The changes exclusively document a new query parameter feature without mentioning security vulnerabilities, access controls, or authentication mechanisms. The added content focuses on data retrieval functionality without evidence of addressing security flaws or describing security features.
Diff
diff --git a/healthimaging/latest/devguide/dicomweb-search.md b/healthimaging/latest/devguide/dicomweb-search.md index d8683c38f..2c3dc779f 100644 --- a//healthimaging/latest/devguide/dicomweb-search.md +++ b//healthimaging/latest/devguide/dicomweb-search.md @@ -7 +7 @@ -DICOMweb search APIs for HealthImagingSupported DICOMweb query types for HealthImaging +DICOMweb search APIs for HealthImagingSupported DICOMweb query types for HealthImagingUsing IncludeField in QIDO-RS queries @@ -15 +15 @@ AWS HealthImaging offers representations of [ DICOMweb QIDO-RS](https://www.dico -HealthImaging's DICOMweb APIs can be used to return image set information with QIDO-RS. HealthImaging DICOMweb APIs reference only [image sets](./getting-started-concepts.html#concept-image-set) unless otherwise noted. Use HealthImaging [cloud native actions,](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_Operations.html) or the optional image set parameter of DICOMweb actions to retrieve non-primary image sets. HealthImaging's DICOMweb APIs can be used to return image set information with DICOMweb-conformant responses. +HealthImaging's DICOMweb APIs can be used to return image set information with QIDO-RS. HealthImaging DICOMweb APIs reference only primary [image sets](./getting-started-concepts.html#concept-image-set) unless otherwise noted. Use HealthImaging [cloud native actions,](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_Operations.html) or the optional image set parameter of DICOMweb actions to retrieve non-primary image sets. HealthImaging's DICOMweb APIs can be used to return image set information with DICOMweb-conformant responses. @@ -54,0 +55,260 @@ FuzzyMatching queries | Enable fuzzy matching on name DICOM attributes (Patient +IncludeField queries | Use the `includefield` query parameter to request additional DICOM attributes beyond the default response set. Return specific attributes by tag: `.../studies?PatientID=11235813&includefield=00101081&includefield=PatientWeight` Return all available attributes: `.../studies?PatientID=11235813&includefield=all` Return sequence (SQ) sub-attributes using dotted notation: `.../studies?PatientID=11235813&includefield=00080096.00080100` Return private data elements: `.../instances?includefield=00191001&00190010=Philips` + +## Using IncludeField in QIDO-RS queries + +The `includefield` query parameter lets you request additional DICOM attributes beyond the default response set in HealthImaging QIDO-RS queries. You can use `includefield` at the study, series, and instance levels. + +### Syntax + +Use the following GET request format to include additional fields in your QIDO-RS queries: + + + GET .../studies?<query_params>&includefield=<tag_or_keyword> + GET .../studies/<StudyInstanceUID>/series?<query_params>&includefield=<tag_or_keyword> + GET .../studies/<StudyInstanceUID>/series/<SeriesInstanceUID>/instances?<query_params>&includefield=<tag_or_keyword> + +You can specify multiple `includefield` parameters in a single request: + + + GET .../studies?PatientID=11235813&includefield=00101081&includefield=00101030&includefield=00101010 + +### Supported values for includefield + +The following table describes the supported values for the `includefield` parameter. + +Supported includefield values Value type | Description | Example +---|---|--- +DICOM tag (8 hex characters) | Request a specific DICOM attribute by its tag in GGGGEEEE format. | `includefield=00081030` +`all` | Request all available DICOM attributes for the resource level. | `includefield=all` +Dotted SQ path | Request a specific sub-attribute within a Sequence (SQ) attribute using dot notation: <parent_tag>.<child_tag>. | `includefield=00080096.00080100` +Private data element tag | Request a private tag (odd-group element). Requires the `privateCreatorElement` parameter. | `includefield=00191001` +Standard DICOM attributes including bulkdata | Request specific single or multiple attributes by tag or keyword. | `includefield=00102201` + +### Behavior and rules + +The following rules apply to `includefield` queries: + + * **Default response** – Without `includefield`, the QIDO-RS response returns only the standard set of attributes. + + * **includefield=all** – Returns all available attributes at the requested level. When `all` is combined with other `includefield` values, `all` takes priority. + + * **Maximum tags** – A request can include up to 50 `includefield` parameters. + + * **Duplicate tags** – Duplicate `includefield` values are deduplicated and treated as a single request. + + * **Invalid or missing tags** – If a requested tag does not exist in the DICOM data or is invalid, it is silently omitted from the response. Other valid `includefield` attributes are still returned. + + + + +### Sequence (SQ) attributes + +Use dot notation to request nested attributes within a Sequence (SQ) attribute: + + + includefield=<parent_SQ_tag>.<child_tag> + +For example, to retrieve CodeValue (0008,0100) within ReferringPhysicianIdentificationSequence (0008,0096): + + + GET .../studies?PatientID=11235813&includefield=00080096.00080100 + +Multi-level nesting is supported. For example: + + + includefield=00081115.00081199.00081150 + +### Private tags + +Private DICOM data elements (odd-group tags) are supported at all resource levels. To request private tags, include the `privateCreatorElement` query parameter. + +Use the following syntax: + + + GET .../instances?includefield=<private_tag>&<creator_tag>=<creator_name> + +For example: + + + GET .../instances?includefield=00191001&00190010=Philips + +The following rules apply to private tags: + + * The `privateCreatorElement` tag and creator name must be provided as a match parameter if the private tag is requested. + + * If the specified `privateCreatorElement` is not found, the private tag is silently omitted. + + * Requesting only a `privateCreatorElement` tag without a private data element returns the creator element name and value only. It does not return all tags belonging to that creator's block. + + + + +### Bulkdata tags + +DICOM attributes with bulkdata VRs (OB, OD, OF, OL, UN, OW, OV) with binary value greater than 1 MB requested as part of the `includefield` are returned as `bulkdataURI` instead of the raw binary value. For more information about retrieving bulkdata, see [Retrieving DICOM bulkdata in HealthImaging](https://docs.aws.amazon.com/healthimaging/latest/devguide/dicom-retrieve-bulkdata.html). + +### What does includefield=all return at each level? + +When `includefield=all` is specified, the response includes all attributes at the specific resource level. + +#### Study level (includefield=all) + +The following table lists all attributes returned at the study level when `includefield=all` is specified. + +Study level attributes for includefield=all Tag | Name | VR +---|---|--- +00080005| SpecificCharacterSet| CS +00080020| StudyDate| DA +00080030| StudyTime| TM +00080050| AccessionNumber| SH +00080051| IssuerOfAccessionNumberSequence| SQ +00080056| InstanceAvailability| CS +00080061| ModalitiesInStudy| CS +00080062| SOPClassesInStudy| UI +00080090| ReferringPhysicianName| PN +0008009C| ConsultingPhysicianName| PN +00080201| TimezoneOffsetFromUTC| SH +00081030| StudyDescription| LO +00081048| PhysiciansOfRecord| PN +00081060| NameOfPhysiciansReadingStudy| PN +00081080| AdmittingDiagnosesDescription| LO +00081190| RetrieveURL| UR +00100010| PatientName| PN +00100020| PatientID| LO +00100021| IssuerOfPatientID| LO +00100022| TypeOfPatientID| CS +00100026| SourcePatientGroupIdentificationSequence| SQ +00100027| GroupOfPatientsIdentificationSequence| SQ +00100028| SubjectRelativePositionInImage| US +00100030| PatientBirthDate| DA +00100032| PatientBirthTime| TM +00100033| PatientBirthDateInAlternativeCalendar| LO +00100034| PatientDeathDateInAlternativeCalendar| LO +00100035| PatientAlternativeCalendar| CS +00100040| PatientSex| CS +00100050| PatientInsurancePlanCodeSequence| SQ +00100101| PatientPrimaryLanguageCodeSequence| SQ +00100102| PatientPrimaryLanguageModifierCodeSequence| SQ +00100200| QualityControlSubject| CS +00100201| QualityControlSubjectTypeCodeSequence| SQ +00100213| StrainNomenclature| LO +00100214| StrainStockNumber| LO +00100215| StrainSourceRegistryCodeSequence| SQ +00100217| StrainSource| LO +00100219| StrainCodeSequence| SQ +00100223| GeneticModificationsNomenclature| LO +00100229| GeneticModificationsCodeSequence| SQ +00101001| OtherPatientNames| PN +00101005| PatientBirthName| PN +00101010| PatientAge| AS +00101020| PatientSize| DS +00101021| PatientSizeCodeSequence| SQ +00101022| PatientBodyMassIndex| DS +00101023| MeasuredAPDimension| DS +00101024| MeasuredLateralDimension| DS +00101030| PatientWeight| DS +00101040| PatientAddress| LO +00101060| PatientMotherBirthName| PN +00101080| MilitaryRank| LO +00101081| BranchOfService| LO +00102000| MedicalAlerts| LO +00102110| Allergies| LO +00102150| CountryOfResidence| LO +00102152| RegionOfResidence| LO +00102154| PatientTelephoneNumbers| SH +00102160| EthnicGroup| SH +00102180| Occupation| SH +001021A0| SmokingStatus| CS +001021C0| PregnancyStatus| US +001021D0| LastMenstrualDate| DA +001021F0| PatientReligiousPreference| LO +00102201| PatientSpeciesDescription| LO +00102202| PatientSpeciesCodeSequence| SQ +00102203| PatientSexNeutered| CS +00102210| AnatomicalOrientationType| CS +00102292| PatientBreedDescription| LO +00102293| PatientBreedCodeSequence| SQ +00102295| BreedRegistrationNumber| LO +00102296| BreedRegistryCodeSequence| SQ +00102297| ResponsiblePerson| PN +00102298| ResponsiblePersonRole| CS +00102299| ResponsibleOrganization| LO +00109431| ExaminedBodyThickness| FL +0020000D| StudyInstanceUID| UI +00200010| StudyID| SH +00201206| NumberOfStudyRelatedSeries| IS +00201208| NumberOfStudyRelatedInstances| IS +00321032| RequestingPhysician| PN +00321033| RequestingService| LO +00321060| RequestedProcedureDescription| LO