Managed SLD proposal reference

This page defines version 1 of the public semantic proposal used by managed SLD builds. All JSON objects are strict unless a field is explicitly described as a property map.

Top-level proposal

source.identity is required and contains 1–200 characters. source.sha256 is optional and, when present, must be the lowercase 64-character SHA-256 calculated by the agent. EKX does not calculate or verify it. source.evidence contains at most 100 entries:

{
  "ref": "panel-schedule-a",
  "page": 4,
  "locator": "Panel A feeder schedule",
  "explanation": "Agent-supplied conductor interpretation"
}

ref is required. page is an optional positive integer. locator and explanation are optional text. These fields are references only; do not embed PDF content or base64 data.

For a new project, use:

{
  "kind": "new_project",
  "name": "Plant distribution",
  "codeBook": "NEC",
  "codeEditionYear": 2026
}

codeBook may be NEC or CEC. For a merge, the build already fixes the target project, so use only { "kind": "existing_project" }.

autoSizingMode chooses whether the new project is sized once it is created. Ask the user before submitting:

In apply, a cable conductor size that sizing fills is not listed in compiledResult.limitations. A cable with catalogIntent leave_unresolved stays out of sizing in every mode: it keeps no family and no size until the user chooses one, and its size stays a limitation. Sizing a merge into an existing project is not part of the build; the project's own mode applies to later edits.

Field states

Every component property uses one of four states:

Omission is different from unresolved. Omit a property only when the agent has not classified it. EKX returns a blocking issue when an omitted field requires a decision. An explicitly unresolved study input can allow the diagram to become ready while listing the unavailable studies or sizing operations.

Some optional properties require a concrete value when you include them. For example, inService, protection-device operatingState, and cable parallelRuns cannot remain unresolved. EKX returns a blocking decision asking you to supply the value. It does not offer mark_unresolved for these fields. Omitted optional properties retain their usual default or merge behavior; nullable study inputs can still remain unresolved.

Harmonic models

harmonicSettings accepts a structured, versioned model on loads, motor controllers, cables, transformers and utility supplies. A capacitor bank is its own capacitor_bank component and carries its rating as ordinary properties, not harmonicSettings. It is the only property that accepts these objects; other properties keep their scalar contracts. Supply the complete typed model, including all 49 orders for an installed source spectrum, rather than a JSON string.

For example, a capacitor_bank component carries its rating as properties:

{
  "ref": "cap-1",
  "componentType": "capacitor_bank",
  "name": "CAP-1",
  "properties": {
    "ratedKvar": { "state": "supplied", "value": 50 },
    "ratedKv": { "state": "supplied", "value": 0.48 },
    "ratedFrequencyHz": { "state": "supplied", "value": 60 },
    "connection": { "state": "supplied", "value": "delta" },
    "steps": { "state": "supplied", "value": 2 },
    "energizedSteps": { "state": "supplied", "value": 1 },
    "lossWattsPerKvar": { "state": "supplied", "value": 0.5 }
  },
  "evidenceRefs": []
}

The model must match its owning equipment subtype. Omitted drive and UPS models receive their sourced defaults automatically; missing manufacturer data does not require a clarification or block a drive's harmonic result. Existing-project context and merge fingerprints preserve the complete installed model. See harmonic studies for the supported scope and result bases.

Component schema

Every component has this shape:

{
  "ref": "main-bus",
  "componentType": "bus",
  "name": "MAIN BUS",
  "existingComponentId": "optional-existing-uuid",
  "properties": {
    "baseKv": { "state": "supplied", "value": 13.8 }
  },
  "layoutParentRef": "utility",
  "branchOrder": 0,
  "evidenceRefs": ["service-riser"]
}

