generated: '2026-08-15'
method: derived
source: openapi/ribbon-health-api-openapi.json, openapi/h1-price-transparency-v2-openapi.json
note: >-
  Derived from OpenAPI paths and id-reference parameters (NPI + *_uuid). The v1 contract exposes no
  components.schemas, so v1 relationships are inferred from path structure and id fields. The Price
  Transparency v2 contract does carry response schemas, and it introduces a SECOND, incompatible id
  space: v2 carriers are string business ids (not v1 carrier UUIDs) and v2 locations accept either an
  integer location id or the location UUID. Treat v1 and v2 pricing as two graphs joined only through
  the procedure code, not through carrier identity.
entities:
- name: provider
  id: npi
  id_type: NPI
- name: location
  id: location_uuid
- name: insurance
  id: insurance_uuid
- name: specialty
  id: specialty_uuid
- name: procedure
  id: procedure_uuid
- name: organization
  id: organization_uuid
- name: clinical_area
  id: clinical_area_uuid
- name: condition
  id: condition_uuid
- name: treatment
  id: treatment_uuid
- name: provider_type
  id: provider_type_uuid
- name: location_type
  id: location_type_uuid
- name: tin
  id: tin_id
- name: carrier
  id: carrier_uuid
- name: filter
  id: filter_uuid
- name: virtual_care_platform
  id: virtual_care_platform_uuid
relationships:
- from: provider
  to: location
  type: has_many
  via: location_uuid
- from: provider
  to: specialty
  type: has_many
  via: specialty_uuid
- from: provider
  to: procedure
  type: has_many
  via: procedure_uuid
- from: provider
  to: clinical_area
  type: has_many
  via: clinical_area_uuid
- from: location
  to: insurance
  type: has_many
  via: insurance_uuid
- from: location
  to: organization
  type: has_many
  via: organization_uuid
- from: location
  to: clinical_area
  type: has_many
  via: clinical_area_uuid
- from: clinical_area
  to: condition
  type: has_many
  via: condition_uuid
- from: condition
  to: treatment
  type: has_many
  via: treatment_uuid
- from: carrier
  to: procedure
  type: has_many
  via: procedure_uuid
  context: price transparency negotiated rates
- from: care_cluster
  to: v2_procedure
  type: has_many
  via: procedure_code
  context: price transparency v2 care-episode bundles (included_procedures / missing_procedures)
- from: v2_location
  to: v2_procedure
  type: has_many
  via: procedure_code
  context: price transparency v2 location-scoped negotiated rates
- from: v2_location
  to: care_cluster
  type: has_many
  via: care_cluster_id
  context: price transparency v2 location-scoped bundle prices
- from: v2_carrier
  to: v2_location
  type: has_many
  via: carrier_id
  context: price transparency v2 carrier filter (string business id, NOT the v1 carrier_uuid)
v2_entities:
- name: v2_procedure
  id: procedure_code
  id_type: CPT (or other procedure code)
  source: openapi/h1-price-transparency-v2-openapi.json
- name: care_cluster
  id: care_cluster_id
  note: curated group of related procedures representing a care episode, e.g. JOINT_REPLACEMENT
  source: openapi/h1-price-transparency-v2-openapi.json
- name: v2_carrier
  id: carrier_id
  id_type: string business id
  note: NOT interchangeable with the v1 carrier_uuid
  source: openapi/h1-price-transparency-v2-openapi.json
- name: v2_location
  id: location_id
  id_type: integer location id OR location UUID
  source: openapi/h1-price-transparency-v2-openapi.json