Skip to content

Protocols API Reference

All protocol definitions.

Patient Protocols

PatientProtocol

Bases: Protocol

Patient data contract.

Source code in ccdakit/protocols/patient.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class PatientProtocol(Protocol):
    """Patient data contract."""

    @property
    def first_name(self) -> str:
        """
        Legal first name.

        Returns:
            First name
        """
        ...

    @property
    def last_name(self) -> str:
        """
        Legal last name.

        Returns:
            Last name
        """
        ...

    @property
    def middle_name(self) -> Optional[str]:
        """
        Middle name or initial.

        Returns:
            Middle name or None
        """
        ...

    @property
    def date_of_birth(self) -> date:
        """
        Date of birth.

        Returns:
            Date of birth
        """
        ...

    @property
    def sex(self) -> str:
        """
        Administrative sex: 'M', 'F', or 'UN'.

        Returns:
            Sex code
        """
        ...

    @property
    def race(self) -> Optional[str]:
        """
        Race code (CDC Race and Ethnicity).

        Returns:
            Race code or None
        """
        ...

    @property
    def ethnicity(self) -> Optional[str]:
        """
        Ethnicity code (CDC Race and Ethnicity).

        Returns:
            Ethnicity code or None
        """
        ...

    @property
    def language(self) -> Optional[str]:
        """
        Preferred language (ISO 639-2).

        Returns:
            Language code or None
        """
        ...

    @property
    def ssn(self) -> Optional[str]:
        """
        Social Security Number (US) or national ID.

        Returns:
            SSN or None
        """
        ...

    @property
    def addresses(self) -> Sequence[AddressProtocol]:
        """
        List of addresses (home, work, etc.).

        Returns:
            List of addresses
        """
        ...

    @property
    def telecoms(self) -> Sequence[TelecomProtocol]:
        """
        List of contact methods (phone, email, etc.).

        Returns:
            List of contact methods
        """
        ...

    @property
    def marital_status(self) -> Optional[str]:
        """
        Marital status code (HL7 MaritalStatus).

        Returns:
            Marital status code or None
        """
        ...

Attributes

first_name property

Legal first name.

Returns:

Type Description
str

First name

last_name property

Legal last name.

Returns:

Type Description
str

Last name

middle_name property

Middle name or initial.

Returns:

Type Description
Optional[str]

Middle name or None

date_of_birth property

Date of birth.

Returns:

Type Description
date

Date of birth

sex property

Administrative sex: 'M', 'F', or 'UN'.

Returns:

Type Description
str

Sex code

race property

Race code (CDC Race and Ethnicity).

Returns:

Type Description
Optional[str]

Race code or None

ethnicity property

Ethnicity code (CDC Race and Ethnicity).

Returns:

Type Description
Optional[str]

Ethnicity code or None

language property

Preferred language (ISO 639-2).

Returns:

Type Description
Optional[str]

Language code or None

ssn property

Social Security Number (US) or national ID.

Returns:

Type Description
Optional[str]

SSN or None

addresses property

List of addresses (home, work, etc.).

Returns:

Type Description
Sequence[AddressProtocol]

List of addresses

telecoms property

List of contact methods (phone, email, etc.).

Returns:

Type Description
Sequence[TelecomProtocol]

List of contact methods

marital_status property

Marital status code (HL7 MaritalStatus).

Returns:

Type Description
Optional[str]

Marital status code or None

AddressProtocol

Bases: Protocol

Address data contract.

Source code in ccdakit/protocols/patient.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class AddressProtocol(Protocol):
    """Address data contract."""

    @property
    def street_lines(self) -> Sequence[str]:
        """
        Street address lines (1-4 lines).

        Returns:
            List of street address lines
        """
        ...

    @property
    def city(self) -> str:
        """
        City name.

        Returns:
            City name
        """
        ...

    @property
    def state(self) -> str:
        """
        State/province code (e.g., 'CA', 'NY').

        Returns:
            State or province code
        """
        ...

    @property
    def postal_code(self) -> str:
        """
        ZIP/postal code.

        Returns:
            Postal code
        """
        ...

    @property
    def country(self) -> str:
        """
        Country code (ISO 3166-1 alpha-2, e.g., 'US').

        Returns:
            Country code
        """
        ...