ref is the stable proposal-local identity and contains 1–160 characters. name contains 1–200 characters and may contain the source wording. For new components, EKX preserves source tags of at most 12 characters. Conventional panel labels use PANEL <tag>, so Existing Panel LPO becomes PANEL LPO; a tag too long for the prefix, such as Panel MAIN F/A, keeps the tag alone. Derived cable names use the concise tag without the PANEL prefix. Otherwise EKX generates a short engineering tag and retains the submitted name in description. Transformers use T1, T2, and so on. Capacitor banks use the prefix CAP. Cables use the equipment at both ends, looking through breakers, switches, and fuses, such as CBL_T1_MDP; when that does not fit they use the equipment they feed, such as CBL_MCCLA, and then CBL1, CBL2, and so on. Breakers, switches, and fuses use the equipment they feed, such as CB_2100 or SW_NEWELEV, and then CB1, SW1, and so on. Duplicate names add _2, _3, and so on. existingComponentId is valid only when intentionally targeting an existing merge component. layoutParentRef and zero-based branchOrder describe hierarchy and sibling order, not coordinates. Evidence references must name entries in source.evidence.

For a bus with multiple incoming supplies, set layoutParentRef to the component that should group it horizontally. EKX retains every electrical connection, sizes the bus for all connected terminals, and leaves at least 50 px of clear vertical space along every source-to-load connection. An omitted parent remains ambiguous when several sources feed the same component, except a transfer switch fed at its throws. Cyclic placement constraints or connections that require moving fixed existing equipment block the build.

Supported componentType values are bus, cable, transformer, generator, load, capacitor_bank, utility_feed, protection_device, and motor_control_device.

Required and study-dependent properties

Utilities, generators, transformer windings and buses connected without a transformer between them must share one voltage. EKX never changes a supplied voltage to make them agree. When they disagree, the build returns the blocking issue VOLTAGE_ZONE_CONFLICT, which names one component at each voltage and any transfer switch that joins them, and nothing is applied. Correct the value or connection that disagrees with the source drawing and revise the proposal. A protection or motor-control device's ratedVoltage left out of the proposal is filled from its connected voltage.

Utility input methods require these study fields:

Units

Use base engineering units in the semantic value. Do not send display-unit objects.

Supported optional properties

Voltage-drop declarations use the values in the project input reference. Supply voltageDropCircuitVoltageV in volts. Mark unknown declarations unresolved; an imported diagram can remain editable while mandatory sizing is blocked. A motor nameplate confirmation must include the matching positive fullLoadAmps in the same proposal. These declarations are project facts and cannot be filled by a generic ekx_typical assumption.

Unknown property names are reported as deterministic issues. Supported optional names are:

• bus: ratedPeakWithstandCurrent, ratedShortTimeSymmetricalShortCircuitCurrent,

ratedShortTimeAsymmetricalShortCircuitCurrent, isSlackBus, inService, includeInShortCircuit, includeInArcFlash, bracingDurationCycles, mainBusRatingAmps, verticalBusRatingAmps, horizontalBusRatingAmps, busType, configuration, phaseConfiguration, enclosureType, mainProtectiveDeviceIsolated, electrodeGapMm, workingDistanceMm, heightMm, widthMm, depthMm, and description. A null or omitted mainProtectiveDeviceIsolated takes the equipment class default.

• cable: preferredLengthUnit, installationType, ambientInstallTemperature,

currentCarryingConductors, parallelRuns, conductorsPerRun, terminationTempRatingC, racewayType, voltageDropLimitPercent, voltageDropCircuitKind, voltageDropCircuitVoltageV, bondingMeans, bondingLocation, cableTrayFillType, cableTrayType, cableTrayLayering, bondingConductorSize, bondingConductorSizeUnit, bondingConductorMaterial, bondingConductorQuantity, conduitSize, conduitSizeUnit, conduitQuantity, inService, and description.

• transformer: transformerType, tertiaryVoltage, useTypicalImpedance, noLoadLossesKw,

loadLossesKw, transformerConstruction, coolingType, tapChangerType, tapRange, tapPosition, tapMin, tapMax, tapStep, inService, primaryCurrent, secondaryCurrent, and description.

useTypicalImpedance does not by itself approve an engineering assumption in a managed proposal. Use { "state": "assumed", "basis": "ekx_typical" } on each transformer field the engineer approved.

• generator: generatorType, voltageSetByUser, ratedPowerMw, powerFactor, statorResistancePu, xd, xdPrime,

