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"
}
}
}
| Property | Type | Cardinality | Description |
|---|
system | uri | 0:1 | Namespace that defines uniqueness |
value | symbol | 0:1 | The actual identifier |
use | code | 0:1 | Purpose (usual, official, temp, secondary) |
period | period | 0:1 | When identifier was/is valid |
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"
}
}
}
| Property | Type | Cardinality | Description |
|---|
use | code | 0:1 | Purpose (home, work, temp, old) |
type | code | 0:1 | Physical vs mailing address |
text | symbol | 0:1 | Complete address string |
line | array of symbol | 0:* | Street address components |
city | symbol | 0:1 | City name |
district | symbol | 0:1 | District/prefecture |
state | symbol | 0:1 | State/province |
postalCode | symbol | 0:1 | Postal/ZIP code |
country | symbol | 0:1 | Country name |
period | period | 0:1 | When 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"
}
}
}
| Property | Type | Cardinality | Description |
|---|
use | code | 0:1 | Purpose (usual, official, nickname, maiden) |
text | symbol | 0:1 | Complete display name |
family | symbol | 0:1 | Family/last name |
given | array of symbol | 0:* | Given/first names and middle names |
prefix | array of symbol | 0:* | Prefixes (Dr., Prof.) |
suffix | array of symbol | 0:* | Suffixes (Jr., MD, PhD) |
period | period | 0:1 | When the name was/is in use |
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"
}
}
}
| Property | Type | Cardinality | Description |
|---|
system | code | 0:1 | Communication type (phone, fax, email, url, sms) |
value | symbol | 0:1 | Actual contact detail |
use | code | 0:1 | Purpose (home, work, mobile, old) |
rank | integer | 0:1 | Preference (1 = highest priority) |
period | period | 0:1 | When 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"
}
}
| Property | Type | Cardinality | Description |
|---|
system | uri | 0:1 | Terminology system URL |
version | symbol | 0:1 | Code system version |
code | code | 0:1 | Symbol defined by the system |
display | symbol | 0:1 | Human-readable representation |
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"
}
}
| Property | Type | Cardinality | Description |
|---|
reference | symbol | 0:1 | Relative or absolute reference |
type | uri | 0:1 | Resource type being referenced |
identifier | identifier | 0:1 | Logical reference when literal unknown |
display | symbol | 0:1 | Human-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"
}
}
| Property | Type | Cardinality | Description |
|---|
start | datetime | 0:1 | Beginning of the period (inclusive) |
end | datetime | 0:1 | End 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"
}
}
| Property | Type | Cardinality | Description |
|---|
contentType | code | 0:1 | MIME type |
language | code | 0:1 | Content language |
url | url | 0:1 | Location of the content |
size | integer | 0:1 | Size in bytes |
title | symbol | 0:1 | Display label |
creation | datetime | 0:1 | When 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.