Attributes

street_lines property

Street address lines (1-4 lines).

Returns:

Type Description
Sequence[str]

List of street address lines

city property

City name.

Returns:

Type Description
str

City name

state property

State/province code (e.g., 'CA', 'NY').

Returns:

Type Description
str

State or province code

postal_code property

ZIP/postal code.

Returns:

Type Description
str

Postal code

country property

Country code (ISO 3166-1 alpha-2, e.g., 'US').

Returns:

Type Description
str

Country code

TelecomProtocol

Bases: Protocol

Contact information protocol.

Source code in ccdakit/protocols/patient.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class TelecomProtocol(Protocol):
    """Contact information protocol."""

    @property
    def type(self) -> str:
        """
        Type: 'phone', 'email', 'fax', 'url'.

        Returns:
            Type of contact information
        """
        ...

    @property
    def value(self) -> str:
        """
        The actual phone number, email, etc.

        Returns:
            Contact value (phone number, email address, etc.)
        """
        ...

    @property
    def use(self) -> Optional[str]:
        """
        Use code: 'HP' (home), 'WP' (work), 'MC' (mobile).

        Returns:
            Use code or None
        """
        ...

Attributes

type property

Type: 'phone', 'email', 'fax', 'url'.

Returns:

Type Description
str

Type of contact information

value property

The actual phone number, email, etc.

Returns:

Type Description
str

Contact value (phone number, email address, etc.)

use property

Use code: 'HP' (home), 'WP' (work), 'MC' (mobile).

Returns:

Type Description
Optional[str]

Use code or None

Author Protocols

AuthorProtocol

Bases: Protocol

Author data contract for CDA header.

Source code in ccdakit/protocols/author.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
class AuthorProtocol(Protocol):
    """Author data contract for CDA header."""

    @property
    def first_name(self) -> str:
        """
        Author's first name.

        Returns:
            First name
        """
        ...

    @property
    def last_name(self) -> str:
        """
        Author's last name.

        Returns:
            Last name
        """
        ...

    @property
    def middle_name(self) -> Optional[str]:
        """
        Author's middle name or initial.

        Returns:
            Middle name or None
        """
        ...

    @property
    def npi(self) -> Optional[str]:
        """
        National Provider Identifier.

        Returns:
            NPI or None
        """
        ...

    @property
    def addresses(self) -> Sequence[AddressProtocol]:
        """
        List of author addresses.

        Returns:
            List of addresses
        """
        ...

    @property
    def telecoms(self) -> Sequence[TelecomProtocol]:
        """
        List of author contact methods.

        Returns:
            List of contact methods
        """
        ...

    @property
    def time(self) -> datetime:
        """
        Time when the document was authored.

        Returns:
            Authoring time
        """
        ...

    @property
    def organization(self) -> Optional[OrganizationProtocol]:
        """
        Author's organization/facility.

        Returns:
            Organization or None
        """
        ...

Attributes

first_name property

Author's first name.

Returns:

Type Description
str

First name

last_name property

Author's last name.

Returns:

Type Description
str

Last name

middle_name property

Author's middle name or initial.

Returns:

Type Description
Optional[str]

Middle name or None

npi property

National Provider Identifier.

Returns:

Type Description
Optional[str]

NPI or None

addresses property

List of author addresses.

Returns:

Type Description
Sequence[AddressProtocol]

List of addresses

telecoms property

List of author contact methods.

Returns:

Type Description
Sequence[TelecomProtocol]

List of contact methods

time property

Time when the document was authored.

Returns:

Type Description
datetime

Authoring time

organization property

Author's organization/facility.

Returns:

Type Description
Optional[OrganizationProtocol]

Organization or None

OrganizationProtocol

Bases: Protocol

Organization/facility data contract.

