Collections

Overview

The API exposes a representation of collections, which are versioned containers of references to concepts and mappings. Note that sources are used to actually author concepts and mappings, whereas collections are used to organize existing concepts and mappings into useful logical groupings, such as a diabetes value set or a Community Maternal-Child Starter Set.

Collections reference concepts and mappings by combining one or more expressions that, when evaluated, result in concepts and mappings. A reference may be “static” or “dynamic”:

  • static - A static expression will always resolve to the same resource version

  • dynamic - A dynamic expression may resolve to different resources or resource versions

In OCL, a collection is used to represent a FHIR ValueSet. “Dynamic” and “static” are closely related to the idea of “extensional” and “intensional” value sets:

  • extensional - Extensional value sets explicitly state each member of the value set (e.g. a list of concept codes)

  • intensional - Intensional value sets define a set of properties that are evaluated (or “expanded”) to determine the value set members

References Syntax

The full references syntax that is supported for references is specified in the :doc:$resolveReference operation documentation</oclapi/apireference/resolveReference>

Reference Evaluation Logic

For a detailed explanation of how collection references are evaluated — including the evaluation pipeline, cascade parameters, transforms, include/exclude processing, and expansion version tracking — see Collection Reference Evaluation Logic.

Implementation Considerations

  • Collections may contain concepts that share the same code, which means that to ensure unique identification of a concept, the owner and source must also be included. Ideally, the API can support use of only the concept ID if the ID is unique within the collection, and it would always support the fully specified form. Here are examples of using the fully specified owner, repository and ID to reference a concept within a collection: * /orgs/CIEL/collections/DiabetesStarterSet/concepts/CIEL:CIEL:1234/ * /orgs/CIEL/collections/DiabetesStarterSet/concepts/OCL:MaternalHealthCoreDataset:1234/

  • Mapping UUIDs are unique across all of OCL, so mappings can be uniquely identified the same as they are within a source:

    • /orgs/CIEL/collections/DiabetesStarterSet/mappings/kdi03993fkie919u1/

Versioning of collections

  • The current state of a collection’s metadata and all of its referenced resources is referred to as the HEAD. All changes to a collection’s metadata or references are made to the HEAD, and prior collection versions are not affected. The collection HEAD is used when no collection version is otherwise specified in a request. For example, GET /user/collections/MyCollection/ will retrieve the HEAD whereas GET /user/collections/MyCollection/v1.0/ will retrieve the collection version with an ID of “v1.0”.

  • At any time, the current state of a collection may be saved by creating a new collection version (e.g. POST /orgs/:org/collections/:collection/versions/). Metadata and resource references from a specific version of a collection may be retrieved by explicitly stating a version number (e.g. GET /orgs/:org/collections/:collection/:version/ or GET /orgs/:org/collections/:collection/:version/concepts/).

  • Collections versions can be marked as “released” or “retired” to indicate to users how the contents of a collection version are intended to be used. Any number of versions may be marked as “released”.

Future Considerations

  • Collections should support multi-lingual names and descriptions in the future

Get a single collection

  • Get a collection owned by a user or organization, where an optional :collectionVersion is “latest” or a specific ID of a collection version. If :collectionVersion is not provided, HEAD is assumed.

GET /users/:user/collections/:collection/[:collectionVersion/]
GET /orgs/:org/collections/:collection/[:collectionVersion/]
GET /user/collections/:collection/[:collectionVersion/]

  • Parameters (only applicable when including child concepts or mappings in the response)

    • includeConcepts (optional) boolean - set to true to include the concepts owned by this collection in a child attribute named concepts

    • includeMappings (optional) boolean - set to true to include the mappings owned by this collection in a child attribute named mappings

    • includeReferences (optional) boolean - set to true to include the references owned by this collection in a child attribute named references

    • offset (optional) integer - zero-based index of the concepts and mappings to return; default is 0; note that this is only applicable if includeConcepts or includeMappings is set to true

    • updatedSince (optional) datetime - ISO 8601 timestamp (e.g. 2011-11-16T14:26:15Z) that filters the returned concepts and mappings to only those updated after the specified date/time; note that this is only applicable if includeConcepts or includeMappings is set to true

    • includeRetired (optional) boolean - set to true to include retired mappings or concepts in the response; note that this is only applicable if includeConcepts or includeMappings is set to true

    • limit (optional) numeric - set to the maximum number of concepts and mappings to return with the source; note that this is only applicable if includeConcepts or includeMappings is set to true

Response

  • Typical response – with includeMappings, includeConcepts and includeReferences set to false

Status: 200 OK

