SDC4 Type Reference

Generated from the reference model (src/rm/sdc4/sdc4.xsd, namespace https://semanticdatacharter.com/ns/sdc4/), the SDCStudio component models and the Component Wizard's type grid by scripts/generate_type_reference.py. It is not edited by hand: a test fails when the schema, the models or the grid change without regenerating it.

How to read it. A type has three names: the label on the Component Wizard's grid, the component model in SDCStudio, and the complex type in the published XSD. Each entry gives what the type is for, what a record carries (In the record: the schema elements, in the schema's own words), and what you set when you create the component (What you set: the model fields, in the wizard's own words). The common elements and fields that every component carries are listed once, below the hierarchy.

The hierarchy

The abstract bases carry the shared elements and fields: XdAny for every value type, XdOrdered for anything with an order (ordinals, dates, quantities), XdQuantified for anything with a magnitude. Cluster and the contextual types sit beside them on Common.

graph TD
  Common --> XdAny
  XdAny --> XdOrdered
  XdOrdered --> XdQuantified
  XdAny --> XdBoolean
  XdAny --> XdLink
  XdAny --> XdString
  XdAny --> XdToken
  XdAny --> XdFile
  XdOrdered --> XdOrdinal
  XdQuantified --> XdCount
  XdQuantified --> XdQuantity
  XdQuantified --> XdFloat
  XdQuantified --> XdDouble
  XdOrdered --> XdTemporal
  XdAny --> XdInterval
  XdAny --> ReferenceRange
  XdAny --> SimpleReferenceRange
  XdAny --> Units
  XdAny --> XdBooleanList
  XdAny --> XdStringList
  XdAny --> XdTokenList
  XdQuantified --> XdDecimalList
  XdQuantified --> XdDoubleList
  XdQuantified --> XdIntegerList
  XdQuantified --> XdNonNegativeIntegerList
  XdQuantified --> XdPositiveIntegerList
  Common --> Cluster
  Common --> Party
  Common --> Participation
  Common --> Audit
  Common --> Attestation

What every component carries

In the record. Every Xd value in a Governed Data Record can carry these elements beside its value. The schema defines them once on XdAnyType:

What you set. Every component has these fields from Common:

Every Xd value type adds the XdAny switches that decide which of the common elements a record must or may carry:

Semantic links. Every component and model carries a set of RDF predicate-object pairs (pred_obj) that link it to terms in published ontologies; they are set on the Semantic Linking step of each wizard. Lifecycle. published locks a component for use in models; retired (with retired_at and retired_reason) hides it from lists and new models while every record made from it stays valid. Neither is edited directly: Save & Publish, Copy and Retire are the controls.

Shared by ordered types (XdOrderedType)

Abstract type defining the concept of ordered values, which includes ordinals as well as true quantities. The implementations require the functions '' and is_strictly_comparable_to ('==').

Shared by quantified types (XdQuantifiedType)

Abstract type defining the concept of true quantified values, i.e. values which are not only ordered, but which have a precise magnitude.

Data Types

The twelve value types. Each carries one value (or, for Temporal, one of nine representations) plus what every component carries.

String (XdString)

Use it for. Free text and coded text: names, addresses, notes, and any pick-list without an inherent order. The permitted values are bound into the component, so the list stops being validation on one sheet and becomes part of the definition everyone inherits.

In the schema: XdStringType, extending XdAnyType. Inherits XdAny.

The string data type can contain characters, line feeds, carriage returns, and tab characters. The use cases are for any free form text entry or for any enumerated lists. Additionally the minimum and maximum lengths may be set and regular expression patterns may be specified.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Boolean (XdBoolean)

Use it for. A yes-or-no with both answers named: Granted and Denied, not 1 and 0. Six months later nobody has to ask what the 1 meant.

In the schema: XdBooleanType, extending XdAnyType. Inherits XdAny.

An enumerated type which represents boolean decisions. Such as true/false or yes/no answers. Useful where it is essential to devise the meanings (often questions in subjective data) carefully so that the only allowed result values result in one the options; true or false but are presented to the user as a list of options. The possible choices for True or False are enumerations in the DM. The reference model defines 'true-value' and 'false-value' in an xsd:choice so only one or the other may be present in the instance data. The XdBooleanType should not be used as a replacement for enumerated choice types such as male/female, or similar choice sets. Such values should be modeled as XdStrings with enumerations and may reference a controlled vocabulary. In any case, the choice set often has more than two values. The elements, 'true-value' and 'false-value' are contained in an xsd:choice and only one or the other is instantiated in the instance data with its value coming from the enumerations defined in a Data Model.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Count (XdCount)

Use it for. Counting discrete things: pallets, visits, employees, doses dispensed. Always a whole number, and it carries its own unit, so the value is not 17 but 17 pallets.

In the schema: XdCountType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

Countable quantities. Used for countable types such as pregnancies and steps (taken by a physiotherapy patient), number of cigarettes smoked in a day, etc. The thing(s) being counted must be represented in the units element. Misuse:Not used for amounts of physical entities (which all have standardized units).

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Quantity (XdQuantity)

Use it for. Measuring something, with required units: 2.5 kg, 120 mmHg, 499.00 USD. If a value can be halved and still mean something it is a measurement. Money is a Quantity and the currency is the unit.

In the schema: XdQuantityType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

Quantified type representing specific quantities, i.e. quantities expressed as a magnitude and units. Can also be used for time durations, where it is more convenient to treat these as simply a number of individual seconds, minutes, hours, days, months, years, etc. when no temporal calculation is to be performed.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Temporal (XdTemporal)

Use it for. Dates and times at a deliberate granularity: a date of birth is a date, an event is a date and a time, a lease is a duration. Saying which one you mean stops the receiving system inventing midnight.

In the schema: XdTemporalType, extending XdOrderedType. Inherits XdOrdered, XdAny.

Type defining a temporal value. It allows for varying levels of precision by offering a choice of exactly one temporal representation, from a full dateTime to a partial date like a year-month. In a Data Model, this type is constrained via restriction to a subset of the choices, allowing the modeler to define precisely which temporal representations are permitted for a given field (e.g., allowing only xsd:date or xsd:gYearMonth for a date of birth).

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Float (XdFloat)

Use it for. A 32-bit IEEE floating-point value with optional units, for scientific and engineering data where that representation is the right one. Not for money or business measures: those are Quantities.

In the schema: XdFloatType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

Quantified type representing specific a value as a floating point (32 bit) number and optional units. This is a xsd:float.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Double (XdDouble)

Use it for. A 64-bit IEEE floating-point value with optional units, for scientific and engineering data where that representation is the right one. Not for money or business measures: those are Quantities.

In the schema: XdDoubleType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

Quantified type representing specific a value as a 64 bit number and optional units. This is a xsd:double.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Ordinal (XdOrdinal)

Use it for. Ordered categories: mild, moderate, severe; bronze, silver, gold. Carries the symbol a person reads and the rank a machine sorts by, and each symbol can point at its definition.

In the schema: XdOrdinalType, extending XdOrderedType. Inherits XdOrdered, XdAny.

Models rankings and scores, e.g., pain, Apgar values, educational level, and the Likert Scale where there is; * implied ordering, * no implication that the distance between each value is constant, and * the total number of values is finite. Note that the term 'ordinal' in mathematics means natural numbers only. In this case, any decimal is allowed since negative, and zero values are used by medical and other professionals for centering values around a neutral point. Also, decimal values are sometimes used such as 0.5 or .25 Examples of sets of ordinal values are; * -3, -2, -1, 0, 1, 2, 3 -- reflex response values * 0, 1, 2 -- Apgar values Also used for recording any clinical or other data which is customarily recorded using symbolic values. Examples; * the results on a urinalysis strip, e.g. {neg, trace, +, ++, +++} are used for leukocytes, protein, nitrites etc; * for non-haemolysed blood {neg, trace, moderate}; * for haemolysed blood {neg, trace, small, moderate, large}. Elements ordinal and symbol MUST have the same number of enumerations in the RMC.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Link (XdLink)

Use it for. A reference to another record or resource that carries the relationship in words (this document is the subject_of that one) rather than as a bare foreign key.

In the schema: XdLinkType, extending XdAnyType. Inherits XdAny.

Used to specify a Universal Resource Identifier. Set the pattern facet to accommodate your needs in the DM. Intended use is to provide a mechanism that can be used to link together Data Models. The relation element allows for the use of a descriptive term for the link with an optional URI pointing to the source vocabulary. In most usecases the modeler will define all three of these using the 'fixed' attribute. Other usecases will have the 'relation' and 'relation-uri' elements fixed and the application will provide the 'link-value'.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

File (XdFile)

Use it for. A file or media item, embedded in the record or referenced by URI, with its media type, encoding, size and hash.

In the schema: XdFileType, extending XdAnyType. Inherits XdAny.

A type to use for encapsulated content (aka. files) for image, audio and other media types with a defined MIME type. This type provides a choice of embedding the content into the data or using a URL to point to the content.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Token (XdToken)

Use it for. Codes and identifiers: an SKU, an ICD-10 code, a policy number. Leading, trailing and repeated whitespace is normalized, so a stray space in one system never makes the same code fail to match.

In the schema: XdTokenType, extending XdAnyType. Inherits XdAny.

The token data type represents normalized strings where leading and trailing whitespace is removed and internal whitespace is normalized to single spaces. This type is useful for identifiers, codes, and other normalized text values that should not contain excessive whitespace. The use cases are for identifiers, codes, enumerated values, and other normalized text entries.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Interval (XdInterval)

Use it for. A bounded range of ordered values: integers, decimals, floats, doubles, dates, times, date-times or durations. Used mostly as the interval of a reference range.

In the schema: XdIntervalType, extending XdAnyType. Inherits XdAny.

A generic type for defining an interval (i.e., range) of ordered values. It is primarily used to define reference ranges for quantified data.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

List Types

The eight list types carry several values of one kind in one component. In the record the values are one space-delimited string; the model sets how many items, whether duplicates are allowed and whether order matters. The five numeric lists are quantified: they carry units and magnitude constraints like their scalar counterparts.

Boolean List (XdBooleanList)

Use it for. Several yes-or-no flags of one kind in one component, space-delimited in the record.

In the schema: XdBooleanListType, extending XdAnyType. Inherits XdAny.

A data type for a white space-delimited list of boolean values. This type provides efficient storage and transmission of multiple boolean values in a single field. Useful for scientific measurements, batch processing results, and other scenarios where multiple related boolean values need to be transmitted together.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

String List (XdStringList)

Use it for. Several text values of one kind in one component: tags, aliases, keywords.

In the schema: XdStringListType, extending XdAnyType. Inherits XdAny.

A data type for a white space-delimited list of string values. This type provides efficient storage and transmission of multiple string values in a single field. Useful for identifiers, codes, and other scenarios where multiple related string values need to be transmitted together.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Token List (XdTokenList)

Use it for. Several codes of one kind in one component, each normalized as a Token is.

In the schema: XdTokenListType, extending XdAnyType. Inherits XdAny.

A data type for a white space-delimited list of normalized token values. This type provides efficient storage and transmission of multiple normalized token values in a single field. Useful for identifiers, codes, and other scenarios where multiple related normalized token values need to be transmitted together. Token values have leading and trailing whitespace removed and internal whitespace normalized to single spaces.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Decimal List (XdDecimalList)

Use it for. Several decimal readings of one kind with one set of units: a series of measurements.

In the schema: XdDecimalListType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

A data type for a white space-delimited list of decimal values. This type provides efficient storage and transmission of multiple decimal values in a single field. Useful for scientific measurements, statistical data, and other scenarios where multiple related decimal values need to be transmitted together. All values in the list share the same units.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Double List (XdDoubleList)

Use it for. Several double-precision readings of one kind with one set of units.

In the schema: XdDoubleListType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

A data type for a white space-delimited list of double precision values. This type provides efficient storage and transmission of multiple double values in a single field. Useful for scientific measurements, mathematical computations, and other scenarios where multiple related double precision values need to be transmitted together. All values in the list share the same units.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Integer List (XdIntegerList)

Use it for. Several whole numbers of one kind with one set of units.

In the schema: XdIntegerListType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

A data type for a white space-delimited list of integer values. This type provides efficient storage and transmission of multiple integer values in a single field. Useful for counts, indices, and other scenarios where multiple related integer values need to be transmitted together. All values in the list share the same units.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Non-Negative Int List (XdNonNegativeIntegerList)

Use it for. Several whole numbers of one kind that cannot be negative, with one set of units.

In the schema: XdNonNegativeIntegerListType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

A data type for a white space-delimited list of non-negative integer values. This type provides efficient storage and transmission of multiple non-negative integer values in a single field. Useful for counts, indices, and other scenarios where multiple related non-negative integer values need to be transmitted together. All values in the list share the same units.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Positive Int List (XdPositiveIntegerList)

Use it for. Several whole numbers of one kind that must be greater than zero, with one set of units.

In the schema: XdPositiveIntegerListType, extending XdQuantifiedType. Inherits XdQuantified, XdOrdered, XdAny.

A data type for a white space-delimited list of positive integer values. This type provides efficient storage and transmission of multiple positive integer values in a single field. Useful for counts, indices, and other scenarios where multiple related positive integer values need to be transmitted together. All values in the list share the same units.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Structural

The two types that give a record its shape.

Cluster

Use it for. The grouping. A Governed Data Record is a Cluster of components and smaller clusters, and a data model names one Cluster as its structure.

In the schema: ClusterType, extending ItemType.

The grouping component, which may contain further instances of itself or any eXtended datatype, in an ordered list. This can serve as the root component for arbitrarily complex structures.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Units

Use it for. The permitted units for a quantified component, published as a string type with the unit names as its enumeration. Count, Quantity, Float, Double and the numeric lists each point at a Units component.

In the schema: XdStringType, extending XdAnyType. Inherits XdAny.

The string data type can contain characters, line feeds, carriage returns, and tab characters. The use cases are for any free form text entry or for any enumerated lists. Additionally the minimum and maximum lengths may be set and regular expression patterns may be specified.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Contextual

The four types that say who, where and when. They are not Xd types: they carry no exceptional values, valid-time or location elements of their own, only a label and their own fields.

Party

Use it for. A person or organization: the subject of a record, a provider, a committer, with an optional link to an identity system and an optional details cluster.

In the schema: PartyType.

Description of a party, including an optional external link to data for this party in a demographic or other identity management system. An additional details element provides for the inclusion of information related to this party directly. If the party information is to be anonymous then do not include the details element.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Participation

Use it for. Who took part in the activity a record describes, in what function and mode, and when.

In the schema: ParticipationType.

Model of a participation of a Party (any Actor or Role) in an activity. Used to represent any participation of a Party in some activity, which is not explicitly in the model, e.g. assisting nurse. Can be used to record past or future participations.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Audit

Use it for. The who, where and when of a record as it moves from system to system.

In the schema: AuditType.

AuditType provides a mechanism to identify the who/where/when tracking of instances as they move from system to system.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Attestation

Use it for. A party's attestation of a record's content: the reason, the proof, the committer, whether it is still pending.

In the schema: AttestationType.

Record an attestation by a party of the DM content. The type of attestation is recorded by the reason attribute, which my be coded.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Reference ranges and intervals

Any ordered value can carry reference ranges (normal, critical, therapeutic), each with an interval. In SDCStudio a ReferenceRange points at a separate Interval component; a SimpleReferenceRange carries its interval inline and publishes as the same schema type. Neither is on the wizard's grid; both are created from a quantified component's reference-range settings.

Reference Range (ReferenceRange)

Use it for. A named range (normal, critical, therapeutic) for an ordered value, with its interval as a separate Interval component.

In the schema: ReferenceRangeType, extending XdAnyType. Inherits XdAny.

Defines a named range to be associated with any ORDERED datatype. Each such range is sensitive to the context, e.g. sex, age, location, and any other factor which affects ranges. May be used to represent high, low, normal, therapeutic, dangerous, critical, etc. ranges that are constrained by an interval.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

Simple Reference Range (SimpleReferenceRange)

Use it for. A named range with its interval written in the same component. Published as a ReferenceRange.

In the schema: ReferenceRangeType, extending XdAnyType. Inherits XdAny.

Defines a named range to be associated with any ORDERED datatype. Each such range is sensitive to the context, e.g. sex, age, location, and any other factor which affects ranges. May be used to represent high, low, normal, therapeutic, dangerous, critical, etc. ranges that are constrained by an interval.

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

The interval boundary (InvlType) and its units (InvlUnits)

Defines the set of permissible, comparable datatypes that can be used as the boundary for an interval. In a Data Model, this type is constrained to a single choice (e.g., only 'invl-decimal').

The units designation for an Interval. This is composed of a units name and a URI because a ReferenceRange can contain intervals with different units (e.g., a temperature range in Celsius and another in Fahrenheit).

The Data Model

Data Model (DM)

Use it for. The data model: the root of a Governed Data Record, carrying the structure (one Cluster), the parties, the provenance, the Dublin Core description and the assertions.

In the schema: DMType.

This is the root node of a Data Model (DM).

In the record (the elements this type adds; every Xd type also carries the common elements below):

What you set (the fields this type adds in SDCStudio):

The item wrappers (ItemType, XdAdapterType)

A Cluster's members are Item elements. A nested Cluster is an Item; a value is wrapped in an XdAdapter, the leaf Item, so that every member of a Cluster has the same outer shape. SDCStudio writes the adapters; a modeler never creates one.

The sixteen exceptional values

Subtypes are used to indicate why a value is missing (Null) or is outside a measurable range. The element ev-name is fixed in restricted types to a descriptive string. The subtypes defined in the reference model are considered sufficiently generic to be useful in many instances. Data Models may contain additional ExceptionalValueType restrictions to allow for domain related reasons for errant or missing data.

A record puts one or more of these elements beside a value, or in place of it, and the reason the value is missing or unusable travels with the record. The sixteen, with the name each carries in its ev-name element:

A data model may add its own restrictions of ExceptionalValueType for domain reasons; these sixteen are the ones every SDC4 record understands.