Source code in ccdakit/protocols/author.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
class OrganizationProtocol(Protocol):
    """Organization/facility data contract."""

    @property
    def name(self) -> str:
        """
        Organization name.

        Returns:
            Organization name
        """
        ...

    @property
    def npi(self) -> Optional[str]:
        """
        National Provider Identifier.

        Returns:
            NPI or None
        """
        ...

    @property
    def tin(self) -> Optional[str]:
        """
        Tax Identification Number.

        Returns:
            TIN or None
        """
        ...

    @property
    def oid_root(self) -> Optional[str]:
        """
        Organization's OID namespace.

        Returns:
            OID root or None
        """
        ...

    @property
    def addresses(self) -> Sequence[AddressProtocol]:
        """
        List of organization addresses.

        Returns:
            List of addresses
        """
        ...

    @property
    def telecoms(self) -> Sequence[TelecomProtocol]:
        """
        List of organization contact methods.

        Returns:
            List of contact methods
        """
        ...

Attributes

name property

Organization name.

Returns:

Type Description
str

Organization name

npi property

National Provider Identifier.

Returns:

Type Description
Optional[str]

NPI or None

tin property

Tax Identification Number.

Returns:

Type Description
Optional[str]

TIN or None

oid_root property

Organization's OID namespace.

Returns:

Type Description
Optional[str]

OID root or None

addresses property

List of organization addresses.

Returns:

Type Description
Sequence[AddressProtocol]

List of addresses

telecoms property

List of organization contact methods.

Returns:

Type Description
Sequence[TelecomProtocol]

List of contact methods

Clinical Protocols

ProblemProtocol

Bases: Protocol

Problem/diagnosis data contract.

Source code in ccdakit/protocols/problem.py 
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class ProblemProtocol(Protocol):
    """Problem/diagnosis data contract."""

    @property
    def name(self) -> str:
        """
        Human-readable problem name.

        Returns:
            Problem name
        """
        ...

    @property
    def code(self) -> str:
        """
        SNOMED CT or ICD-10 code.

        Returns:
            Problem code
        """
        ...

    @property
    def code_system(self) -> str:
        """
        Code system: 'SNOMED' or 'ICD-10'.

        Returns:
            Code system name
        """
        ...

    @property
    def onset_date(self) -> Optional[date]:
        """
        Date problem was identified/started.

        Returns:
            Onset date or None
        """
        ...

    @property
    def resolved_date(self) -> Optional[date]:
        """
        Date problem was resolved (None if ongoing).

        Returns:
            Resolved date or None
        """
        ...

    @property
    def status(self) -> str:
        """
        Status: 'active', 'inactive', 'resolved'.

        Returns:
            Problem status
        """
        ...

    @property
    def persistent_id(self) -> Optional[PersistentIDProtocol]:
        """
        Persistent ID across document versions.

        Returns:
            Persistent ID or None
        """
        ...

Attributes

name property

Human-readable problem name.

Returns:

Type Description
str

Problem name

code property

SNOMED CT or ICD-10 code.

Returns:

Type Description
str

Problem code

code_system property

Code system: 'SNOMED' or 'ICD-10'.

Returns:

Type Description
str

Code system name

onset_date property

Date problem was identified/started.

Returns:

Type Description
Optional[date]

Onset date or None

resolved_date property

Date problem was resolved (None if ongoing).

Returns:

Type Description
Optional[date]

Resolved date or None

status property

Status: 'active', 'inactive', 'resolved'.

Returns:

Type Description
str

Problem status

persistent_id property

Persistent ID across document versions.

Returns:

Type Description
Optional[PersistentIDProtocol]

Persistent ID or None

PersistentIDProtocol

Bases: Protocol

Persistent identifier protocol.

Source code in ccdakit/protocols/problem.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class PersistentIDProtocol(Protocol):
    """Persistent identifier protocol."""

    @property
    def root(self) -> str:
        """
        OID or UUID identifying the assigning authority.

        Returns:
            Root identifier (OID or UUID)
        """
        ...

    @property
    def extension(self) -> str:
        """
        Unique identifier within the root's namespace.

        Returns:
            Extension identifier
        """
        ...

Attributes

root property

OID or UUID identifying the assigning authority.

Returns:

Type Description
str

Root identifier (OID or UUID)

extension property

Unique identifier within the root's namespace.

Returns:

Type Description
str

Extension identifier

MedicationProtocol

Bases: Protocol