{
    "type": "Collection",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "id": "Community-MCH",
    "external_id": "",

    "short_code": "Community-MCH",
    "name": "Community-MCH Core Dataset",
    "full_name": "Community Maternal-Child Health Core Dataset",
    "collection_type": "Core Dataset",
    "public_access": "View",
    "supported_locales": "en,es",
    "website": "",
    "description": "",
    "active_concepts": 20,
    "active_mappings": 26,

    "extras": {},

    "owner": "OCL",
    "owner_type": "Organization",
    "owner_url": "/orgs/OCL/",

    "url": "/orgs/OCL/collections/Community-MCH/",
    "versions_url": "/orgs/OCL/collections/Community-MCH/versions/",
    "concepts_url": "/orgs/OCL/collections/Community-MCH/concepts/",
    "mappings_url": "/orgs/OCL/collections/Community-MCH/mappings/",

    "versions": 4,

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

  • If includeConcepts, includeMappings or includeReferences parameters are set to true, collection details remain the same as above with the addition of concepts, mappings, and/or references attributes that include JSON lists of the results.

Status: 200 OK

{
   "type": "Collection",
   ...  # Collection details included here

   "concepts": [
      ...      # List of concept results included here
   ],

   "mappings": [
      ...      # List of mapping results included here
   ],

   "references": [
      ...      # List of references in the collection
   ]
}

List all collections for a specific user or organization

  • List collections owned by a user or organization

GET /users/:user/collections/
GET /orgs/:org/collections/
GET /user/collections/

  • Parameters

    • q (optional) string - Search criteria (searches across: “name”, “full_name” and “description”)

    • sortAsc/sortDesc (optional) string - Sort the results along one of these fields: “bestMatch” (default), “name”, “last_update”

    • collection_type (optional) string - Filter results to a particular collection type, e.g. “Subset”, “Value Set”. Known issue: This type cannot have spaces in it.

    • locale (optional) string - Filter results to the ones that include a particular locale in their supported locales, e.g. “en”, “fr”.

    • contains (optional) string - Filter results to collections that contain a referenced to the specified relative URL for a concept version or mapping version, e.g. /orgs/MOH/sources/HMIS-Indicators/concepts/HIV01-01/5a120687f7dccb0064ee8d2f/

    • customValidationSchema (optional) string - Filter results to a given validationSchema, e.g. “OpenMRS”

    • canonicalUrl (optional) string - Filter results by canonical URL

    • allVersions (optional) boolean - Set to true to include all collection versions in results (default behavior only returns HEAD versions)

Response

Status: 200 OK

[
    {
        "id": "Community-MCH",
        "name": "Community-MCH Core Dataset",
        "url": "/orgs/OCL/collections/Community-MCH/",
        "owner": "OCL",
        "owner_type": "Organization",
        "owner_url": "/orgs/OCL/"
    }
]

List all collections for all of a user’s organizations

GET /users/:user/orgs/collections/
GET /user/orgs/collections/

  • Notes

    • Private collections owned by the organization are only returned for users that are members of the organization

  • Parameters

    • q (optional) string - Search criteria (search across: “name”, “full_name” and “description”)

    • sortAsc/sortDesc (optional) string - Sort results on one of the following fields: “best_match” (default), “last_update”, “name”

    • sourceType (optional) string - Filter results to a given source type, e.g. “dictionary”, “reference”

    • locale (optional) string - Filter results to those with a given locale in their supported_locales, e.g. “en”, “fr”

    • customValidationSchema (optional) string - Filter results to a given validationSchema, e.g. “OpenMRS”

    • canonicalUrl (optional) string - Filter results by canonical URL

    • allVersions (optional) boolean - Set to true to include all collection versions in results (default behavior only returns HEAD versions)

Response

Status: 200 OK

[
    {
        "short_code": "ICD-10-2010",
        "name": "ICD-10-WHO 2010",
        "url": "/orgs/WHO/collections/ICD-10-2010/",
        "owner": "WHO",
        "owner_type": "Organization",
        "owner_url": "/orgs/WHO/"
    }
]

List all public collections

  • Use the /collections/ endpoint to list or search public collections across users and organizations

GET /collections/

  • Parameters

    • q (optional) string - Search criteria (searches across: “name”, “full_name” and “description”)

    • sortAsc/sortDesc (optional) string - Sort the results along one of these fields: “name”, “last_update” (default)

    • collection_type (optional) string - Filter results to a particular collection type, e.g. “Subset”, “Value Set”

    • locale (optional) string - Filter results down to the ones that include a particular locale in their supported locales, e.g. “en”, “fr”.

    • contains (optional) string - Filter results to collections that contain a referenced to the specified relative URL for a concept version or mapping version, e.g. /orgs/MOH/sources/HMIS-Indicators/concepts/HIV01-01/5a120687f7dccb0064ee8d2f/

    • customValidationSchema (optional) string - Filter results to a given validationSchema, e.g. “OpenMRS”

    • canonicalUrl (optional) string - Filter results by canonical URL

    • allVersions (optional) boolean - Set to true to include all collection versions in results (default behavior only returns HEAD versions)

Response

Status: 200 OK

[
    {
        "id": "Community-MCH",
        "name": "Community-MCH Core Dataset",
        "url": "/orgs/OCL/collections/Community-MCH/",
        "owner": "OCL",
        "owner_type": "Organization",
        "owner_url": "/orgs/OCL/"
    }
]

Create collection

  • Create new collection owned by the authenticated user or an organization

POST /user/collections/
POST /orgs/:org/collections/

  • Notes

    • “id” is automatically set based on the value of “short_code” and these cannot be modified after the collection has been created

    • The collection “id” must be unique within a specific owner’s sources and collections - meaning a collection “id” may be reused by other users and organizations

    • An authenticated user must be an administrator of the organization to create a new source within that organization

  • Input

    • short_code (required) string - mnemonic used to identify the collection in the URL (usually an acronym e.g. Community-MCH)

    • external_id (optional) string - external ID used for import/export

    • name (required) string - Commonly used name for the collection

    • full_name (optional) string - fully specified name of the collection; automatically set to the value of “name” if blank

    • collection_type (optional) string - Collection type descriptor

    • public_access (optional) string - “View” (default), “Edit”, “None”

    • preferred_source (optional) string - Preferred Collection Source

    • supported_locales (optional) string - comma-separated list of 2-letter language codes supported by the collection (e.g. “en,es,sw”); default is “en”

    • website (optional) string - website for more information on the collection

    • description (optional) string - description of the collection

    • extras (optional) json dictionary - additional metadata for the resource

{
    "short_code": "Community-MCH",
    "name": "Community-MCH Core Dataset",
    "full_name": "Community Maternal-Child Health Core Dataset",
    "collection_type": "Core Dataset",
    "preferred_source": "CIEL",
    "public_access": "View",
    "supported_locales": "en,es"
}

Response

  • Status: 201 Created

  • Location: http://api.openconceptlab.com/OCL/collections/Community-MCH/

{
    "type": "Collection",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "id": "Community-MCH",
    "external_id": "",

    "short_code": "Community-MCH",
    "name": "Community-MCH Core Dataset",
    "full_name": "Community Maternal-Child Health Core Dataset",
    "collection_type": "Core Dataset",
    "public_access": "View",
    "supported_locales": "en,es",
    "website": "",
    "description": "",
    "preferred_source": "CIEL",

    "extras": {},

    "owner": "OCL",
    "owner_type": "Organization",
    "owner_url": "/orgs/OCL/",

    "url": "/orgs/OCL/collections/Community-MCH/",
    "versions_url": "/orgs/OCL/collections/Community-MCH/versions/",
    "concepts_url": "/orgs/OCL/collections/Community-MCH/concepts/",
    "mappings_url": "/orgs/OCL/collections/Community-MCH/mappings/",

    "versions": 1,

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-01-14T04:33:35Z",
    "updated_by": "johndoe"
}

Edit collection

  • Partial update of a collection owned by the authenticated user or an organization

POST /user/collections/:collection/
POST /orgs/:org/collections/:collection/

  • Notes

    • The “id” and “short_code” of the collection cannot be updated after it has been created

  • Input

    • external_id (optional) string - external ID used for import/export

    • name (optional) string - Commonly used name for the collection

    • full_name (optional) string - fully specified name of the collection; automatically set to the value of “name” if blank

    • collection_type (optional) string - Collection type descriptor

    • public_access (optional) string - “View” (default), “Edit”, “None”

    • supported_locales (optional) string - comma-separated list of 2-letter language codes supported by the collection (e.g. “en,es,sw”); default is “en”

    • website (optional) string - website for more information on the collection

    • description (optional) string - description of the collection

    • extras (optional) json dictionary - additional metadata for the resource

{
    "name": "Community-MCH Core Dataset",
    "full_name": "Community Maternal-Child Health Core Dataset",
    "public_access": "View",
    "supported_locales": "en,es"
}

Response

  • Status: 200 OK

  • Returns the detailed JSON representation of the updated collection - same as GET /user/collections/:collection/

Deactivate a collection

  • Deactivate the specified collection owned by the authenticated user or by an organization

DELETE /user/collections/:collection/
DELETE /orgs/:org/collections/:collection/

  • Notes

    • This only deactivates the collection using an internal flag. This effectively hides the organization and any data or metadata it owns, but does not delete it from the system.

    • Authentication information for a user with administrative access to the collection must be passed with the request. E.g. curl -u "username" "/users/johndoe/"

Response

  • Status: 204 No Content

Get single version of a collection

  • Get a single version of a collection, where :version is a collection version ID or “latest”

GET /user/collections/:collection/versions/:version/
GET /users/:user/collections/:collection/versions/:version/
GET /orgs/:org/collections/:collection/versions/:version/

  • Notes

    • “latest” is a magic keyword which automatically refers to the most recent released collection version

Response

  • Status: 200 OK

{
    "type": "Collection Version",
    "id": "1.2",
    "external_id": "",
    "released": "false",
    "description": "Released a new iteration",

    "url": "/orgs/OCL/collections/Community-MCH/1.2/",
    "collection_url": "/orgs/OCL/collections/Community-MCH/",
    "previous_version_url": "/orgs/OCL/collections/Community-MCH/1.1/",
    "root_version_url": "/orgs/OCL/collections/Community-MCH/1.0/",

    "extras": {},

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2010-02-14T04:33:35Z",
    "updated_by": "johndoe",

    "collection": {
       
    }
}

List all versions of a collection

  • List all versions of a collection

GET /user/collections/:collection/versions/
GET /users/:user/collections/:collection/versions/
GET /orgs/:org/collections/:collection/versions/

  • Parameters

    • released (optional) boolean - set to true to include only collection versions with the released attribute set to true

    • processing (optional) boolean - set to true to include only collection versions with the _ocl_processing attribute set to true

Response

  • Status: 200 OK

[
    {
        "id": "1.1",
        "released": "false",
        "url": "/orgs/OCL/collections/Community-MCH/1.1/"
    }
]

Create new version of a collection

  • Create new version of a collection

POST /user/collections/:collection/versions/
POST /users/:user/collections/:collection/versions/
POST /orgs/:org/collections/:collection/versions/

  • Notes

    • “id” cannot be changed after a collection version is created

    • “root_version_url” is set automatically by the API to the first user-generated collection version. If the collection version being created is the first collection version, then “root_version_url” is set to itself.

    • “previous_version_url” is set automatically by the API to the prior collection version, or it is set to an empty string if this is the first collection version.

  • Inputs

    • id (required) string

    • released (optional) string - “true” or “false”

    • description (optional) string

    • external_id (optional) string

    • extras (optional) JSON dictionary

{
    "id": "1.5",
    "released": "false",
    "description": "new version",
    "external_id": "v1.5",
    "extras": { "myattr": "myvalue" }
}

Response

  • Status: 201 Created

  • Location: http://api.openconceptlab.com/OCL/collections/Community-MCH/2.5/

{
    "type": "Collection Version",
    "id": "1.5",
    "external_id": "",
    "released": "false",
    "description": "new version",

    "url": "/orgs/OCL/collections/Community-MCH/1.5/",
    "collection_url": "/orgs/OCL/collections/Community-MCH/",
    "previous_version_url": "/orgs/OCL/collections/Community-MCH/1.4/",
    "root_version_url": "/orgs/OCL/collections/Community-MCH/1.0/",

    "extras": {},

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-01-14T04:33:35Z",
    "updated_by": "johndoe",

    "collection": {
        
    }
}

Edit a collection version

  • Edit a collection version owned by a user or organization

POST /user/collections/:collection/versions/:version/
POST /users/:user/collections/:collection/versions/:version/
POST /orgs/:org/collections/:collection/versions/:version/

  • Notes

    • “id” cannot be changed after a version is created

  • Inputs

    • released (optional) string - “true” or “false”

    • description (optional) string

    • external_id (optional) string

    • extras (optional) JSON dictionary

{
    "released": "true",
    "description": "updated version description"
}

Response

  • Status: 200 OK

{
    "type": "Collection Version",
    "id": "1.5",
    "external_id": "",
    "released": "false",
    "description": "new version",

    "url": "/orgs/OCL/collections/Community-MCH/1.5/",
    "collection_url": "/orgs/OCL/collections/Community-MCH/",
    "previous_version_url": "/orgs/OCL/collections/Community-MCH/1.4/",
    "root_version_url": "/orgs/OCL/collections/Community-MCH/1.0/",

    "extras": {},

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-01-14T04:33:35Z",
    "updated_by": "johndoe",

    "collection": {
        
    }
}

Deactivate a collection version

  • Deactivate a collection version owned by a user or organization

DELETE /user/collections/:collection/versions/:version/
DELETE /users/:user/collections/:collection/versions/:version/
DELETE /orgs/:org/collections/:collection/versions/:version/

  • Notes

    • A deactivated version can no longer be accessed

    • Authentication information for a user with administrative access to the collection must be passed with the request. E.g. curl -u "username" "/users/johndoe/"

Response

  • Status: 204 No Content

Retrieve and clear processing flag on a collection version

Retrieve processing flag on a collection version

GET /orgs/:org/collections/:collection/:version/processing/

Response

  • Processing flag value: True or False

Clear processing flag on a collection version

POST /orgs/:org/collections/:collection/:version/processing/

Response

  • Status: 200 OK

List all references in a collection

  • List all references in a collection

GET /orgs/:org/collections/:collection/[:collectionVersion/]references/
GET /users/:user/collections/:collection/[:collectionVersion/]references/
GET /user/collections/:collection/[:collectionVersion/]references/

  • Notes

    • “expression” may be any API request that results in a list of concepts or mappings

Example

GET /orgs/KenyaMOH/collections/KenyaEMR/v1.1/references/

Response

  • Status: 200 OK

[
    {
        "expression": "/orgs/CIEL/sources/CIEL/concepts/"
    },
    {
        "expression": "/orgs/CIEL/sources/CIEL/mappings/"
    },
    {
        "expression": "/orgs/KenyaMOH/sources/LocalConcepts/concepts/123/"
    },
    {
        "expression": "/orgs/KenyaMOH/sources/LocalConcepts/concepts/123/mappings/"
    }
]

Add a reference to a collection

PUT /orgs/:org/collections/:collection/references/
PUT /users/:user/collections/:collection/references/
PUT /user/collections/:collection/references/

  • Input

    • expressions (required) string - URLs of the references to add

    • uri (optional) string - URL of source/ collection from which to copy concepts

    • concepts (optional) lists of strings - URLs of the concepts to add or * when used with uri to add all concepts from the collection/ source

    • mappings (optional) lists of strings - URLs of the mappings to add or * when used with uri to add all mappings from the collection/ source

    • search_term (optional) - Used with uri to filter concepts/ mappings to add by search term

  • Query Parameters

    • async (optional) - set to true to process the request asynchronously;

    • cascade (optional) (default=none) - Controls whether related mappings and concepts are automatically included. Accepts a string or a JSON object:

      • none (default): Do not cascade to any mappings or concepts

      • sourcemappings: Cascade to mappings in the same source where the concept is the from-concept

      • sourcetoconcepts: Cascade to mappings AND their target concepts in the same source

      • JSON object: For extended cascade control with parameters like cascade_levels, map_types, reverse, cascade_hierarchy, etc. See Cascade parameters for the full reference.

      • Note: Additional cascade documentation: https://docs.openconceptlab.org/en/latest/oclapi/apireference/cascade.html

Example

  • PUT /orgs/KenyaMOH/collections/KenyaEMR/references/?cascade=sourcemappings

{
    "data": {
        "expressions": ["/orgs/WHO/sources/ICD-10/concepts/A15.1/"]
    }
}

Response

  • Status: 200 OK

  • Information, warning or error messages concerning addition of reference(s) are returned in a list

[
  {
    "message": "Added the latest versions of concept to the collection. Future updates will not be added automatically.",
    "added": true,
    "expression": "/users/molgun/sources/HSTP-Indicatorsubhea/concepts/C1.1.1.2-gazmuk/58a19a1d46d2b100166d287f/"
  },
  {
    "message": [
      "Concept or Mapping reference name must be unique in a collection."
    ],
    "added": false,
    "expression": "/users/molgun/sources/HSTP-Indicatorsubhea/concepts/C1.1.1.2-gazmuk/"
  }
]

Delete a reference from a collection

DELETE /orgs/:org/collections/:collection/references/
DELETE /users/:user/collections/:collection/references/
DELETE /user/collections/:collection/references/

  • Input

    • references (required). One of;

      • string array - Version URLs of the references to remove

      • * - Delete all references from the collection

  • Query Parameters

    • cascade (optional) (default=none) string - It takes none, sourcemappings, or sourcetoconcepts as a value.

Example

  • DELETE /orgs/KenyaMOH/collections/KenyaEMR/references/

{
    "references": ["/orgs/WHO/sources/ICD-10/concepts/A15.1/589193e44ac5f4030b80bdb0/"]
}

Response

  • Status: 200 OK – indicates that the expression was deleted

  • Status: 404 Not Found – indicates that the expression was not found in the collection

Get single concept from a collection

  • Get a single concept from a collection, where an optional :collectionVersion is “latest” or a collection version ID.

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/

  • Notes

    • The results are identical to fetching a concept directly from a source (i.e. GET /user/sources/MySource/concepts/123/), with two exceptions:

      • The concept mappings (both direct and inverse) are pulled from the collection, not from the original source.

      • Additional metadata are added to the concept that point back to the collection from which it is referenced (e.g. concept_reference_url, collection_url, collection, collection_owner, collection_owner_type).

    • :concept is of the form concept_id (e.g. “A15.1”) or owner:source[sourceVersion]:concept_id (e.g. “WHO:ICD-10:A15.1”). The simple form may only be used if the concept ID is unique within the collection, otherwise it results in an error.

    • The version of the concept returned is determined by the expression that added this concept to the collection

Example Request

  • Get a single concept from a collection with a simple concept ID

GET /orgs/OCL/collections/Community-MCH/concepts/1234/

  • Get a single concept from a collection with a fully specified concept ID

GET /orgs/OCL/collections/Community-MCH/concepts/CIEL:CIEL:1234/

Example

GET /orgs/OCL/collections/Community-MCH/concepts/WHO:ICD-10:A15.1/

Response

Status: 200 OK

{
    "concept_reference_url": "/orgs/OCL/collections/Community-MCH/concepts/WHO:ICD-10:A15.1/",
    "collection_url": "/orgs/OCL/collections/Community-MCH/",
    "collection": "Community-MCH",
    "collection_owner": "OCL",
    "collection_owner_type": "Organization",

    "type": "Concept",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "id": "A15.1",
    "external_id": "19jf93jf9j39fii399du9393",

    "concept_class": "Diagnosis",
    "datatype": "None",
    "retired": false,

    "display_name": "Tuberculosis of lung, confirmed by culture only",
    "display_locale": "en",

    "names": [
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_id": "1fddfenkcineh9",
            "name": "Tuberculosis of lung, confirmed by culture only",
            "locale": "en",
            "locale_preferred": "true",
            "name_type": "None"
        },
        {
            "type": "ConceptName",
            "uuid": "90jmcna4-lkdhf78",
            "external_id": "12345677",
            "name": "Tuberculose pulmonaire, confirmée par culture seulement",
            "locale": "fr",
            "locale_preferred": "true",
            "name_type": "None"
        }
    ],
    "descriptions": [
        {
            "type": "ConceptDescription",
            "uuid": "aY873Hbmkdi09jeh",
            "external_id": "abcdefghijklmnopqrstuvwxyz",
            "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
            "locale": "en",
            "locale_preferred": "true",
            "description_type": "None"
        }
    ],
    "mappings": [
        {
            "type": "Mapping",
            "uuid": "8jf8j-39fnnkdked",
            "external_id": "a9d93ffjjen9dnfekd9",
            "retired": "false",

            "map_type": "Same As",

            "from_source_owner": "WHO",
            "from_source_owner_type": "Organization",
            "from_source_name": "ICD-10-2010",
            "from_concept_code": "A15.1",
            "from_concept_code": "Tuberculosis of lung, confirmed by culture only",
            "from_source_url": "/orgs/WHO/sources/ICD-10-2010/",
            "from_concept_url": "/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/",

            "to_source_owner": "IHTSDO",
            "to_source_owner_type": "Organization",
            "to_source_name": "SNOMED",
            "to_concept_code": "154283005",
            "to_concept_name": "Pulmonary Tuberculosis",
            "to_source_url": "/orgs/IHTSDO/sources/SNOMED/",

            "source": "ICD-10-2010",
            "owner": "WHO",
            "owner_type": "Organization",

            "url": "/orgs/WHO/sources/ICD-10-2010/mappings/8jf8j-39fnnkdked/",

            "created_on": "2008-01-14T04:33:35Z",
            "created_by": "johndoe",
            "updated_on": "2008-02-18T09:10:16Z",
            "updated_by": "johndoe"
        }
    ],

    "extras": {
        "parent": "A15"
    },

    "source": "ICD-10",
    "owner": "WHO",
    "owner_type": "Organization",

    "version": "abc345jf9fj",

    "url": "/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/",
    "version_url": "/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/abc345jf9fj/",
    "source_url": "/orgs/WHO/sources/ICD-10-2010/",
    "owner_url": "/orgs/WHO/",
    "mappings_url": "/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/mappings/",
    "extras_url": "/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/extras/",

    "versions": 9,

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

List concepts referenced in a collection

  • List concepts referenced in a collection, where an optional :collectionVersion is “latest” or a collection version ID

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/
GET /user/collections/:collection/[:collectionVersion/]concepts/

  • Parameters

    • verbose (optional) string - default is false; set to true to return full concept details instead of the summary

    • q (optional) string - Search criteria

    • sortAsc/sortDesc (optional) string - sort results according to one of the following attributes: “bestMatch” (deafult), “lastUpdate”, “name”, “id”, “datatype”, “conceptClass”

    • conceptClass (optional) string - filter results to those within a particular concept class, e.g. “laboratory procedure”

    • datatype (optional) string

    • locale (optional) string - filter results to those with a name for the given locale, e.g. “en”, “fr”

    • includeRetired (optional) integer - 1 or 0, default 0

    • mapcode (optional) string - e.g. IHTSDO:SNOMED-CT:123455

    • includeMappings (optional) string - default is “false” (even if “verbose” is set to “true”); set to “true” to return direct mappings contained in this collection

    • includeInverseMappings (optional) string - default is “false” (even if “verbose” is set to “true”); set to “true” to return inverse mappings contained in this collection

  • Notes

    • The results are identical to listing concepts directly from a source (i.e. GET /user/sources/MySource/concepts/), with the exception that additional metadata are added that point back to the collection from which they are referenced (e.g. concept_reference_url). Note that “concept_reference_url” always uses the fully specified format (e.g. “WHO:ICD-10:A15.1”).

    • If verbose is set to true, results are the same as fetching a single concept

Examples

  • List concepts in the latest version of a collection

GET /orgs/CIEL/collections/StarterSet/concepts/

  • List concepts in a specific version of a collection

GET /orgs/CIEL/collections/StarterSet/v1.0/concepts/

Example

GET /orgs/CIEL/collections/StarterSet/concepts/

Response

Status: 200 OK

[
    {
        "id": "A15.1",
        "concept_class": "Diagnosis",
        "datatype": "None",
        "retired": false,
        "source": "ICD-10",
        "owner": "WHO",
        "owner_type": "Organization",
        "owner_url": "/orgs/WHO/sources/ICD-10/",
        "display_name": "Tuberculosis of lung, confirmed by culture only",
        "display_locale": "en",
        "version": "abc345jf9fj",
        "url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/",
        "version_url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/",
        "concept_reference_url": "/orgs/CIEL/collections/StarterSet/concepts/WHO:ICD-10:A15.1"
    }
]

Concept subresource Requests

  • List concept names – just pull from the concept; in the future, collections may allow restricting which names are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/names/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/names/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/names/

  • Get a single concept name – just pull from the concept; in the future, collections may allow restricting which names are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/names/:name/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/names/:name/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/names/:name/

  • List concept descriptions – just pull from the concept; in the future, collections may allow restricting which descriptions are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/

  • Get a single concept description – just pull from the concept; in the future, collections may allow restricting which descriptions are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/:description/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/:description/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/descriptions/:description/

  • List extras – just pull from the concept; in the future, collections may allow restricting which extras are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/extras/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/extras/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/extras/

  • Get a single extra – just pull from the concept; in the future, collections may allow restricting which extras are present – is :conceptVersion dictated by the reference?

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/extras/:field_name/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/extras/:field_name/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/extras/:field_name/

Get a single mapping from a collection

  • Get a single mapping from a collection owned by a user or organization

GET /orgs/:org/collections/:collection/[:collectionVersion/]mappings/:mapping/
GET /users/:user/collections/:collection/[:collectionVersion/]mappings/:mapping/
GET /user/collections/:collection/[:collectionVersion/]mappings/:mapping/

  • Notes

    • The results are identical to fetching a mapping directly from a source (i.e. GET /user/sources/MySource/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/), with one exception:

      • Additional metadata are added to the mapping that point back to the collection from which it is referenced (e.g. mapping_reference_url, collection_url, collection, collection_owner, collection_owner_type).

    • :mapping is the same identifier that is used when requesting a mapping from a source, because the mapping “uuid” is guaranteed unique across OCL.

Example

GET /orgs/MyOrg/collections/MyCollection/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/

Response

  • Status: 200 OK

{
    "mapping_reference_url": "/orgs/MyOrg/collections/MyCollection/mappings/WHO:ICD-10:A15.1/",
    "collection_url": "/orgs/MyOrg/collections/MyCollection/",
    "collection": "MyCollection",
    "collection_owner": "MyOrg",
    "collection_owner_type": "Organization",

    "type": "Mapping",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "external_id": "a9d93ffjjen9dnfekd9",
    "retired": "false",

    "map_type": "Same As",

    "from_source_owner": "Regenstrief",
    "from_source_owner_type": "Organization",
    "from_source_name": "loinc2",
    "from_concept_code": "32700-7",
    "from_concept_name": "Malarial Smear",
    "from_source_url": "/orgs/Regenstrief/sources/loinc2/",
    "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",

    "to_source_owner": "WHO",
    "to_source_owner_type": "Organization",
    "to_source_name": "ICPC-2",
    "to_concept_code": "A73",
    "to_concept_name": "Malaria",
    "to_source_url": "/orgs/WHO/sources/ICPC-2/",

    "source": "loinc2",
    "owner": "Regenstrief",
    "owner_type": "Organization",

    "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",

    "extras": {},

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

List mappings for a single concept that are contained in the collection

  • List mappings for a single concept that are contained in the collection

GET /orgs/:org/collections/:collection/[:collectionVersion/]concepts/:concept/mappings/
GET /users/:user/collections/:collection/[:collectionVersion/]concepts/:concept/mappings/
GET /user/collections/:collection/[:collectionVersion/]concepts/:concept/mappings/

  • Notes

    • Only mappings that are referenced in the collection are returned.

    • The results are identical to requesting mappings from a source (e.g. GET /orgs/CIEL/sources/CIEL/mappings/), with the exception that an additional metadata field is added, “mapping_reference_url”, to point back to the mapping’s URL within the collection.

    • If verbose is set to true, the results look the same as fetching a single concept (refer to documentation above).

  • Parameters

    • verbose (optional) string - default is “false”; set to “true” to return full mapping details instead of the summary

    • includeRetired (optional) string - default - “false”; set to “true” to return retired mappings

    • includeInverseMappings (optional) string - default is “false”; set to “true” to return inverse mappings

Example

GET /orgs/MyOrg/collections/MyCollection/concepts/Regenstrief:LOINC2:32700-7/mappings/

Response

  • Status: 200 OK

[
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
        "mapping_reference_url": "/orgs/MyOrg/collections/MyCollection/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/"
    },
    {
        "map_type": "Narrower Than",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_code": "A73",
        "to_concept_name": "Malaria",
        "to_source_code": "ICPC-2",
        "url": "/orgs/Regenstrief/sources/loinc2/def3fe-c2cc-11de-8d13-asdf9393930/",
        "mapping_reference_url": "/orgs/MyOrg/collections/MyCollection/mappings/def3fe-c2cc-11de-8d13-asdf9393930/"
    }
]

List mappings in a collection

  • List mappings in a collection

GET /orgs/:org/collections/:collection/[:collectionVersion/]mappings/
GET /users/:user/collections/:collection/[:collectionVersion/]mappings/
GET /user/collections/:collection/[:collectionVersion/]mappings/

  • Notes

    • The results are identical to requesting mappings from a source (e.g. GET /orgs/CIEL/sources/CIEL/mappings/), with the exception that an additional metadata field is added, “mapping_reference_url”, to point back to the mapping’s URL within the collection.

    • If verbose is set to true, the results look the same as fetching a single concept (refer to documentation above).

  • Parameters

    • verbose (optional) string - default is “false”; set to “true” to return full mapping details instead of the summary

    • includeRetired (optional) string - default - “false”; set to “true” to return retired mappings

    • includeInverseMappings (optional) string - default is “false”; set to “true” to return inverse mappings

Example

GET /orgs/MyOrg/collections/MyCollection/mappings/

Response

  • Status: 200 OK

[
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
        "mapping_reference_url": "/orgs/MyOrg/collections/MyCollection/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/"
    },
    {
        "map_type": "Narrower Than",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_code": "A73",
        "to_concept_name": "Malaria",
        "to_source_code": "ICPC-2",
        "url": "/orgs/Regenstrief/sources/loinc2/def3fe-c2cc-11de-8d13-asdf9393930/",
        "mapping_reference_url": "/orgs/MyOrg/collections/MyCollection/mappings/def3fe-c2cc-11de-8d13-asdf9393930/"
    }
]

