> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clinia Complex Types

> Discover the opinionated data structures Clinia provides for healthcare interoperability

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.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "patientId": {
        "system": "http://hospital.example.com/patients",
        "value": "MRN-123456",
        "use": "usual",
        "period": {
          "start": "2020-01-01T00:00:00Z"
        }
      }
    }
    ```
  </Tab>
</Tabs>

| 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               |

<Info>
  Provide either `system`+`value` together or just `value` for meaningful identification. See [field validation cardinality](/explanation/field-validation/advanced#cardinality) for rule combinations.
</Info>

## Address (`address`)

Postal addresses for physical and mailing locations.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

| 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.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

| 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                 |

## ContactPoint (`contactpoint`)

Communication details for individuals or organizations.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "phoneNumber": {
        "system": "phone",
        "value": "+1-617-555-0123",
        "use": "work",
        "rank": 1,
        "period": {
          "start": "2020-01-01T00:00:00Z"
        }
      }
    }
    ```
  </Tab>
</Tabs>

| 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.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "diagnosis": {
        "system": "http://snomed.info/sct",
        "version": "2024.03",
        "code": "44054006",
        "display": "Type 2 diabetes mellitus"
      }
    }
    ```
  </Tab>
</Tabs>

| 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 |

<Info>
  Bind codings to vocabularies for richer validation. See [Vocabulary validation](/explanation/field-validation/vocabulary) for workflow details.
</Info>

## Reference (`reference`)

Links to other resources within or outside the system.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "practitioner": {
        "reference": "Practitioner/dr-wilson-123",
        "type": "Practitioner",
        "identifier": {
          "system": "http://hospital.example.com/practitioners",
          "value": "PROV-456"
        },
        "display": "Dr. Sarah Wilson, MD"
      }
    }
    ```
  </Tab>
</Tabs>

| 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                   |

<Warning>
  Provide either `reference` or `identifier` to keep references resolvable.
</Warning>

## Period (`period`)

Time periods with start and end dates.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "employmentPeriod": {
        "start": "2020-01-01T00:00:00Z",
        "end": "2024-12-31T23:59:59Z"
      }
    }
    ```
  </Tab>
</Tabs>

| 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.

<Tabs>
  <Tab title="Example Usage">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>
</Tabs>

| 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](/explanation/field-validation/advanced).

### Mix with base types

Complex types coexist with [base primitives](/explanation/data-types/base-types). 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.

## Related documentation

<CardGroup cols={2}>
  <Card title="Base Data Types" icon="cubes" href="/explanation/data-types/base-types">
    Review primitive and composite building blocks that these complex types rely on.
  </Card>

  <Card title="Profiles" icon="shapes" href="/explanation/data-model/profiles-relationships">
    See how complex types appear in profile definitions and ingestion.
  </Card>
</CardGroup>