xq, xqPrime, xqDoublePrime, xl, tdoPrime, tdoDoublePrime, tqoPrime, inertiaConstant, dampingCoefficient, fuelType, efficiency, minimumLoad, governorType, exciterType, avrType, x0, x2, groundingType, groundingResistanceOhms, groundingReactanceOhms, inService, and description.

• load: loadType, reactivePowerMvar, powerFactor, voltageSetByUser, ratedCurrent,

motorHorsepower, motorEfficiency, fullLoadAmps, fullLoadAmpsSource, startingCurrent, startingTorque, fullLoadTorque, motorType, enclosureType, motorServiceFactor, lockedRotorCurrentPu, rXRatio, cosPhiRated, efficiencyRated, motorXdDoublePrime, motorXOverR, motorMf, loadCharacteristic, diversityFactor, demandFactor, utilizationFactor, phaseConfiguration, isContinuousLoad, dutyCyclePercent, operatingTemperature, altitudeMeters, serviceCondition, protectionType, controlType, inService, and description.

• utility_feed: utilityFeedType, operatingVoltagePercent (percent of nominal voltage

the utility holds in power flow, 80 to 120, default 100), inputMethod, threePhaseFaultCurrent, singlePhaseFaultCurrent, faultCurrentXrRatio, baseMva, z1PuReal, z1PuImag, z0PuReal, z0PuImag, shortCircuitMvaLg, xrRatioLg, shortCircuitMvaLl, xrRatioLl, r1Ohms, x1Ohms, r0Ohms, x0Ohms, faultCaseName, faultCaseStudies, additionalFaultCases, inService, and description. The fault-case fields are described under Utility fault cases.

• protection_device: ratedVoltage, voltageSetByUser, ratedCurrent,

interruptingCapacity, continuousDutyRating, operatingState, lvBreakerType, inService, and description.

• motor_control_device: ratedVoltage, ratedCurrent, ratedHp, ratedKw, nemaSize,

inService, and description.

• capacitor_bank: ratedKv, voltageSetByUser, ratedFrequencyHz, connection, steps,

energizedSteps, lossWattsPerKvar, inService, and description.

For new transformers, fields explicitly marked unresolved remain unknown when saved, including cooling, losses, tap details, impedance, and X/R. Typical defaults still apply to omitted fields. An existing-project merge preserves an existing non-null value when the proposal marks that field unresolved, and reports EXISTING_VALUE_PRESERVED. To correct an existing value to unknown, clear it through the ordinary project import PATCH endpoint.

Utility fault cases

A utility letter that gives more than one fault level, such as a maximum and a minimum, can be stated as fault cases. They are optional; omit them when the source gives one level. The utility's fault-level fields are its first case, and three properties describe the cases with the values the project input reference defines:

• faultCaseName: the first case's name, for example "Max".
• faultCaseStudies: a list of the studies the first case is included in, from short_circuit

and arc_flash.

• additionalFaultCases: a list of up to three more cases. Each case has an id (a UUID you

choose), a name, studies, and values under the first case's field names for the utility's inputMethod. A fault current may be given in amperes as threePhaseFaultCurrentA; EKX converts it to kA as threePhaseFaultCurrent.

"additionalFaultCases": {
  "state": "supplied",
  "value": [{
    "id": "6f1c2a4e-7d1b-4c55-9a52-0f6b3c1e2d77",
    "name": "Min",
    "studies": ["arc_flash"],
    "threePhaseFaultCurrentA": 12000,
    "faultCurrentXrRatio": 8
  }]
}

These are the only properties that take a list value. A case that breaks a rule, such as an unknown key, a value the input method does not use, or a name another case already has, returns the blocking issue INVALID_UTILITY_FEED_INPUT naming the problem; nothing is applied. In a merge, restating an existing utility's saved cases unchanged changes nothing. A different list replaces the saved one and returns EXISTING_VALUE_CONFLICT until you accept the replacement. Send the complete list, including cases you keep. The rules apply to the utility as it would be saved, so a merge that changes only the first case's name or the input method is checked against the saved cases it leaves out.

Enum values enforced by the managed compiler include:

