OwS Object Type: codesystem

Description

Objects of type Codesystem hold a set of concepts to either form a networked ontology, a hierachical terminology, a flat vocabulary or a value set as a collection of concepts from other systems. Codesystem objects defined in an OwS document are transformed into a standard format by the OwS compiler which allows to import them into any kind of semantics-aware service (e.g. a CTS2-LE terminology server).

Defined Properties

Property Name	RWDS	Type	Card.	Definition
_name	R	string	1..1	Name of the object. Set when the object is initially defined (see define statement).
_type	R	string	1..1	"codesystem"
oid	RW	string	0/1..1	OID of the code system. Used by OwS as the primary identitfier. May only be omitted if an URN is defined.
uri	RW	string	0/1..1	URN of the code system. Must be given if no OID is provided. Takes the role of the primary identifier in this case.
version	RWD	string	0..1	A code system is globally and univocally identifiable by it's OID/URN and Version. If a code system is uploaded to CTS2-LE that has the same OID/URN and Version as an existing code system, the existing code system is overwritten by the uploaded system. If no value for this property is givem OwS sets the current date (YYYY-MM-DD) as the version.
title	RWD	string	0..1	Human readable title for the code system. If this property is not explicitly set, the codesystem's name will be considered as its title, too.
status	RWD	code	0..1	active | retired | unknown) from FHIR PublicationStatus value set. If no status is given, OwS sets the code system status to "draft" by default.
context	RW	Domain	0..1	Domain context of the code system. If the code system is to be uploaded to CTS2-LE this property must be defined.
description	RW	string	0..*	Description of the code system.
copyright	RW	string	0..1	Copyright notice to be linked with the code system. NOTE: This property is ignored by CTS2-LE as there is no corresponding property within the CTS2 standard information model.
publisher	RW	string	0..1	Information about the publisher of the code system. NOTE: This property is ignored by CTS2-LE as there is no corresponding property within the CTS2 standard information model.
language	RW	string	0..1	CTS2-LE specific: If different language versions of the code system exist, this property given the version of the defined code system. Value shall be an RFC5646 "simple language subtag".
hierarchyMeaning	RW	code	0..1	(grouped-by | is-a | part-of | classified-with) from FHIR CodeSystemHierarchyMeaning value set.
encoding	RWD	string	0..1	Encoding to be used when the code system is uploaded to a terminology server. If no encoding is defined, OwS uses "UTF-8" by default.
concepts	RWS	concept	0..*	Concepts within the code system
_temp	RW	string	0..1	for your own disposition; may hold any string value
_ctemp	RW	Object	0..1	for your own displosition; may refer to any type of object

RWDS = Read Access - Write Access - Default Value if not explicitly set - Special Treatment

Using Codesystem Objects for defining Ontologies, Terminologies, Vocabularies and Value Sets

Codesystem objects are used for defining any kind of code system: flat, hierarchical, poly-hierarchical or even networked. A Codesystem object holds a set of Concept objects as its children, with each Concept object holding other Concept objects or linking with other Concept objects (even from other code systems). By this the kinds of relationships among the contained concepts define the flavor of the code system and - depending on the export format - the externalized standard representation. E.g if FHIR DSTU-2 is selected as the export format all Codesystem objects are mapped onto a FHIR ValueSet resource while choosing FHIR STU-3 (or newer) as the export format will either result in a CodeSystem resource (all concepts within the system are defined as part of the system) or a ValueSet resource (all concepts within the system originate from other code systems).

The following subsection sketch examples for the kinds of code systems that can be defined through the Codesystem type.

Flat Vocabulary

define Codesystem ABC {
    define Concept A { }
    define Concept B { }
    define Concept C { }
}

Hierarchical Terminology

define Codesystem ABC {
    define Concept A { 
        define Concept B { }
    }
    define Concept C { }
}

Networked Ontology

define Codesystem ABC {
    define Concept A { 
      --XYZ--> B
    }
    define Concept B { 
      --XYZ--> A
      --XYZ--> C
    }
    define Concept C { 
      --XYZ--> A
    }
}

Value Set

define System EXT = CTS2LE.Systems[OID=(..)]
define Codesystem ABC {
    define Concept A = X@EXT
    define Concept B = Y@EXT
    define Concept C = Z@EXT
}

Using Codesystem Properties

The only property that shall be explicitly set for each Codesystem object is the code system's unique identifier which can either be provided as an OID (property oid) or as an URI (property uri). If neither an OID or an URI is set for a Codesystem object the OwS parser will throw an error when exporting the code system to standard format.

The _name property of a Codesystem object is mainly used for referencing the object within an OwS file. When exported it maps on a (user readable) name element of the target standard (e.g. title in FHIR STU-3).