Get collection summary

  • Get a summary of a collection’s contents

GET /user/collections/:collection/summary/
GET /users/:user/collections/:collection/summary/
GET /orgs/:org/collections/:collection/summary/

Response

  • Status: 200 OK

{
    "id": "MyCollection",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "active_concepts": 100,
    "active_mappings": 50,
    "active_references": 25,
    "versions": 2,
    "expansions": 1
}

Get verbose collection summary

  • Get a detailed summary of a collection including distributions of concepts, mappings, versions, and references

GET /user/collections/:collection/summary/?verbose=true
GET /users/:user/collections/:collection/summary/?verbose=true
GET /orgs/:org/collections/:collection/summary/?verbose=true

Response

  • Status: 200 OK

{
    "id": "MyCollection",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "concepts": {
        "active": 100,
        "retired": 3,
        "concept_class": [["Diagnosis", 40], ["Finding", 35], ["Procedure", 25]],
        "datatype": [["Coded", 60], ["Text", 30], ["Numeric", 10]],
        "locale": [["en", 100], ["fr", 50]],
        "name_type": [["FULLY_SPECIFIED", 100], ["SHORT", 40]],
        "contributors": [["johndoe", 70], ["janedoe", 30]]
    },
    "mappings": {
        "active": 50,
        "retired": 1,
        "map_type": [["SAME-AS", 30], ["NARROWER-THAN", 15], ["BROADER-THAN", 5]],
        "contributors": [["johndoe", 35], ["janedoe", 15]]
    },
    "versions": {
        "total": 2,
        "released": 1
    },
    "references": {
        "include": 25,
        "exclude": 0,
        "concepts": 18,
        "mappings": 7,
        "total": 25
    },
    "expansions": 1
}