• transformerType: power_transformer, distribution_transformer, instrument_transformer,

autotransformer, isolation_transformer.

• transformerConstruction: dry_type, other_than_dry_type. Mark it unresolved when unknown;

EKX does not infer construction from cooling type or supply a typical construction.

• vectorGroup: wye_wye, wye_delta, delta_wye, delta_delta, zigzag_wye, open_delta.
• generatorType: synchronous_generator, induction_generator, diesel_generator,

gas_turbine, steam_turbine, wind_turbine, solar_inverter, battery_storage.

• loadType: motor, static_load, lighting, heating, ups, variable_frequency_drive,

reactor. Use the capacitor_bank component type for a capacitor bank.

• connection for a capacitor bank: delta, grounded_wye, ungrounded_wye.
• utilityFeedType: grid, generator, solar, wind, battery.
• deviceType for protection: circuit_breaker_hv, circuit_breaker_lv, fuse,

disconnect_switch, load_break_switch, recloser, sectionalizer, relay, surge_arrester, overload_relay.

• operatingState: closed, open, throw_a, throw_b.
• load_break_switch is the double-throw transfer switch. It has one common source terminal and

two load throw terminals. throw_a or throw_b selects the conducting throw; open blocks both. Connect it in one of two directions:

• One supply, two outputs: a relationship into source, and up to two relationships out of

load. The first relationship out of load is Throw A and the second is Throw B.

• Two supplies, one output, as for an automatic transfer switch: up to two relationships into

load and one relationship out of source. The first relationship into load is Throw A and the second is Throw B. EKX draws the switch turned over, with the Throw A supply directly above it, the Throw B supply to its left, and the load below. Leave layoutParentRef unset on the switch.

A switch connected both ways, for example with a relationship into source and another into load, returns the blocking issue MIXED_TRANSFER_SWITCH_DIRECTION.

The throws and the common terminal share one nominal voltage, whichever throw is selected. Two supplies at different voltages on the throws return the blocking issue VOLTAGE_ZONE_CONFLICT.

  {
    "ref": "ats-1",
    "componentType": "protection_device",
    "name": "ATS-1",
    "properties": {
      "deviceType": { "state": "supplied", "value": "load_break_switch" },
      "operatingState": { "state": "supplied", "value": "throw_a" },
      "catalogIntent": { "state": "supplied", "value": "leave_unresolved" }
    },
    "evidenceRefs": []
  }

  [
    { "ref": "normal-to-ats", "kind": "electrical", "evidenceRefs": [],
      "from": { "componentRef": "normal-cable", "terminal": "load" },
      "to": { "componentRef": "ats-1", "terminal": "load" } },
    { "ref": "emergency-to-ats", "kind": "electrical", "evidenceRefs": [],
      "from": { "componentRef": "generator-cable", "terminal": "load" },
      "to": { "componentRef": "ats-1", "terminal": "load" } },
    { "ref": "ats-to-load", "kind": "electrical", "evidenceRefs": [],
      "from": { "componentRef": "ats-1", "terminal": "source" },
      "to": { "componentRef": "ats-load-cable", "terminal": "source" } }
  ]

• deviceType for motor control: vfd, soft_starter, contactor, motor_starter,

reduced_voltage_starter, fvnr, fvr.

Catalog selectors

Agents select catalog intent with public descriptive fields, not internal UUIDs. Supported selector names are catalogIntent, manufacturer, modelNumber, partNumber, variant, deviceCategory, mfgName, seriesName, specNumber, conductorMaterial, insulationType, ratedVoltageKv, numberOfConductors, armoured, conductorSize, and conductorSizeUnit. A protective device part without a part number is picked by its variant, such as 30 A, within its modelNumber.

Set catalogIntent to leave_unresolved when a cable's catalogue selection must remain unresolved. Later graph changes preserve that missing selection, including ordinary API imports and editor changes. Selecting a cable family or size remains an explicit component edit. EKX then saves that cable with no selected series or variant. The legacy value not_applicable remains accepted for existing integrations.

