Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:06:05Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:36, 6 July 2026
Line 379:		Line 379:
	* <code>facility</code> controls scope: omit it for instance-wide, set it for facility-local. Address records by slug (<code>i-<slug></code> or <code>f-<facility_external_id>-<slug></code>); the parsed parts come back as <code>slug_config</code>.		* <code>facility</code> controls scope: omit it for instance-wide, set it for facility-local. Address records by slug (<code>i-<slug></code> or <code>f-<facility_external_id>-<slug></code>); the parsed parts come back as <code>slug_config</code>.
	* <code>code</code>, <code>names</code>, <code>storage_guidelines</code>, <code>definitional</code>, and <code>base_unit</code> carry their structure and value-set binding in the spec, not the model. <code>base_unit</code> is required.		* <code>code</code>, <code>names</code>, <code>storage_guidelines</code>, <code>definitional</code>, and <code>base_unit</code> carry their structure and value-set binding in the spec, not the model. <code>base_unit</code> is required.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:45Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Product Knowledge
|order=8
|introduced=3.0
|model=ProductKnowledge
|reference=References/Base models & conventions
}}

<code>ProductKnowledge</code> 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 <code>Product</code> 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>code</code>, <code>names</code>, <code>storage_guidelines</code>, <code>definitional</code>, and <code>base_unit</code> are opaque <code>JSONField</code>s 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: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/product_knowledge.py <code>care/emr/models/product_knowledge.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product_knowledge/spec.py <code>care/emr/resources/inventory/product_knowledge/spec.py</code>]
* Value sets: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product_knowledge/valueset.py <code>care/emr/resources/inventory/product_knowledge/valueset.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ProductKnowledge</code>
| Foundational, reusable definition of a product (medication, nutritional product, or consumable)
|}

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

== <code>ProductKnowledge</code> fields ==

=== Identity & scope ===

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

=== Naming ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ProductKnowledge|section=Naming|name=name|type=CharField(255)|notes=Primary display name (required in spec)}}
{{Field|model=ProductKnowledge|section=Naming|name=names|type=JSONField (list)|notes=Nullable; list of <code>ProductName { name_type: ProductNameTypes, name: str }</code>. <code>name_type</code> is bound to the <code>ProductNameTypes</code> enum, not a FHIR value set}}
{{Field|model=ProductKnowledge|section=Naming|name=names_cache|type=CharField(2048)|notes=Nullable; denormalized space-joined string of <code>name</code> plus every <code>names</code> entry, rebuilt on each <code>save()</code> to power search. Platform-maintained, absent from every spec — never set it from clients}}
|}

=== Coding & definition (JSON fields) ===

The model stores these as bare <code>JSONField</code>s; the spec enforces the shapes below.