Medication data contract.

Source code in ccdakit/protocols/medication.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class MedicationProtocol(Protocol):
    """Medication data contract."""

    @property
    def name(self) -> str:
        """
        Human-readable medication name.

        Returns:
            Medication name (e.g., "Lisinopril 10mg oral tablet")
        """
        ...

    @property
    def code(self) -> str:
        """
        RxNorm code for the medication.

        Returns:
            RxNorm code
        """
        ...

    @property
    def dosage(self) -> str:
        """
        Dosage amount (e.g., "10 mg", "1 tablet").

        Returns:
            Dosage string
        """
        ...

    @property
    def route(self) -> str:
        """
        Route of administration (e.g., "oral", "IV", "topical").

        Returns:
            Route code or display name
        """
        ...

    @property
    def frequency(self) -> str:
        """
        Frequency of administration (e.g., "twice daily", "every 6 hours").

        Returns:
            Frequency description
        """
        ...

    @property
    def start_date(self) -> date:
        """
        Date medication was started.

        Returns:
            Start date
        """
        ...

    @property
    def end_date(self) -> Optional[date]:
        """
        Date medication was stopped (None if ongoing).

        Returns:
            End date or None
        """
        ...

    @property
    def status(self) -> str:
        """
        Medication status: 'active', 'completed', 'discontinued'.

        Returns:
            Medication status
        """
        ...

    @property
    def instructions(self) -> Optional[str]:
        """
        Patient instructions (optional).

        Returns:
            Instructions or None
        """
        ...

Attributes

name property

Human-readable medication name.

Returns:

Type Description
str

Medication name (e.g., "Lisinopril 10mg oral tablet")

code property

RxNorm code for the medication.

Returns:

Type Description
str

RxNorm code

dosage property

Dosage amount (e.g., "10 mg", "1 tablet").

Returns:

Type Description
str

Dosage string

route property

Route of administration (e.g., "oral", "IV", "topical").

Returns:

Type Description
str

Route code or display name

frequency property

Frequency of administration (e.g., "twice daily", "every 6 hours").

Returns:

Type Description
str

Frequency description

start_date property

Date medication was started.

Returns:

Type Description
date

Start date

end_date property

Date medication was stopped (None if ongoing).

Returns:

Type Description
Optional[date]

End date or None

status property

Medication status: 'active', 'completed', 'discontinued'.

Returns:

Type Description
str

Medication status

instructions property

Patient instructions (optional).

Returns:

Type Description
Optional[str]

Instructions or None

AllergyProtocol

Bases: Protocol

Allergy/Intolerance data contract.

Source code in ccdakit/protocols/allergy.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class AllergyProtocol(Protocol):
    """Allergy/Intolerance data contract."""

    @property
    def allergen(self) -> str:
        """
        Human-readable allergen name.

        Returns:
            Allergen name (e.g., "Penicillin", "Peanuts", "Latex")
        """
        ...

    @property
    def allergen_code(self) -> Optional[str]:
        """
        Code for the allergen (RxNorm, UNII, or SNOMED CT).

        Returns:
            Allergen code or None
        """
        ...

    @property
    def allergen_code_system(self) -> Optional[str]:
        """
        Code system for allergen code (e.g., "RxNorm", "UNII", "SNOMED CT").

        Returns:
            Code system name or None
        """
        ...

    @property
    def allergy_type(self) -> str:
        """
        Type of allergy: 'allergy' or 'intolerance'.

        Returns:
            Allergy type
        """
        ...

    @property
    def reaction(self) -> Optional[str]:
        """
        Reaction/manifestation (e.g., "Hives", "Anaphylaxis", "Nausea").

        Returns:
            Reaction description or None
        """
        ...

    @property
    def severity(self) -> Optional[str]:
        """
        Severity: 'mild', 'moderate', 'severe', or 'fatal'.

        Returns:
            Severity level or None
        """
        ...

    @property
    def status(self) -> str:
        """
        Allergy status: 'active' or 'resolved'.

        Returns:
            Allergy status
        """
        ...

    @property
    def onset_date(self) -> Optional[date]:
        """
        Date when allergy was first identified (optional).

        Returns:
            Onset date or None
        """
        ...