When the user names a cable family but not its conductor size, submit that family's selectors, such as seriesName, and omit conductorSize, conductorSizeUnit, and partNumber. When every match belongs to one family, EKX saves that series and leaves the variant unresolved. Selectors that match more than one family return an ambiguous match.

Set catalogIntent to use_project_default_series when the user accepts the configured cable type but the conductor size is unknown. EKX saves the project-default series and leaves the variant unresolved; in a new project with autoSizingMode apply, sizing then picks the size. Set it to use_project_default only when the user explicitly accepts both the configured series and its default variant, including that variant's conductor size. Omitting both catalogue selectors and catalogIntent blocks the proposal.

EKX returns zero, one, or multiple exact candidates from the draft's fixed workspace. An ambiguous result includes opaque candidate keys and labels. Resolve it only with the returned candidate key; do not discover or submit private catalog row IDs. A catalog change before apply requires a fresh compiled proposal version.

Protected properties

The following property keys are rejected: position, positionX, positionY, x, y, spacing, sourceHandle, targetHandle, handleId, routing, and collisionChecks. There is no managed API field for minimum spacing, final labels, visible bounds, rendered handle IDs, or edge routes. EKX maintains at least 50 px of clear vertical space between connected rendered bounds.

Relationship schema

Relationships are electrical and refer only to semantic terminals:

{
  "ref": "transformer-to-bus",
  "kind": "electrical",
  "from": { "componentRef": "transformer", "terminal": "secondary" },
  "to": { "componentRef": "bus", "terminal": "bus" },
  "evidenceRefs": ["service-riser"]
}

A capacitor bank has one top terminal, load, like a load. It is fed through that terminal and feeds nothing.

Valid semantic terminals are source, load, primary, secondary, tertiary, and bus. EKX selects the mounted rendered handles and indices. Unsupported relationships return an issue rather than a saved but invisible connection.

Merge removals

An explicit removal has this shape:

{
  "existingComponentId": "026451a7-ad3c-44b1-b797-76e04e2f0acf",
  "reason": "The reviewed revision removes the abandoned feeder",
  "intent": "reviewed_removal",
  "evidenceRefs": ["demolition-note-3"]
}

The compiler returns a confirm_removal decision before a removal can become ready. Components absent from a merge proposal remain unchanged.

Issue classes and resolutions

Issue classes are blocking_error, required_decision, warning, normalization, and informational_exclusion. Severity is error, warning, or info. blocksReady is authoritative for readiness.

Only submit a resolution type listed in the issue's allowedResponses:

Issue keys bind the decision to the exact current issue. A stale or no-longer-applicable resolution does not silently carry forward.

Bounded revision schema

A PATCH body contains 1–100 operations and the current expected version:

{
  "version": 1,
  "expectedVersion": 3,
  "operations": [
    { "operation": "upsert_component", "component": {} },
    { "operation": "remove_component", "ref": "old-local-ref" },
    { "operation": "upsert_relationship", "relationship": {} },
    { "operation": "remove_relationship", "ref": "old-relationship-ref" },
    { "operation": "upsert_resolution", "resolution": {} },
    { "operation": "remove_resolution", "issueKey": "sld-issue:v1:..." },
    { "operation": "upsert_evidence", "evidence": {} },
    { "operation": "remove_evidence", "ref": "old-evidence-ref" },
    { "operation": "replace_project", "project": { "kind": "existing_project" } }
  ]
}

The empty objects above are placeholders for the complete schemas described on this page. Submit only the operations required for the correction.

Build response

A permitted GET or mutation response returns these data fields:

PUT and PATCH compile the submitted version and apply it in the same transaction when no blocking issues remain. A blocked response leaves the project unchanged. The agent asks the user about those issues and submits a revision. There is no separate review or apply endpoint.

compiledResult includes normalized components, mounted connections, project effect, issues, material outcomes, limitations, counts, policyVersion, catalogFingerprint, optional merge baselineFingerprint, compiledFingerprint, and layoutOutcome. Positions, line wrapping, visible bounds, handles, and routes in this result are server-owned output and must not be copied back into the semantic proposal.

Common managed-build errors

Related topics

• Import a single-line diagram with an agent
• Connect to the EKX API
• Component properties