Using OwS together with CTS2-LE

Code systems defined in OwS that are planned to be imported to the CTS2-LE terminology server shall have a version property and a context property defined:

• within CTS2-LE a code system is unique through its URI/OID together with its version. When referencing a code from an external code system (e.g. for placing a concept into a value set) the code system must be identified through URI/OID and version. The same holds when one wants to delete a code system from CTS2-LE; again URI/OID and version are needed to univocally identify the code system to be deleted.
• CTS2-LE requires every code system to be part of a named group. While groups are displayed as folders in the CTS2-LE Web-GUI, they are more than just a means for structuring sets of code systems; e.g. the cross-terminology search can be restricted to a defined set of groups. When uploading a code system to CTS2LE, the OwS compiler uses the groupname property of the code system's context as the CTS2LE group name.

Both properties may be defined as defaults on a global OwS scope.

Property: language

The language property of a code system sets

• the default language for all other Codesystem properties of type string,
• the default language for all concepts within the code system.

Furthermore a code systems default language influences how OwS sets further defaults. E.g. by default the value of a concept's display property is set to the value of the designation property where the designation's language corresponds to the language of the code system.

Property: concepts

When read from a Codesystem object, the property concepts provides a flat collection of all concepts defined within the code system (attention: This recently only works for Codesystem objects defined in the recent OwS document). Single concepts within that list can be picked through qualifiers, which act as search operators in that respect.

Example: mysystem.concepts[Name=cn1] is equivalent to cn1@mysystem

Example: mysystem.concepts[Level=1] provides a collection of all root-level concepts within the code system "mysystem".

When used in conjunction with the set statement, a flat collection of concepts can be assigned as the 'contentes' of a value set. The example below shows how to define a value set from two existing code systems by just adding the contents of these systems to the newly defined value set:

define Codesystem vs1 {
   set .concepts = othersystem1.concepts
   set .concepts =[mode=append] othersystem2.concepts
}

FHIR Mapping

DSTU-2: Terminology (codesystem)

<?xml version="1.0" encoding="Encoding"?>
<ValueSet xmlns="http://hl7.org/fhir" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ext="http://semantik.fokus.fraunhofer.de/ehealth/fhir-extensions#" xsi:schemaLocation="http://hl7.org/fhir ../fhir-std/spec-v1.0.2/valueset.xsd">
<name value="name"/>
<status value="status"/>
<experimental value="False"/> <!-- value="True" if code system has Silent Name (name starting with an underscore) -->
<publisher value="publisher"/>
<description value="description"/>
<copyright value="copyright"/>
<codeSystem>
<extension url="ext:language">       <valueCode value="Language"/>     </extension>
<extension url="ext:groupName">       <valueString value="context.groupName"/>     </extension>
<extension url="ext:resourceId">       <valueString value="name"/>     </extension>
<system value="urn:oid:oid"/> <!-- if no OID is provided: <system value="uri"/> -->
<version value="version"/>
...
</codeSystem>
</ValueSet>

---

The table below lists the elements defined for the FHIR ValueSet resource which are not used/supported for OwS terminology definitions.

FHIR ValueSet DSTU-2	Reason for not supporting this element
ValueSet/urn	For terminologies CTS2-LE only considers the identifer given within the codeSystem element. This behavior is compliant with FHIR STU-3 and makes sure that terminologies defined using OwS can be exported as DSTU-2 and STU-3 without any need for adapting existing files.
ValueSet/identifer	see above. Only identifiers provided in the codeSystem element are considered for terminology definitions.
ValueSet/version	see above. The version element is part of the terminology's unique identifer and therefore only the version given within the codeSystem element is considered.
ValueSet/contact	will be supported in one of the next updates to the OwS interpreter.
ValueSet/date	will be supported in one of the next updates to the OwS interpreter.
ValueSet/lockedDate	This element is no longer part of the FHIR resource for terminology definitions and therefore not supported by OwS.
ValueSet/useContext	will be supported in one of the next updates to the OwS interpreter.
ValueSet/immutable	This element is no longer part of the FHIR resource for terminology definitions and therefore not supported by OwS.
ValueSet/requirements	will be supported in one of the next updates to the OwS interpreter.
ValueSet/extensible	This element is no longer part of the FHIR resource for terminology definitions and therefore not supported by OwS.
ValueSet/codeSystem/caseSensitive	From our understanding of codes as unique identifiers for concepts, two concepts are identical only if they are part of the same version of the same code system and have the same code. This shall be interpreted as strict as possible and therefor CTS2-LE and OwS perform case sensitive code comparison only.