Attributes

allergen property

Human-readable allergen name.

Returns:

Type Description
str

Allergen name (e.g., "Penicillin", "Peanuts", "Latex")

allergen_code property

Code for the allergen (RxNorm, UNII, or SNOMED CT).

Returns:

Type Description
Optional[str]

Allergen code or None

allergen_code_system property

Code system for allergen code (e.g., "RxNorm", "UNII", "SNOMED CT").

Returns:

Type Description
Optional[str]

Code system name or None

allergy_type property

Type of allergy: 'allergy' or 'intolerance'.

Returns:

Type Description
str

Allergy type

reaction property

Reaction/manifestation (e.g., "Hives", "Anaphylaxis", "Nausea").

Returns:

Type Description
Optional[str]

Reaction description or None

severity property

Severity: 'mild', 'moderate', 'severe', or 'fatal'.

Returns:

Type Description
Optional[str]

Severity level or None

status property

Allergy status: 'active' or 'resolved'.

Returns:

Type Description
str

Allergy status

onset_date property

Date when allergy was first identified (optional).

Returns:

Type Description
Optional[date]

Onset date or None

ImmunizationProtocol

Bases: Protocol

Protocol for immunization data.

Defines the interface that immunization objects must implement to be used with the ImmunizationActivity builder.

Attributes:

Name Type Description
vaccine_name str

Name of the vaccine (e.g., "Influenza vaccine")
cvx_code str

CVX code for the vaccine (CDC vaccine code system)
administration_date date | datetime

Date the vaccine was administered
status str

Status of the immunization (e.g., "completed", "refused")
lot_number Optional[str]

Optional vaccine lot number
manufacturer Optional[str]

Optional vaccine manufacturer name
route Optional[str]

Optional route of administration (e.g., "Intramuscular", "Oral")
site Optional[str]

Optional body site where vaccine was administered
dose_quantity Optional[str]

Optional dose quantity and unit (e.g., "0.5 mL")
Source code in ccdakit/protocols/immunization.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
class ImmunizationProtocol(Protocol):
    """Protocol for immunization data.

    Defines the interface that immunization objects must implement to be
    used with the ImmunizationActivity builder.

    Attributes:
        vaccine_name: Name of the vaccine (e.g., "Influenza vaccine")
        cvx_code: CVX code for the vaccine (CDC vaccine code system)
        administration_date: Date the vaccine was administered
        status: Status of the immunization (e.g., "completed", "refused")
        lot_number: Optional vaccine lot number
        manufacturer: Optional vaccine manufacturer name
        route: Optional route of administration (e.g., "Intramuscular", "Oral")
        site: Optional body site where vaccine was administered
        dose_quantity: Optional dose quantity and unit (e.g., "0.5 mL")
    """

    vaccine_name: str
    cvx_code: str
    administration_date: date | datetime
    status: str
    lot_number: Optional[str]
    manufacturer: Optional[str]
    route: Optional[str]
    site: Optional[str]
    dose_quantity: Optional[str]

VitalSignProtocol

Bases: Protocol

Protocol for a single vital sign observation.

Defines the interface that vital sign observation objects must implement to be used with the VitalSignObservation builder.

Attributes:

Name Type Description
type str

Type of vital sign (e.g., "Blood Pressure", "Heart Rate", "Temperature")
code str

LOINC code for the vital sign
value str

Measured value
unit str

Unit of measurement (e.g., "mm[Hg]", "bpm", "Cel")
date date | datetime

Date and time the observation was taken
interpretation Optional[str]

Optional interpretation (e.g., "Normal", "High", "Low")
Source code in ccdakit/protocols/vital_signs.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class VitalSignProtocol(Protocol):
    """Protocol for a single vital sign observation.

    Defines the interface that vital sign observation objects must implement to be
    used with the VitalSignObservation builder.

    Attributes:
        type: Type of vital sign (e.g., "Blood Pressure", "Heart Rate", "Temperature")
        code: LOINC code for the vital sign
        value: Measured value
        unit: Unit of measurement (e.g., "mm[Hg]", "bpm", "Cel")
        date: Date and time the observation was taken
        interpretation: Optional interpretation (e.g., "Normal", "High", "Low")
    """

    type: str
    code: str
    value: str
    unit: str
    date: date | datetime
    interpretation: Optional[str]

