Skip to main content
Clinia augments base primitives with opinionated structures that model healthcare and business concepts. These complex types keep your schemas interoperable while aligning with validation, search, and terminology features across the platform.

​
Identifier (identifier)

Uniquely identifies entities within specific systems. 
{
  "patientId": {
    "system": "http://hospital.example.com/patients",
    "value": "MRN-123456",
    "use": "usual",
    "period": {
      "start": "2020-01-01T00:00:00Z"
    }
  }
}
PropertyTypeCardinalityDescription
systemuri0:1Namespace that defines uniqueness
valuesymbol0:1The actual identifier
usecode0:1Purpose (usual, official, temp, secondary)
periodperiod0:1When identifier was/is valid
Provide either system+value together or just value for meaningful identification. See field validation cardinality for rule combinations.

​
Address (address)

Postal addresses for physical and mailing locations. 
{
  "clinicAddress": {
    "use": "work",
    "type": "physical",
    "text": "123 Medical Center Dr, Suite 200, Boston, MA 02115",
    "line": ["123 Medical Center Dr", "Suite 200"],
    "city": "Boston",
    "state": "MA",
    "postalCode": "02115",
    "country": "US",
    "period": {
      "start": "2020-01-01T00:00:00Z"
    }
  }
}
PropertyTypeCardinalityDescription
usecode0:1Purpose (home, work, temp, old)
typecode0:1Physical vs mailing address
textsymbol0:1Complete address string
linearray of symbol0:*Street address components
citysymbol0:1City name
districtsymbol0:1District/prefecture
statesymbol0:1State/province
postalCodesymbol0:1Postal/ZIP code
countrysymbol0:1Country name
periodperiod0:1When address was/is valid

​
HumanName (humanname)

Structured representation of human names. 
{
  "providerName": {
    "use": "official",
    "text": "Dr. Sarah Elizabeth Wilson, MD",
    "family": "Wilson",
    "given": ["Sarah", "Elizabeth"],
    "prefix": ["Dr."],
    "suffix": ["MD"],
    "period": {
      "start": "2015-01-01T00:00:00Z"
    }
  }
}
PropertyTypeCardinalityDescription
usecode0:1Purpose (usual, official, nickname, maiden)
textsymbol0:1Complete display name
familysymbol0:1Family/last name
givenarray of symbol0:*Given/first names and middle names
prefixarray of symbol0:*Prefixes (Dr., Prof.)
suffixarray of symbol0:*Suffixes (Jr., MD, PhD)
periodperiod0:1When the name was/is in use

​
ContactPoint (contactpoint)

Communication details for individuals or organizations. 
{
  "phoneNumber": {
    "system": "phone",
    "value": "+1-617-555-0123",
    "use": "work",
    "rank": 1,
    "period": {
      "start": "2020-01-01T00:00:00Z"
    }
  }
}
PropertyTypeCardinalityDescription
systemcode0:1Communication type (phone, fax, email, url, sms)
valuesymbol0:1Actual contact detail
usecode0:1Purpose (home, work, mobile, old)
rankinteger0:1Preference (1 = highest priority)
periodperiod0:1When contact point was/is valid

​
Coding (coding)

References to concepts in terminology systems. 
{
  "diagnosis": {
    "system": "http://snomed.info/sct",
    "version": "2024.03",
    "code": "44054006",
    "display": "Type 2 diabetes mellitus"
  }
}
PropertyTypeCardinalityDescription
systemuri0:1Terminology system URL
versionsymbol0:1Code system version
codecode0:1Symbol defined by the system
displaysymbol0:1Human-readable representation
Bind codings to vocabularies for richer validation. See Vocabulary validation for workflow details.

​
Reference (reference)

Links to other resources within or outside the system. 
{
  "practitioner": {
    "reference": "Practitioner/dr-wilson-123",
    "type": "Practitioner",
    "identifier": {
      "system": "http://hospital.example.com/practitioners",
      "value": "PROV-456"
    },
    "display": "Dr. Sarah Wilson, MD"
  }
}
PropertyTypeCardinalityDescription
referencesymbol0:1Relative or absolute reference
typeuri0:1Resource type being referenced
identifieridentifier0:1Logical reference when literal unknown
displaysymbol0:1Human-readable label
Provide either reference or identifier to keep references resolvable.

​
Period (period)

Time periods with start and end dates. 
{
  "employmentPeriod": {
    "start": "2020-01-01T00:00:00Z",
    "end": "2024-12-31T23:59:59Z"
  }
}
PropertyTypeCardinalityDescription
startdatetime0:1Beginning of the period (inclusive)
enddatetime0:1End of the period (optional for ongoing)

​
Attachment (attachment)

Content stored in external formats. 
{
  "medicalReport": {
    "contentType": "application/pdf",
    "language": "en-US",
    "url": "https://storage.example.com/reports/patient-123-xray.pdf",
    "size": 2048576,
    "title": "Chest X-Ray Report - Patient 123",
    "creation": "2024-08-15T10:30:00Z"
  }
}
PropertyTypeCardinalityDescription
contentTypecode0:1MIME type
languagecode0:1Content language
urlurl0:1Location of the content
sizeinteger0:1Size in bytes
titlesymbol0:1Display label
creationdatetime0:1When attachment was created

​
Best practices

​
Consistency guidelines

  • Prefer standard types — Use Clinia complex types (address, humanname, identifier) instead of bespoke objects to stay interoperable.
  • Terminology binding — Couple coding and code fields with managed vocabularies for consistent semantics.
  • Identifier hygiene — Establish system URIs and enforce uniqueness with validation rules.

​
Mix with base types

Complex types coexist with base primitives. For example:
  • A ContactPoint can include arrays of code and symbol.
  • Attachment metadata combines code, url, and integer values.
  • Reference leverages identifier for logical linking.
Design schemas so that complex types express business intent while base types enforce structure.

Base Data Types

Review primitive and composite building blocks that these complex types rely on.

Profiles

See how complex types appear in profile definitions and ingestion.