References/Product Knowledge

referencedefinitionsCARE 3.0+

Definitions

Concepts

Questionnaire

Response Template Value Set Observation Definition Specimen Definition Activity Definition Charge Item Definition

Product Knowledge

References

Questionnaire

Response Template Value Set Observation Definition Specimen Definition Activity Definition Charge Item Definition

Product Knowledge

ProductKnowledge is the reusable definition of a product — its coding, base presentation unit, ingredients and nutrients, drug characteristics, and storage rules. Define it once and every concrete Product points back to it instead of carrying duplicate data. A definition is either instance-wide or scoped to a single facility.

The Django model is only the storage layer: code, names, storage_guidelines, definitional, and base_unit are opaque JSONFields whose real structure lives in the Pydantic resource specs. Every enum, nested JSON shape, validation rule, and read/write difference below comes from those specs.

Source:

• Model: [https://github.com/ohcnetwork/care/blob/develop/care/emr/models/product_knowledge.py care/emr/models/product_knowledge.py]
• Spec: [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product_knowledge/spec.py care/emr/resources/inventory/product_knowledge/spec.py]
• Value sets: [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product_knowledge/valueset.py care/emr/resources/inventory/product_knowledge/valueset.py]

Models

Model	Purpose
ProductKnowledge	Foundational, reusable definition of a product (medication, nutritional product, or consumable)

ProductKnowledge extends SlugBaseModel, which extends EMRBaseModel (the shared base providing external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON). SlugBaseModel sets FACILITY_SCOPED = True and adds the slug helpers calculate_slug and parse_slug, so a record is addressable by an instance slug (i-<slug>) or a facility slug (f-<facility_external_id>-<slug>).

ProductKnowledge fields

Identity & scope

Field	Type	Notes
facility	FK → facility.Facility	PROTECT, nullable. Null means an instance-level definition; set means facility-scoped. Excluded from the spec base (__exclude__ = ["facility"]); set on write via a facility UUID, surfaced on read as is_instance_level
slug	CharField(255)	Slug value; combined with facility to form the addressable slug. Set server-side from slug_value on write
alternate_identifier	CharField(255)	Nullable; secondary external identifier
status	CharField(255)	Lifecycle status. Spec-constrained to ProductKnowledgeStatusOptions (required)
product_type	CharField(255)	Product category. Spec-constrained to ProductTypeOptions (required) {{Field|model=ProductKnowledge|section=Identity & scope|name=category|type=FK → emr.ResourceCategory|notes=CASCADE, nullable; classifies the product into a [[References/Resource Category}}

Naming

Field	Type	Notes
name	CharField(255)	Primary display name (required in spec)
names	JSONField (list)	Nullable; list of ProductName { name_type: ProductNameTypes, name: str }. name_type is bound to the ProductNameTypes enum, not a FHIR value set
names_cache	CharField(2048)	Nullable; denormalized space-joined string of name plus every names entry, rebuilt on each save() to power search. Platform-maintained, absent from every spec — never set it from clients

Coding & definition (JSON fields)

The model stores these as bare JSONFields; the spec enforces the shapes below.

Field	Model type	Spec type / shape	Notes
code	JSONField (dict)	None	Nullable; product code as a [[#coding
base_unit	JSONField (dict)	ValueSetBoundCoding[CARE_UCUM_UNITS]	Required. A Coding bound to the UCUM units value set (system-ucum-units)
names	JSONField (list)	None	See [[#productname
storage_guidelines	JSONField (list)	None	See [[#storageguideline
definitional	JSONField (dict)	None	Type-specific definition payload. See [[#productdefinitionspec

Enums

ProductTypeOptions (product_type)

Value
medication
nutritional_product
consumable

ProductKnowledgeStatusOptions (status)

Value
draft
active
retired
unknown

ProductNameTypes (names[].name_type)

Value
trade_name
alias
original_name
preferred

DrugCharacteristicCode (definitional.drug_characteristic[].code)

Value
imprint_code
size
shape
color
coating
scoring
logo
image

Nested spec shapes

These are plain Pydantic BaseModels in spec.py, not value-set bound unless noted.

ProductName

names[] — alternate names for the product.

Field	Type	Required	Notes
name_type	ProductNameTypes	yes
name	str	yes

StorageGuideline

storage_guidelines[] — a storage note paired with a stability duration.

Field	Type	Required	Notes
note	str	yes
stability_duration	DurationSpec { value: int, unit: Coding }	yes

ProductDefinitionSpec

definitional — type-specific definition payload.

Field	Type	Default	Notes
dosage_form	ValueSetBoundCoding[MEDICATION_FORM_CODES]	required (nullable)
intended_routes	list[Coding]	[]
ingredients	list[ProductIngredient]	[]
nutrients	list[ProductNutrient]	[]
drug_characteristic	list[DrugCharacteristic]	[]

ProductIngredient

definitional.ingredients[].

Field	Type	Required	Notes
is_active	bool	yes
substance	ValueSetBoundCoding[CARE_SUBSTANCE_VALUSET]	yes
strength	ProductStrength	yes

ProductNutrient

definitional.nutrients[].

Field	Type	Required	Notes
item	ValueSetBoundCoding[CARE_NUTRIENTS_VALUESET]	yes
amount	ProductStrength	yes

ProductStrength

Shared by ProductIngredient.strength and ProductNutrient.amount.

Field	Type	Required	Notes
ratio	Ratio { numerator: Quantity, denominator: Quantity }	yes
quantity	Quantity	yes

DrugCharacteristic

definitional.drug_characteristic[].

Field	Type	Required	Notes
code	DrugCharacteristicCode	yes
value	str	yes

Shared common types

Coding

From care/emr/resources/common/coding.py (extra="forbid").

Field	Type	Required
system	None	no
version	None	no
code	str	yes
display	None	no

A ValueSetBoundCoding[<slug>] is a Coding subclass that additionally validates code against the named value set on deserialization.

Quantity

From care/emr/resources/common/quantity.py (extra="forbid").

Field	Type	Notes
value	Decimal	max 20 digits, 6 decimal places
unit	Coding	human-readable unit
code	Coding	machine-processable unit
meta	dict

Ratio { numerator: Quantity, denominator: Quantity } — both required.

Resource specs (API schema)

Every spec builds on EMRResource (care/emr/resources/base.py), which provides serialize (DB → Pydantic), de_serialize (Pydantic → DB), and the perform_extra_serialization / perform_extra_deserialization hooks. EMRResource.serialize copies only non-FK database fields that are declared spec fields and not in __exclude__.

Spec class	Role	Adds / behaviour
BaseProductKnowledgeSpec	shared base	__exclude__ = ["facility"]. Fields: id, alternate_identifier, status, product_type, code, base_unit (required, UCUM-bound), name, names, storage_guidelines, definitional
ProductKnowledgeUpdateSpec	write · update	None (resource-category slug) and slug_value: SlugType (required). On deserialize, resolves category via ResourceCategory.objects.get(slug=...) and sets obj.slug = self.slug_value
ProductKnowledgeWriteSpec	write · create	None. On deserialize, runs the update-spec logic, then resolves facility via Facility.objects.get(external_id=...) when supplied
ProductKnowledgeReadSpec	read · detail/list	None, slug_config: dict, slug: str. On serialize, sets id = external_id, is_instance_level = not facility_id, serializes category via ResourceCategoryReadSpec, and sets slug_config = parse_slug(slug)

Validation & bound value sets

• status ∈ ProductKnowledgeStatusOptions and product_type ∈ ProductTypeOptions, both required.
• base_unit is required and bound to CARE_UCUM_UNITS (system-ucum-units, system http://unitsofmeasure.org).
• definitional.dosage_form is bound to MEDICATION_FORM_CODES; ingredients[].substance to CARE_SUBSTANCE_VALUSET; nutrients[].item to CARE_NUTRIENTS_VALUESET. code and intended_routes stay free Codings.
• slug_value uses SlugType: 5–50 chars, URL-safe (^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$), starting and ending alphanumeric.
• category on write is a slug string; an unknown slug raises DoesNotExist from .get(...).

Server-maintained behaviour

• facility never flows through the generic field loop (it sits in __exclude__); only ProductKnowledgeWriteSpec (create) sets it, from the facility UUID.
• slug is set server-side from slug_value; names_cache is rebuilt in the model's save() (see below).
• On read, is_instance_level, slug_config, and the serialized category are computed in perform_extra_serialization — none are stored columns.

Methods & save behaviour

save() side effects

save() rebuilds names_cache before persisting:

1. names_cache is reset to "<name> ".
2. For each entry in names, the entry's name (dict key or attribute) is appended, space-separated.
3. super().save() persists the record, including the slug logic inherited from SlugBaseModel.

names_cache is platform-maintained — write to name and names instead of setting it directly.

API integration notes

• Exposed through Care's REST API; aligns with the FHIR MedicationKnowledge and NutritionProduct concepts.
• product_type decides what definitional means (medication, nutritional_product, or consumable).
• facility controls scope: omit it for instance-wide, set it for facility-local. Address records by slug (i-<slug> or f-<facility_external_id>-<slug>); the parsed parts come back as slug_config.
• code, names, storage_guidelines, definitional, and base_unit carry their structure and value-set binding in the spec, not the model. base_unit is required.

Definitions

Concepts

Questionnaire · Response Template · Value Set · Obs Definition · Specimen Definition · Activity Definition · Charge Item Definition · Product Knowledge

References

Questionnaire · Response Template · Value Set · Obs Definition · Specimen Definition · Activity Definition · Charge Item Definition · Product Knowledge

Related

Pages that link here:

• Concepts/Product Knowledge

• Reference: References/Base models & conventions

Open Healthcare Network's flagship product: an open-source, FHIR-native electronic medical record (EMR) and healthcare operating system.

Fast Healthcare Interoperability Resources — an HL7 standard for exchanging healthcare data. CARE is built on FHIR R5.

Unified Code for Units of Measure — a standard for encoding measurement units in health data.