VitalSignsOrganizerProtocol

Bases: Protocol

Protocol for a group of vital sign observations taken at the same time.

Defines the interface for a vital signs organizer that groups related observations.

Attributes:

Name Type Description
date date | datetime

Date and time when the vital signs were taken
vital_signs Sequence[VitalSignProtocol]

List of vital sign observations
Source code in ccdakit/protocols/vital_signs.py 
34
35
36
37
38
39
40
41
42
43
44
45
class VitalSignsOrganizerProtocol(Protocol):
    """Protocol for a group of vital sign observations taken at the same time.

    Defines the interface for a vital signs organizer that groups related observations.

    Attributes:
        date: Date and time when the vital signs were taken
        vital_signs: List of vital sign observations
    """

    date: date | datetime
    vital_signs: Sequence[VitalSignProtocol]

ProcedureProtocol

Bases: Protocol

Protocol defining the interface for procedure data.

Represents surgical, diagnostic, or therapeutic procedures. Used with ProcedureActivity and ProceduresSection builders.

Source code in ccdakit/protocols/procedure.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class ProcedureProtocol(Protocol):
    """
    Protocol defining the interface for procedure data.

    Represents surgical, diagnostic, or therapeutic procedures.
    Used with ProcedureActivity and ProceduresSection builders.
    """

    @property
    def name(self) -> str:
        """Procedure name/description (e.g., 'Appendectomy')."""
        ...

    @property
    def code(self) -> str:
        """
        Procedure code (e.g., '80146002' from SNOMED CT).

        Should be from one of: LOINC, SNOMED CT, CPT-4, ICD10 PCS, HCPCS, or CDT-2.
        """
        ...

    @property
    def code_system(self) -> str:
        """
        Code system for the procedure code.

        Examples: 'SNOMED CT', 'CPT-4', 'LOINC', 'ICD10 PCS'
        """
        ...

    @property
    def date(self) -> Optional[date | datetime]:
        """
        Date/time when the procedure was performed.

        Can be a date or datetime. Optional but recommended.
        """
        ...

    @property
    def status(self) -> str:
        """
        Status of the procedure.

        Common values: 'completed', 'active', 'aborted', 'cancelled'
        """
        ...

    @property
    def target_site(self) -> Optional[str]:
        """
        Target body site where procedure was performed.

        Optional. Example: 'Right knee', 'Abdomen'
        """
        ...

    @property
    def target_site_code(self) -> Optional[str]:
        """
        Code for the target body site (from SNOMED CT).

        Optional. Example: '72696002' for right knee
        """
        ...

    @property
    def performer_name(self) -> Optional[str]:
        """
        Name of the person/entity who performed the procedure.

        Optional. Example: 'Dr. Jane Smith'
        """
        ...

Attributes

name property

Procedure name/description (e.g., 'Appendectomy').

code property

Procedure code (e.g., '80146002' from SNOMED CT).

Should be from one of: LOINC, SNOMED CT, CPT-4, ICD10 PCS, HCPCS, or CDT-2.

code_system property

Code system for the procedure code.

Examples: 'SNOMED CT', 'CPT-4', 'LOINC', 'ICD10 PCS'

date property

Date/time when the procedure was performed.

Can be a date or datetime. Optional but recommended.

status property

Status of the procedure.

Common values: 'completed', 'active', 'aborted', 'cancelled'

target_site property

Target body site where procedure was performed.

Optional. Example: 'Right knee', 'Abdomen'

target_site_code property

Code for the target body site (from SNOMED CT).

Optional. Example: '72696002' for right knee

performer_name property

Name of the person/entity who performed the procedure.

Optional. Example: 'Dr. Jane Smith'

ResultObservationProtocol

Bases: Protocol

Protocol for a single lab result observation.

Defines the interface that result observation objects must implement to be used with the ResultObservation builder.

Attributes:

Name Type Description
test_name str

Name of the test (e.g., "Glucose", "Hemoglobin")
test_code str

