# Case schema and import contract

Owner: Rods Project Team  
Status: Active  
Last Updated: 2026-04-16  
Version: 0.2.0

## Canonical input

- Root: `INPRoot/Case`  
- Example: `data/cases/base-case.xml`

## Parsed fields used by solver (SI after `xmlParser`)

### Core (required)

- `PumpingSpeed` — SPM  
- `PumpDepth` — MD to pump (case units → m)  
- `MeasuredDepthArray`, `InclinationFromVerticalArray` — trajectory (`:` separated)  
- `AzimuthFromNorthArray` — optional for vertical; required for full 3D curvature in API validation  

### Friction / contact

- `RodFrictionCoefficient` — Coulomb \(\mu\) baseline  
- `StuffingBoxFriction`, `PumpFriction` — case force units → N  
- `MoldedGuideFrictionRatio`, `WheeledGuideFrictionRatio`, `OtherGuideFrictionRatio` — scale effective \(\mu\) along string (`heuristic` blend)  

### Rod string / materials

- `TaperDiameterArray`, `TaperLengthArray`, `TaperModulusArray`, `TaperWeightArray`, `TaperMTSArray`  
- `RodTypeArray` — maps to steel vs fiberglass density/modulus defaults when modulus not set  
- `TubingAnchorLocation`  
- `SinkerBarDiameter`, `SinkerBarLength`  
- `RodGuideTypeArray`, `RodGuideWeightArray` — metadata / future contact  

### Damping

- `UpStrokeDampingFactor`, `DownStrokeDampingFactor`  
- `NonDimensionalFluidDamping` — Gibbs-style dimensionless damping input  

### Pump / fluid (valve + buoyancy helpers)

- `PumpDiameter`, `PumpIntakePressure`, `PumpFillageOption`, `PercentPumpFillage`  
- `WaterCut`, `WaterSpecGravity`, `FluidLevelOilGravity`, `TubingGradient`, `TubingSize`  
- `PercentageUpstrokeTime`, `PercentageDownstrokeTime`  
- `PumpingUnitID`, `PumpingSpeedOption` — metadata for future kinematics  

### Units

- `UnitsSelection` — drives internal conversion (see `units.md`)  

## Unknown / unsupported field policy

- Parse immediate `Case` children into `rawFields`.  
- Fields outside the MVP subset used for **solver** remain in `unsupportedFields` but are **preserved** in API responses.  
- Do not silently drop imported tags.

## Validation rules

- Required for parse: `PumpingSpeed`, `PumpDepth`, `MeasuredDepthArray`, `InclinationFromVerticalArray`.  
- Trajectory arrays must have equal lengths after parse.  
- Numeric parse failures throw explicit errors.