Get collection summary distribution by field

  • Get the distribution of a specific field or set of fields from a collection summary. Multiple fields can be requested as a comma-separated list.

GET /orgs/:org/collections/:collection/summary/?verbose=true&distribution=concept_class
GET /orgs/:org/collections/:collection/summary/?verbose=true&distribution=concept_class,datatype,map_type

  • Parameters

    • verbose (required) string - must be set to “true”

    • distribution (required) string - comma-separated list of fields to retrieve. Supported values: concept_class, datatype, name_type, name_locale, map_type

Response

  • Status: 200 OK

{
    "id": "MyCollection",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "distribution": {
        "concept_class": [
            {"concept_class": "Diagnosis", "count": 40},
            {"concept_class": "Finding", "count": 35},
            {"concept_class": "Procedure", "count": 25}
        ]
    }
}

Get collection version summary

  • Get a summary for a specific version of a collection or the latest released version

GET /user/collections/:collection/:version/summary/
GET /users/:user/collections/:collection/:version/summary/
GET /orgs/:org/collections/:collection/:version/summary/
GET /orgs/:org/collections/:collection/latest/summary/

  • Notes

    • The latest keyword returns the summary for the most recently created released version

    • Supports the same verbose and distribution query parameters as the collection summary

    • Version summaries do not include the versions field