LOINC code for the test
value str

Measured value (numeric or text)
unit Optional[str]

Unit of measurement (e.g., "mg/dL", "g/dL"). Optional for coded/text values.
status str

Status of the result (e.g., "completed", "preliminary", "final")
effective_time date | datetime

Date and time the test was performed
value_type Optional[str]

Type of value - "PQ" (physical quantity), "CD" (coded), or "ST" (string). Defaults to "PQ" if unit is provided, otherwise "ST".
interpretation Optional[str]

Optional interpretation code (e.g., "N" for normal, "H" for high, "L" for low)
reference_range_low Optional[str]

Optional lower bound of reference range
reference_range_high Optional[str]

Optional upper bound of reference range
reference_range_unit Optional[str]

Optional unit for reference range (should match value unit)
Source code in ccdakit/protocols/result.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class ResultObservationProtocol(Protocol):
    """Protocol for a single lab result observation.

    Defines the interface that result observation objects must implement to be
    used with the ResultObservation builder.

    Attributes:
        test_name: Name of the test (e.g., "Glucose", "Hemoglobin")
        test_code: LOINC code for the test
        value: Measured value (numeric or text)
        unit: Unit of measurement (e.g., "mg/dL", "g/dL"). Optional for coded/text values.
        status: Status of the result (e.g., "completed", "preliminary", "final")
        effective_time: Date and time the test was performed
        value_type: Type of value - "PQ" (physical quantity), "CD" (coded), or "ST" (string).
                   Defaults to "PQ" if unit is provided, otherwise "ST".
        interpretation: Optional interpretation code (e.g., "N" for normal, "H" for high, "L" for low)
        reference_range_low: Optional lower bound of reference range
        reference_range_high: Optional upper bound of reference range
        reference_range_unit: Optional unit for reference range (should match value unit)
    """

    test_name: str
    test_code: str
    value: str
    unit: Optional[str]
    status: str
    effective_time: date | datetime
    value_type: Optional[str]
    interpretation: Optional[str]
    reference_range_low: Optional[str]
    reference_range_high: Optional[str]
    reference_range_unit: Optional[str]

ResultOrganizerProtocol

Bases: Protocol

Protocol for a group of related lab results (e.g., a lab panel).

Defines the interface for a result organizer that groups related test results.

Attributes:

Name Type Description
panel_name str

Name of the panel (e.g., "Complete Blood Count", "Basic Metabolic Panel")
panel_code str

LOINC code for the panel
status str

Status of the organizer (e.g., "completed", "active")
effective_time date | datetime

Date and time when the panel was collected/performed
results Sequence[ResultObservationProtocol]

Sequence of result observations in this panel
Source code in ccdakit/protocols/result.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class ResultOrganizerProtocol(Protocol):
    """Protocol for a group of related lab results (e.g., a lab panel).

    Defines the interface for a result organizer that groups related test results.

    Attributes:
        panel_name: Name of the panel (e.g., "Complete Blood Count", "Basic Metabolic Panel")
        panel_code: LOINC code for the panel
        status: Status of the organizer (e.g., "completed", "active")
        effective_time: Date and time when the panel was collected/performed
        results: Sequence of result observations in this panel
    """

    panel_name: str
    panel_code: str
    status: str
    effective_time: date | datetime
    results: Sequence[ResultObservationProtocol]

SmokingStatusProtocol

Bases: Protocol

Protocol for smoking status observation.

Defines the interface for smoking status objects that can be used with the SmokingStatusObservation builder.

This represents a "snapshot in time" observation of the patient's current smoking status as specified in Meaningful Use Stage 2 requirements.

Attributes:

Name Type Description
smoking_status str

Description of smoking status (e.g., "Current every day smoker", "Former smoker", "Never smoker", "Unknown if ever smoked")
code str

SNOMED CT code from Smoking Status Value Set (2.16.840.1.113883.11.20.9.38) Common codes: - 449868002: Current every day smoker - 428041000124106: Current some day smoker - 8517006: Former smoker - 266919005: Never smoker - 266927001: Unknown if ever smoked
date date | datetime