{| class="wikitable"
|-
! Field
! Model type
! Spec type / shape
! Notes
|-
| <code>code</code>
| <code>JSONField</code> (dict)
| <code>Coding | None</code>
| Nullable; product code as a [[#coding
|-
| <code>base_unit</code>
| <code>JSONField</code> (dict)
| <code>ValueSetBoundCoding[CARE_UCUM_UNITS]</code>
| '''Required'''. A <code>Coding</code> bound to the UCUM units value set (<code>system-ucum-units</code>)
|-
| <code>names</code>
| <code>JSONField</code> (list)
| <code>list[ProductName] | None</code>
| See [[#productname
|-
| <code>storage_guidelines</code>
| <code>JSONField</code> (list)
| <code>list[StorageGuideline] | None</code>
| See [[#storageguideline
|-
| <code>definitional</code>
| <code>JSONField</code> (dict)
| <code>ProductDefinitionSpec | None</code>
| Type-specific definition payload. See [[#productdefinitionspec
|}

== Enums ==

=== <code>ProductTypeOptions</code> (<code>product_type</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>medication</code>
|-
| <code>nutritional_product</code>
|-
| <code>consumable</code>
|}

=== <code>ProductKnowledgeStatusOptions</code> (<code>status</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>active</code>
|-
| <code>retired</code>
|-
| <code>unknown</code>
|}

=== <code>ProductNameTypes</code> (<code>names[].name_type</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>trade_name</code>
|-
| <code>alias</code>
|-
| <code>original_name</code>
|-
| <code>preferred</code>
|}

=== <code>DrugCharacteristicCode</code> (<code>definitional.drug_characteristic[].code</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>imprint_code</code>
|-
| <code>size</code>
|-
| <code>shape</code>
|-
| <code>color</code>
|-
| <code>coating</code>
|-
| <code>scoring</code>
|-
| <code>logo</code>
|-
| <code>image</code>
|}

== Nested spec shapes ==

These are plain Pydantic <code>BaseModel</code>s in <code>spec.py</code>, not value-set bound unless noted.

=== <code>ProductName</code> ===

<code>names[]</code> — alternate names for the product.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=ProductName|name=name_type|type=ProductNameTypes|notes=yes}}
{{Field|model=ProductKnowledge|section=ProductName|name=name|type=str|notes=yes}}
|}

=== <code>StorageGuideline</code> ===

<code>storage_guidelines[]</code> — a storage note paired with a stability duration.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=StorageGuideline|name=note|type=str|notes=yes}}
{{Field|model=ProductKnowledge|section=StorageGuideline|name=stability_duration|type=DurationSpec { value: int, unit: Coding }|notes=yes}}
|}

=== <code>ProductDefinitionSpec</code> ===

<code>definitional</code> — type-specific definition payload.

{| class="wikitable"
|-
! Field
! Type
! Default
! Notes
{{Field|model=ProductKnowledge|section=ProductDefinitionSpec|name=dosage_form|type=ValueSetBoundCoding[MEDICATION_FORM_CODES] | None|notes=required (nullable)}}
{{Field|model=ProductKnowledge|section=ProductDefinitionSpec|name=intended_routes|type=list[Coding]|notes=<code>[]</code>}}
{{Field|model=ProductKnowledge|section=ProductDefinitionSpec|name=ingredients|type=list[ProductIngredient]|notes=<code>[]</code>}}
{{Field|model=ProductKnowledge|section=ProductDefinitionSpec|name=nutrients|type=list[ProductNutrient]|notes=<code>[]</code>}}
{{Field|model=ProductKnowledge|section=ProductDefinitionSpec|name=drug_characteristic|type=list[DrugCharacteristic]|notes=<code>[]</code>}}
|}

=== <code>ProductIngredient</code> ===

<code>definitional.ingredients[]</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=ProductIngredient|name=is_active|type=bool|notes=yes}}
{{Field|model=ProductKnowledge|section=ProductIngredient|name=substance|type=ValueSetBoundCoding[CARE_SUBSTANCE_VALUSET]|notes=yes}}
{{Field|model=ProductKnowledge|section=ProductIngredient|name=strength|type=ProductStrength|notes=yes}}
|}

=== <code>ProductNutrient</code> ===

<code>definitional.nutrients[]</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=ProductNutrient|name=item|type=ValueSetBoundCoding[CARE_NUTRIENTS_VALUESET]|notes=yes}}
{{Field|model=ProductKnowledge|section=ProductNutrient|name=amount|type=ProductStrength|notes=yes}}
|}

=== <code>ProductStrength</code> ===

Shared by <code>ProductIngredient.strength</code> and <code>ProductNutrient.amount</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=ProductStrength|name=ratio|type=Ratio { numerator: Quantity, denominator: Quantity }|notes=yes}}
{{Field|model=ProductKnowledge|section=ProductStrength|name=quantity|type=Quantity|notes=yes}}
|}

=== <code>DrugCharacteristic</code> ===

<code>definitional.drug_characteristic[]</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ProductKnowledge|section=DrugCharacteristic|name=code|type=DrugCharacteristicCode|notes=yes}}
{{Field|model=ProductKnowledge|section=DrugCharacteristic|name=value|type=str|notes=yes}}
|}

== Shared common types ==

=== <code>Coding</code> ===

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

{| class="wikitable"
|-
! Field
! Type
! Required
|-
| <code>system</code>
| <code>str | None</code>
| no
|-
| <code>version</code>
| <code>str | None</code>
| no
|-
| <code>code</code>
| <code>str</code>
| yes
|-
| <code>display</code>
| <code>str | None</code>
| no
|}

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

=== <code>Quantity</code> ===

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

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ProductKnowledge|section=Quantity|name=value|type=Decimal | None|notes=max 20 digits, 6 decimal places}}
{{Field|model=ProductKnowledge|section=Quantity|name=unit|type=Coding | None|notes=human-readable unit}}
{{Field|model=ProductKnowledge|section=Quantity|name=code|type=Coding | None|notes=machine-processable unit}}
{{Field|model=ProductKnowledge|section=Quantity|name=meta|type=dict | None|notes=}}
|}

<code>Ratio { numerator: Quantity, denominator: Quantity }</code> — both required.

== Resource specs (API schema) ==

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

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

=== Validation & bound value sets ===

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

=== Server-maintained behaviour ===

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

== Methods & save behaviour ==

=== <code>save()</code> side effects ===

<code>save()</code> rebuilds <code>names_cache</code> before persisting:

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

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

== API integration notes ==

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

{{Related}}

References/Product Knowledge - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed