@nexalink/coding-contracts 0.2.0 → 0.4.0

package/schemas/coding-decision.schema.json

@@ -0,0 +1,430 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/coding-decision.schema.json",
+  "title": "CodingDecision",
+  "description": "The canonical, reconstructable decision for a CodingCase. caseRef is an analytics-safe reference (the case's analyticsId or a runtime opaque reference) and never a direct identifier. provenance pins the pack, model, terminology, rules, and schema versions needed to replay every recommendation.",
+  "version": "1.0.0",
+  "x-wire-version": "coding-decision-v1",
+  "x-wire-constant": "CODING_DECISION_SCHEMA_VERSION",
+  "x-code": "coding_decision",
+  "x-keys-code": "coding_decision_keys",
+  "x-semantic": [
+    {
+      "rule": "reconstructable_provenance",
+      "on": "lineDecisions",
+      "code": "decision_provenance_replay"
+    }
+  ],
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "decisionId",
+    "caseRef",
+    "disposition",
+    "humanReviewRequired",
+    "rationale",
+    "lineDecisions",
+    "provenance"
+  ],
+  "properties": {
+    "decisionId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "x-code": "decision_id"
+    },
+    "caseRef": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "x-code": "decision_case_ref"
+    },
+    "disposition": {
+      "type": "string",
+      "enum": ["review_required", "abstain", "escalate"],
+      "x-code": "decision_disposition"
+    },
+    "humanReviewRequired": {
+      "type": "boolean",
+      "const": true,
+      "x-code": "decision_human_review_required"
+    },
+    "rationale": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "x-strip-nonempty": true,
+      "x-code": "decision_rationale"
+    },
+    "overallConfidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "x-code": "decision_overall_confidence"
+    },
+    "lineDecisions": {
+      "type": "array",
+      "maxItems": 100,
+      "x-code": "decision_lines",
+      "items": {
+        "$ref": "coding-decision-line.schema.json"
+      }
+    },
+    "facts": {
+      "type": "array",
+      "maxItems": 50,
+      "x-code": "decision_facts",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["factId", "statement"],
+        "x-code": "decision_fact",
+        "x-keys-code": "decision_fact_keys",
+        "properties": {
+          "factId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 60,
+            "x-code": "decision_fact_id"
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "x-strip-nonempty": true,
+            "x-code": "decision_fact_statement"
+          },
+          "evidenceRefs": {
+            "type": "array",
+            "maxItems": 10,
+            "x-code": "decision_fact_evidence_refs",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "x-code": "decision_fact_evidence_refs"
+            }
+          }
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "maxItems": 30,
+      "x-code": "decision_gaps",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gapId", "type", "description", "severity"],
+        "x-code": "decision_gap",
+        "x-keys-code": "decision_gap_keys",
+        "properties": {
+          "gapId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 60,
+            "x-code": "decision_gap_id"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "missing_documentation",
+              "unsupported_scope",
+              "insufficient_evidence",
+              "policy_conflict",
+              "terminology_unavailable",
+              "other"
+            ],
+            "x-code": "decision_gap_type"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000,
+            "x-strip-nonempty": true,
+            "x-code": "decision_gap_description"
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "blocking"],
+            "x-code": "decision_gap_severity"
+          }
+        }
+      }
+    },
+    "conflicts": {
+      "type": "array",
+      "maxItems": 20,
+      "x-code": "decision_conflicts",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["conflictId", "type", "summary"],
+        "x-code": "decision_conflict",
+        "x-keys-code": "decision_conflict_keys",
+        "properties": {
+          "conflictId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 60,
+            "x-code": "decision_conflict_id"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "payer_vs_national",
+              "plan_vs_contract",
+              "terminology_period",
+              "rule_vs_rule",
+              "model_vs_rule",
+              "other"
+            ],
+            "x-code": "decision_conflict_type"
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000,
+            "x-strip-nonempty": true,
+            "x-code": "decision_conflict_summary"
+          },
+          "references": {
+            "type": "array",
+            "maxItems": 10,
+            "x-code": "decision_conflict_references",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120,
+              "x-code": "decision_conflict_references"
+            }
+          }
+        }
+      }
+    },
+    "evidenceItems": {
+      "type": "array",
+      "maxItems": 40,
+      "x-code": "decision_evidence_items",
+      "items": {
+        "$ref": "coding-evidence.schema.json"
+      }
+    },
+    "ruleTraces": {
+      "type": "array",
+      "maxItems": 50,
+      "x-code": "decision_rule_traces",
+      "items": {
+        "$ref": "coding-rule-result.schema.json"
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "decisionSchemaVersion",
+        "caseSchemaVersion",
+        "pack",
+        "model",
+        "terminology",
+        "rules",
+        "generatedAt"
+      ],
+      "x-code": "decision_provenance",
+      "x-keys-code": "decision_provenance_keys",
+      "properties": {
+        "decisionSchemaVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40,
+          "x-code": "decision_provenance_decision_schema_version"
+        },
+        "caseSchemaVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40,
+          "x-code": "decision_provenance_case_schema_version"
+        },
+        "pack": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["packId", "packVersion"],
+          "x-code": "decision_provenance_pack",
+          "x-keys-code": "decision_provenance_pack_keys",
+          "properties": {
+            "packId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120,
+              "x-code": "decision_provenance_pack_id"
+            },
+            "packVersion": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40,
+              "x-code": "decision_provenance_pack_version"
+            }
+          }
+        },
+        "model": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["modelId", "modelVersion"],
+          "x-code": "decision_provenance_model",
+          "x-keys-code": "decision_provenance_model_keys",
+          "properties": {
+            "modelId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120,
+              "x-code": "decision_provenance_model_id"
+            },
+            "modelVersion": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40,
+              "x-code": "decision_provenance_model_version"
+            }
+          }
+        },
+        "terminology": {
+          "type": "array",
+          "maxItems": 20,
+          "x-code": "decision_provenance_terminology",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["system", "editionVersion", "licenseApproved"],
+            "x-code": "decision_provenance_terminology_item",
+            "x-keys-code": "decision_provenance_terminology_item_keys",
+            "properties": {
+              "system": {
+                "type": "string",
+                "enum": [
+                  "ICD-10-CM",
+                  "ICD-10-PCS",
+                  "CPT",
+                  "HCPCS",
+                  "NDC",
+                  "CDT",
+                  "REVENUE_CODE",
+                  "DRG",
+                  "MODIFIERS",
+                  "OTHER"
+                ],
+                "x-code": "decision_provenance_terminology_system"
+              },
+              "editionVersion": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40,
+                "x-code": "decision_provenance_terminology_edition"
+              },
+              "licenseApproved": {
+                "type": "boolean",
+                "x-code": "decision_provenance_terminology_license"
+              }
+            }
+          }
+        },
+        "rules": {
+          "type": "array",
+          "maxItems": 30,
+          "x-code": "decision_provenance_rules",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["ruleId", "ruleVersion"],
+            "x-code": "decision_provenance_rule",
+            "x-keys-code": "decision_provenance_rule_keys",
+            "properties": {
+              "ruleId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "x-code": "decision_provenance_rule_id"
+              },
+              "ruleVersion": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40,
+                "x-code": "decision_provenance_rule_version"
+              }
+            }
+          }
+        },
+        "retrievalCorpus": {
+          "type": "object",
+          "additionalProperties": false,
+          "x-code": "decision_provenance_corpus",
+          "x-keys-code": "decision_provenance_corpus_keys",
+          "properties": {
+            "corpusId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120,
+              "x-code": "decision_provenance_corpus_id"
+            },
+            "corpusVersion": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120,
+              "x-code": "decision_provenance_corpus_version"
+            }
+          }
+        },
+        "generatedAt": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
+          "format": "date-time",
+          "maxLength": 64,
+          "x-code": "decision_provenance_generated_at"
+        }
+      }
+    },
+    "reviewerAction": {
+      "$ref": "coding-reviewer-action.schema.json"
+    },
+    "extensions": {
+      "type": "array",
+      "maxItems": 25,
+      "x-code": "decision_extensions",
+      "items": {
+        "$ref": "coding-extension.schema.json"
+      }
+    }
+  },
+  "if": {
+    "properties": {
+      "disposition": {
+        "const": "review_required"
+      }
+    },
+    "required": ["disposition"]
+  },
+  "then": {
+    "properties": {
+      "lineDecisions": {
+        "minItems": 1
+      },
+      "provenance": {
+        "properties": {
+          "terminology": {
+            "minItems": 1
+          },
+          "rules": {
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "x-code": "decision_review_required_lines"
+  },
+  "else": {
+    "properties": {
+      "lineDecisions": {
+        "maxItems": 0
+      }
+    },
+    "x-code": "decision_disposition_lines"
+  }
+}

package/schemas/coding-evidence.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/coding-evidence.schema.json",
+  "title": "CodingEvidence",
+  "description": "One typed, traced evidence item attached to a decision. Every item carries source, scope, version, effective period, and a stable identifier so reviews can be reconstructed. Licensed terminology content is never distributed through evidence excerpts.",
+  "version": "1.0.0",
+  "x-wire-version": "coding-evidence-v1",
+  "x-wire-constant": "CODING_EVIDENCE_SCHEMA_VERSION",
+  "x-code": "evidence",
+  "x-keys-code": "evidence_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "evidenceId",
+    "type",
+    "source",
+    "sourceVersion",
+    "scope",
+    "effectiveFrom",
+    "stableId",
+    "excerpt",
+    "retrievedAt"
+  ],
+  "properties": {
+    "evidenceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "x-code": "evidence_id"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "clinical",
+        "coding_guideline",
+        "payer_policy",
+        "plan_policy",
+        "contract_configuration",
+        "terminology_validity",
+        "rule_execution"
+      ],
+      "x-code": "evidence_type"
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "x-strip-nonempty": true,
+      "x-code": "evidence_source"
+    },
+    "sourceVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "x-code": "evidence_source_version"
+    },
+    "publisher": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "x-code": "evidence_publisher"
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["national", "payer", "plan", "contract", "tenant"],
+      "x-code": "evidence_scope"
+    },
+    "effectiveFrom": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "format": "date",
+      "x-code": "evidence_effective_from"
+    },
+    "effectiveTo": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "format": "date",
+      "x-code": "evidence_effective_to"
+    },
+    "stableId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "x-code": "evidence_stable_id"
+    },
+    "excerpt": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "x-strip-nonempty": true,
+      "x-code": "evidence_excerpt"
+    },
+    "retrievedAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "format": "date",
+      "x-code": "evidence_retrieved_at"
+    }
+  }
+}

package/schemas/coding-extension.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/coding-extension.schema.json",
+  "title": "CodingExtension",
+  "description": "A namespaced, bounded extension attached to a CodingCase or CodingDecision. Extensions carry pack-specific data without turning the shared envelope into an unbounded bag of specialty fields. Namespace ownership follows reverse-domain convention; Nexalink reserves com.nexalink and org.nexalink.",
+  "version": "1.0.0",
+  "x-wire-version": "coding-extension-v1",
+  "x-wire-constant": "CODING_EXTENSION_SCHEMA_VERSION",
+  "x-code": "extension",
+  "x-keys-code": "extension_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["namespace", "schemaVersion", "payload"],
+  "properties": {
+    "namespace": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+([._-][a-z0-9]+)*$",
+      "minLength": 3,
+      "maxLength": 160,
+      "x-code": "extension_namespace"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 40,
+      "x-code": "extension_schema_version"
+    },
+    "payload": {
+      "type": "object",
+      "maxProperties": 50,
+      "x-code": "extension_payload",
+      "x-keys-code": "extension_payload",
+      "properties": {}
+    }
+  }
+}

package/schemas/coding-reviewer-action.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/coding-reviewer-action.schema.json",
+  "title": "CodingReviewerAction",
+  "description": "Attributable human-review disposition appended to an otherwise immutable decision. A decision plus its reviewer actions remains replayable: original and reviewer versions are both preserved. Review outcome categories are reviewer-adjudicated observations and never inferred from payment, code, or reimbursement changes.",
+  "version": "1.1.0",
+  "x-wire-version": "coding-reviewer-action-v1",
+  "x-wire-constant": "CODING_REVIEWER_ACTION_SCHEMA_VERSION",
+  "x-code": "reviewer_action",
+  "x-keys-code": "reviewer_action_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["reviewerId", "action", "occurredAt"],
+  "properties": {
+    "reviewerId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "x-code": "reviewer_action_id"
+    },
+    "reviewerRole": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "x-code": "reviewer_action_role"
+    },
+    "action": {
+      "type": "string",
+      "enum": ["approved", "approved_with_changes", "rejected", "escalated"],
+      "x-code": "reviewer_action_type"
+    },
+    "resolutionCode": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "x-code": "reviewer_action_resolution_code"
+    },
+    "reviewOutcomeCategory": {
+      "type": "string",
+      "enum": [
+        "unsupported_or_excessive",
+        "missed_supported",
+        "unchanged_supported",
+        "missing_evidence",
+        "escalation"
+      ],
+      "x-code": "reviewer_action_outcome_category"
+    },
+    "notes": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "x-strip-nonempty": true,
+      "x-code": "reviewer_action_notes"
+    },
+    "occurredAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
+      "format": "date-time",
+      "maxLength": 64,
+      "x-code": "reviewer_action_occurred_at"
+    }
+  }
+}