Date and time when smoking status was observed (point in time, not interval)
Source code in ccdakit/protocols/social_history.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class SmokingStatusProtocol(Protocol):
    """Protocol for smoking status observation.

    Defines the interface for smoking status objects that can be used with
    the SmokingStatusObservation builder.

    This represents a "snapshot in time" observation of the patient's current
    smoking status as specified in Meaningful Use Stage 2 requirements.

    Attributes:
        smoking_status: Description of smoking status (e.g., "Current every day smoker",
                       "Former smoker", "Never smoker", "Unknown if ever smoked")
        code: SNOMED CT code from Smoking Status Value Set (2.16.840.1.113883.11.20.9.38)
              Common codes:
              - 449868002: Current every day smoker
              - 428041000124106: Current some day smoker
              - 8517006: Former smoker
              - 266919005: Never smoker
              - 266927001: Unknown if ever smoked
        date: Date and time when smoking status was observed (point in time, not interval)
    """

    smoking_status: str
    code: str
    date: date | datetime

EncounterProtocol

Bases: Protocol

Protocol defining the interface for encounter data.

Represents healthcare encounters (visits, appointments, admissions, etc.). Used with EncounterActivity and EncountersSection builders.

Source code in ccdakit/protocols/encounter.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class EncounterProtocol(Protocol):
    """
    Protocol defining the interface for encounter data.

    Represents healthcare encounters (visits, appointments, admissions, etc.).
    Used with EncounterActivity and EncountersSection builders.
    """

    @property
    def encounter_type(self) -> str:
        """Encounter type/description (e.g., 'Office Visit', 'Emergency Room')."""
        ...

    @property
    def code(self) -> str:
        """
        Encounter type code.

        Should be from ValueSet EncounterTypeCode (2.16.840.1.113883.3.88.12.80.32).
        Common codes include CPT, SNOMED CT, or local codes.
        Example: '99213' (CPT code for office visit)
        """
        ...

    @property
    def code_system(self) -> str:
        """
        Code system for the encounter code.

        Examples: 'CPT-4', 'SNOMED CT', 'ActCode'
        """
        ...

    @property
    def date(self) -> date | datetime | None:
        """
        Date/time when the encounter occurred.

        Can be a date or datetime. Required for encounters.
        For ongoing encounters, this represents the start date.
        """
        ...

    @property
    def end_date(self) -> date | datetime | None:
        """
        End date/time of the encounter.

        Optional. If provided along with date, creates a time interval.
        If not provided, the encounter is considered a point in time.
        """
        ...

    @property
    def location(self) -> str | None:
        """
        Location where the encounter took place.

        Optional. Example: 'Community Health Hospital', 'Main Clinic'
        """
        ...

    @property
    def performer_name(self) -> str | None:
        """
        Name of the healthcare provider who performed the encounter.

        Optional. Example: 'Dr. John Smith'
        """
        ...

    @property
    def discharge_disposition(self) -> str | None:
        """
        Patient discharge disposition.

        Optional. Example: 'Home', 'Skilled Nursing Facility'
        Only applicable for inpatient encounters.
        """
        ...

Attributes

encounter_type property

Encounter type/description (e.g., 'Office Visit', 'Emergency Room').

code property

Encounter type code.

Should be from ValueSet EncounterTypeCode (2.16.840.1.113883.3.88.12.80.32). Common codes include CPT, SNOMED CT, or local codes. Example: '99213' (CPT code for office visit)

code_system property

Code system for the encounter code.

Examples: 'CPT-4', 'SNOMED CT', 'ActCode'

date property

Date/time when the encounter occurred.

Can be a date or datetime. Required for encounters. For ongoing encounters, this represents the start date.

end_date property

End date/time of the encounter.

Optional. If provided along with date, creates a time interval. If not provided, the encounter is considered a point in time.

location property

Location where the encounter took place.

Optional. Example: 'Community Health Hospital', 'Main Clinic'

performer_name property

Name of the healthcare provider who performed the encounter.

Optional. Example: 'Dr. John Smith'

discharge_disposition property

Patient discharge disposition.

Optional. Example: 'Home', 'Skilled Nursing Facility' Only applicable for inpatient encounters.