Response

  • Status: 200 OK

{
    "id": "v1.0",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "active_concepts": 100,
    "active_mappings": 50,
    "active_references": 25,
    "expansions": 1
}

Recalculate collection summary counts

  • Trigger a recalculation of a collection’s concept and mapping counts. Requires edit access to the collection.

PUT /user/collections/:collection/summary/
PUT /users/:user/collections/:collection/summary/
PUT /orgs/:org/collections/:collection/summary/

Response

  • Status: 202 Accepted

Search and Filter Behavior

  • Text Search (e.g. q=criteria) - NOTE: Plus-sign (+) indicates relative relevancy weight of the term

    • collection.short_code (++++), collection.name (++++), collection.full_name (+++), collection.description (+)

  • Facets

    • locale - collection.supported_locales

    • collection_type - collection.source_type

    • owner - collection.owner

    • ownerType - collection.owner_type

  • Filters

    • ??

  • Sort

    • bestMatch (default) - see search fields above

    • name (Asc/Desc) - collection.name

    • lastUpdate (Asc/Desc) - collection.updated_on

Expression Examples

OCL supports a wide range of reference expressions. For the full syntax, see $resolveReference. For the evaluation pipeline, see Collection Reference Evaluation Logic.

  • Individual concepts:

    • Latest version of a concept: /orgs/:org/sources/:source/concepts/:concept/

    • Specific concept version: /orgs/:org/sources/:source/concepts/:concept/:conceptVersion/

    • Concept from a specific source version: /orgs/:org/sources/:source/:sourceVersion/concepts/:concept/

  • Individual mappings:

    • Latest version of a mapping: /orgs/:org/sources/:source/mappings/:mapping/

    • Specific mapping version: /orgs/:org/sources/:source/mappings/:mapping/:mappingVersion/

  • Bulk expressions:

    • All concepts from a source version: /orgs/:org/sources/:source/:sourceVersion/concepts/

    • All concepts from a collection version: /orgs/:org/collections/:collection/:collectionVersion/concepts/

    • All concepts from HEAD of a source: /orgs/:org/sources/:source/concepts/

  • Filtered expressions:

    • All concepts matching search criteria: /orgs/CIEL/sources/CIEL/concepts/?q=malaria

    • All concepts of a specific class: /orgs/CIEL/sources/CIEL/concepts/?conceptClass=Drug

  • Cascade expressions:

    • All direct mappings for a concept: /orgs/:org/sources/:source/concepts/:concept/ with cascade=sourcemappings

    • Full closure (mappings + target concepts): /orgs/:org/sources/:source/concepts/:concept/ with cascade=sourcetoconcepts