Decision Concepts | DecisioQ Developer Center

Introduction

DecisioQ is a catalog-driven decision platform. A client chooses a decision, provides candidate cases, and receives a deterministic recommendation with ranking, scores, validation feedback, and a business-friendly explanation. Profiles and Scenarios are optional configuration tools; begin with the decision's recommended or default configuration and introduce them only when the business requirement calls for a different evaluation emphasis or operating context.

Start with the business question, not the API call. The API is the transport; the decision model is what determines whether the recommendation is useful.

Connect

Client application
Authentication

Discover and Prepare

Decision Catalog discovery
Decision Preparation Model mapping
Scenario and Profile selection

Evaluate

Criterion weight determination
Algorithmic decision execution
Sensitivity analysis when requested

Review and Act

Recommendation and explanation
Client application review

Decisions

A Decision is a reusable model for answering a specific business question, such as which auction vehicle to purchase, which repair order to prioritize, or which towing request should be dispatched first.

Business Purpose

Make a repeatable recommendation using criteria the business trusts, rather than relying on ad hoc judgment.

Technical Purpose

Provide a stable decisionId, metadata, criteria, profiles, scenarios, and execution rules that clients can discover from the catalog.

Concept	Example	Why It Matters
Decision ID	`AUTO-AUCT-044`	Used as the stable API identifier.
Decision Name	Auction purchase recommendation	Displayed to business users.
Decision Metadata	Purpose, business question, expected outcome	Explains when and why to use the decision.

Common mistake: hard-coding decision inputs instead of loading the decision definition from the catalog.

Criteria

Criteria are the measurable factors used to score each candidate case. Examples include title confidence, estimated margin, repair complexity, customer impact, safety risk, and parts availability.

Criterion Weights

A criterion's weight defines its relative importance. A high weight on margin means profitability has more influence on the final ranking. The Weight Strategy explains how those weights are determined.

Normalization

DecisioQ converts different units and ranges into comparable scores so that mileage, percentage, cost, and risk can be evaluated together.

Direction

Some criteria are better when higher, such as confidence. Others are better when lower, such as risk or cost.

Validation

Required values and bounded ranges prevent invalid inputs such as a percentage of 740.

Constraints

Eligibility rules applied before ranking. A constraint can exclude an option that violates a hard business, safety, regulatory, or operational requirement; excluded options do not compete for the recommendation.

A criterion should clearly state what is being measured, the expected unit, whether higher or lower values are preferred, and whether the value is required.

Best practice: show criterion names and overview text to users, but keep criterion IDs in the request payload for stable integration.

Weight Strategy

A criterion weight expresses how much influence that criterion has on the evaluation. A Weight Strategy answers one question: Where do the criterion weights come from?

Weight Strategy is not the Ranking Algorithm. Weight Strategy establishes criterion importance. The Ranking Algorithm then combines criterion values and the resulting weights to compare options. AHP derives weights; TOPSIS or WSM performs the option ranking.

Three practical weighting paths

Approach	Use it when	Where the weights come from
Use Decision Defaults	You accept the decision's standard business priorities and do not need to configure weights.	The selected Decision Catalog definition or an applicable reviewed Profile.
Provide Your Own Weights	Your organization already has established, reviewed, or policy-driven criterion priorities.	The organization's approved values, normalized after validation.
Derive Weights with AHP	Stakeholders know what matters more but cannot confidently assign exact percentages.	Interactive Weight Discovery uses AHP to derive normalized weights from business-priority comparisons.

DecisioQ Recommended Priorities

Recommended priorities let organizations begin without inventing weights first. They are designed as a robust starting configuration by considering the decision's business purpose, the meaning and expected relative importance of its criteria, domain reasoning, consistency across the decision definition, and the intended decision behavior.

They are not universally correct weights. Organizations can use them immediately, observe actual outcomes, evaluate performance, and customize only when evidence, policy, governance, or distinct business objectives warrant it. DecisioQ does not automatically change weights from observed outcomes.

AHP Weight Strategy

Use AHP when stakeholders understand which business factors matter more but do not know the numerical weights. AHP derives normalized weights from relative-importance comparisons.

Learn about AHP & Interactive Weight Discovery →

Client-Provided Weights

Use client-provided weights when the organization already knows the intended relative importance of every criterion. Those values may come from policy, prior decision analysis, management review, domain expertise, historical validation, or another governance process.

DecisioQ normalizes accepted weights for evaluation. Providing custom weights is optional; organizations may continue using recommended priorities while those remain suitable.

How the concepts relate

Concept	Role
Weight Strategy	Determines how criterion weights are established.
Profile	A reusable business preference or configuration that may provide a reviewed alternative emphasis. It is not synonymous with Weight Strategy, and its exact effect is decision-specific.
Scenario	Represents operating context or conditions. It is not a Weight Strategy and does not necessarily change weights.
Ranking Algorithm	Uses criterion values and the established weights to rank options with TOPSIS or WSM.

Establish weights using recommended priorities, AHP, or client-provided values Combine criterion values and weights using TOPSIS or WSM Produce scores, ranking, and recommendation

Choosing an approach

Question	Suggested path
Do you already have established criterion weights?	Yes: Client-Provided Weights.
If not, can stakeholders meaningfully compare criterion importance?	Yes: derive weights with AHP using Interactive Weight Discovery.
Are priorities not yet established?	Yes: DecisioQ Recommended Priorities.

You can begin with DecisioQ Recommended Priorities and adopt a more customized approach later as business evidence and governance requirements develop. These are practical guidelines, not absolute rules.

Measurement Units and Localization

Localize what people see, not the machine-readable API contract. DecisioQ uses stable technical identifiers and the canonical values required by each decision definition so that the same model behaves consistently across regions. Criterion scoring normalization is an algorithm step; it does not convert kilometres to miles or CAD to USD.

Stable API contract

Keep decision IDs, criterion IDs, option IDs, JSON properties, enum values, endpoint paths, profile and scenario IDs, and audit identifiers unchanged. For example, annualDistance remains the criterion ID whether the UI says “Annual distance,” “Annual mileage,” or a translated label.

Localized presentation

Consumer applications may localize labels, guidance, number and date formats, currency display, time-zone presentation, measurement units, and user-facing terminology.

Current responsibility model

Unless an endpoint explicitly documents unit-qualified input or presentation preferences, the consumer converts input to the canonical unit required by the selected decision definition and localizes returned values in its own UI.

Authoritative definition

For every criterion, use the selected decision definition or schema as the authority for data type, canonical unit, accepted input units, conversion behavior, and validation rules.

Implementation status: Do not assume automatic unit detection, unit conversion, currency conversion, localized labels, translated explanations, or jurisdiction-specific rules. Unless the endpoint explicitly documents support, these remain consumer responsibilities.

Submit unambiguous measurements

Do not send a bare value such as {"annualDistance":25000} unless the selected decision definition explicitly and unambiguously defines its unit. If the endpoint supports unit-qualified values, submit the documented unit structure. Otherwise, convert the user's value to the definition's canonical unit before submitting it.

The following shapes are conceptual only, not production request fields: {"annualDistance":{"value":25000,"unit":"km"}} and {"annualDistance":{"value":15534,"unit":"mi"}}. Use them only if the selected endpoint's published schema supports that exact structure.

Locale and measurement system are separate choices. Do not infer units, currency, or jurisdiction from language or country: a Canadian user may prefer miles, a US user may prefer metric units, and a French-speaking user does not imply a particular currency.

Separate localization settings

A client may independently track locale, measurement system, currency, time zone, and jurisdiction. Conceptually: {"locale":"en-CA","measurementSystem":"metric","currency":"CAD","timeZone":"America/Toronto","jurisdiction":"CA-ON"}. This object explains the concerns; it is not an API request contract unless an endpoint explicitly documents these fields.

Setting	Purpose
Locale	Language and regional number/date formatting.
Measurement system	How measurements are displayed.
Currency	Monetary display and valuation context.
Time zone	Date and time presentation.
Jurisdiction	Applicable legal, regulatory, or policy context where the model explicitly supports it.

Currency is not a measurement conversion

Kilometres-to-miles conversion is deterministic. CAD-to-USD conversion requires an exchange-rate source, an effective date or valuation timestamp, rounding rules, and a defined policy. DecisioQ does not automatically convert currencies unless the selected API and decision definition explicitly document that capability. Where currencies may vary, the consumer must retain or identify the currency and apply its approved conversion policy before evaluation.

Canadian and US presentation example

Stage	Canadian consumer	US consumer
User sees	Annual distance in km, fuel consumption in L/100 km, cost in CAD, Canadian date formatting.	Annual mileage in mi, fuel economy in mpg, cost in USD, US date formatting.
Consumer prepares	Converts each value to the canonical unit and currency context required by the selected decision definition.	Performs the equivalent conversions to the same canonical requirements.
API contract	Uses the same decision ID, `annualDistance` criterion ID, option IDs, JSON properties, and enum values.
Result display	Converts and formats canonical output for Canadian preferences.	Converts and formats canonical output for US preferences.

When both consumers represent the same real-world facts and normalize them correctly, presentation differences should not change decision behavior. Any currency comparison must use the same explicitly defined valuation policy.

Responsibility summary

Concern	API consumer	DecisioQ
Technical identifiers	Preserve canonical IDs.	Define and process canonical IDs.
Input units	Identify units and convert to required canonical units unless explicit unit input is documented.	Validate or convert only where the endpoint explicitly supports it.
Display units and labels	Convert, format, and localize for the user.	Return canonical values and metadata unless localized output is documented.
Currency	Identify currency and apply an explicit conversion policy when needed.	Does not imply automatic exchange-rate conversion.
Dates and times	Send the documented canonical format and display in the user's time zone.	Process documented canonical timestamps.
Jurisdiction	Supply or apply appropriate context when required.	Use it only where the selected decision model explicitly supports it.

Decision Execution Contract

Decision Request

The JSON payload submitted to POST /api/v1/decide. It identifies the decision, selects exactly one input mode, and may include execution options such as profile, scenario, algorithm, weight strategy, sensitivity, and response options.

Request Context

Optional operational metadata such as locale, measurement system, currency, time zone, jurisdiction, and a client-provided Correlation ID. Context improves traceability and interpretation without replacing decision inputs.

Correlation ID

A non-secret identifier carried through client, portal, integration, and service logs. Generate one per logical operation and retain it when working with support.

Decision Outcome Feedback

A later observation describing what happened after a recommendation was used. Feedback supports evaluation and improvement; it does not retroactively alter the deterministic response.

Related Concepts

Decision Input Modes

DecisioQ accepts two mutually exclusive ways to supply decision input. The input mode changes who prepares criterion values, but it does not change the ranking, sensitivity, explanation, or response capabilities of the Decision Service.

Business Data Mode

Submit domain-shaped Business Data. The selected decision resolves and applies its Decision Preparation Model automatically.

Business DataDecision Preparation ModelPrepared CriteriaDecision EngineRanking and Recommendation

Prepared Criteria Mode

Submit options and criterion values as Prepared Decision Input. The Decision Preparation Model is bypassed because the client already owns data preparation.

Prepared CriteriaDecision EngineRanking and Recommendation

Common misconception: Prepared Criteria Mode is not a more capable execution path. Both modes converge on the same canonical request and support the same execution options, including runSensitivity.

API considerations

Send businessData for Business Data Mode or options for Prepared Criteria Mode—never both. The shared endpoint is POST /api/v1/decide.

Related Concepts

Platform Components

Decision Catalog and DKS

The Decision Catalog is the authoritative, versioned knowledge source for decisions, criteria, profiles, scenarios, constraints, examples, and recommended configuration. The Decision Knowledge Server (DKS) publishes and serves that catalog. It describes what can be executed; it does not rank options.

Decision Service and DDE

The customer-facing Decision Service is implemented by the Decision Engine (DDE). It validates a request, resolves catalog knowledge, prepares canonical criteria, applies constraints, ranks eligible options, and composes the response.

Integration Platform

The translation and orchestration layer that maps business-shaped inputs to the stable decision contract while preserving correlation, validation, and diagnostic context.

Decision Execution

A single evaluated request against a resolved decision definition and effective configuration. Execution is deterministic for the same inputs and knowledge version.

Related Concepts

Options and Candidate Cases

An Option is a candidate that can be recommended. In the user interface these are often called Candidate Cases. For Auto Auctions, each option may be a vehicle lot. For Auto Towing, each option may be a tow request.

Candidate cases are collected Criteria values are validated Each candidate is scored Candidates are ranked The best-supported recommendation is returned

When not to use: if there is only one possible candidate and no meaningful trade-off, a rule or validation endpoint may be more appropriate than a ranked decision.

Profiles and Scenarios

Profiles and Scenarios let you adapt how a decision is evaluated without redefining its business question, canonical criteria, or candidate data. They are related configuration choices, but they are not interchangeable.

Profiles

A Profile is a reusable evaluation configuration for a decision. It answers: How should this decision generally be evaluated? A published Profile supplies a reviewed weight map keyed by the decision's current criterion IDs and can therefore change the relative emphasis placed on cost, quality, risk, customer value, or other criteria.

One decision can publish multiple Profiles for different enduring business priorities. Current catalog examples include balanced, cost_focused, quality_focused, and risk_control; their exact meaning and weights come from the selected decision definition, not from the name alone.

Select a Profile with profileId. If it is omitted, configuration resolution uses the decision's recommended Profile when one is declared, then the supported Balanced fallback when available. The response's configurationUsed.profile reports the effective value and source. A Profile does not change how Business Data is prepared and does not replace the Weight Strategy: with the normal Expert strategy, it is one supported source of effective criterion weights.

Scenarios

A Scenario names the circumstances, assumptions, or operating context under which the same decision is being evaluated. It answers: Under what circumstances is this decision being evaluated? Decisions can publish several Scenario IDs, such as standard, limited_budget, or risk_control, but clients must discover the actual values and descriptions from the selected Decision Catalog definition.

Select a Scenario with scenarioId. The runtime validates and applies only a Scenario published for that decision and records the effective selection in configurationUsed.scenario. What a Scenario changes is definition-specific; do not infer weight overrides, thresholds, or transformations merely from its name. When scenarioId is omitted, the base/no-Scenario execution is used unless the decision's authoritative configuration explicitly recommends one. The platform fallback is no Scenario.

Profiles vs. Scenarios

Concept	Profile	Scenario
Main question	How should this decision generally be evaluated?	Under what circumstances is it being evaluated?
Nature	Reusable evaluation preference	Context-specific situation or assumptions
Typical persistence	Relatively persistent across executions	Often selected for a particular operating context
Catalog example	`cost_focused`	`limited_budget`
Primary effect	Supplies a reviewed criterion-weight emphasis	Selects definition-specific contextual configuration

Using them together

{
  "decisionId": "AUTO-AUCT-006",
  "profileId": "balanced",
  "scenarioId": "standard",
  "businessData": { "...": "decision-specific fields" }
}

Request choice	Runtime behavior
Neither specified	Resolve the decision's recommended/default Profile chain and use base/no-Scenario behavior unless a Scenario is explicitly recommended.
Profile only	Use that published Profile's evaluation emphasis with base/no-Scenario behavior.
Scenario only	Resolve the default Profile chain and apply the selected published Scenario context.
Both specified	Apply the selected published Profile and Scenario together; each retains its distinct role.

Do you need either one? No. Start with the decision's recommended configuration. Use explicit IDs only when the catalog exposes them and the business intends that preference or context.

Input mode answers how values are supplied; Profiles influence evaluation emphasis; Scenarios identify operating context; TOPSIS or WSM performs ranking; Sensitivity Analysis tests recommendation stability.

Sensitivity Analysis

Sensitivity Analysis tests how stable the recommendation is when weights or model assumptions vary. It helps decision makers understand whether a result is robust or fragile.

Use it when recommendation stability matters, especially for high-value, closely ranked, borderline, or audit-sensitive decisions. It is optional when that additional evidence is not required.

Stable Decision

The same candidate remains recommended after reasonable weight changes. This increases confidence.

Sensitive Decision

A small change causes a different winner. The business may need more data or manager review.

Original recommendation Weight changes are simulated Ranking stability is measured Decision risk is reported

When Sensitivity Analysis is enabled, users should expect an added stability signal that explains whether the recommendation remains strong under reasonable model variation.

When to use: high-value purchases, borderline rankings, audit-sensitive decisions, or decisions where a small data error could change the outcome.

When not to use: very high-throughput flows where latency matters more and the recommendation is already operationally low risk.

Decision Preparation Models

A Decision Preparation Model is a declarative model that defines how DecisioQ validates, normalizes, transforms, calculates, and maps Business Data into the Prepared Criteria required by a specific decision.

It owns the Input Contract, validation, normalization, Prepared Values, reusable metric references, business rules, criterion mappings, and documentation metadata. Clients normally select a decision; Business Data Mode resolves the appropriate model automatically.

A data model describes what data exists. A Decision Preparation Model also describes how that data becomes decision-ready.

Data Preparation

Receive Business DataValidate InputNormalize Units and FormatsCalculate Prepared ValuesApply Business RulesMap Prepared Values to Decision CriteriaProduce Prepared CriteriaExecute the Decision

Business Field	Canonical Criterion	Validation or Transformation
`titleConfidence`	`AUTO-AUCT-TITLE-CONFIDENCE`	Validate as percentage 0 to 100.
`estimatedRepairCost`	`AUTO-AUCT-REPAIR-COST`	Normalize cost where lower is better.
`marketDemandScore`	`AUTO-AUCT-MARKET-DEMAND`	Validate as score 0 to 100.
`odometer.value` plus `odometer.unit`	`vehicle_mileage`	Convert supported `mi` or `km` inputs to the canonical metric value.

Common mistake: treating data preparation as the same thing as business preference. Data preparation gets values into the expected decision shape; Profiles express business preference through weights, defaults, and context.

Financial Metrics

Financial Metrics are reusable Prepared Values calculated by a Decision Preparation Model. They centralize definitions such as Total Acquisition Cost and Expected Gross Vehicle Margin while continuing to map into existing decision criteria such as Cost Impact and Business Value.

Financial Metrics are Prepared Values, not decision criteria. Their canonical definitions declare formulas, inputs, currency policy, inclusions, exclusions, examples, and default criterion mappings.

Decision Algorithm

A Decision Algorithm is the option-ranking algorithm that evaluates the available options using their criterion values and criterion weights, then produces a ranked result. DecisioQ currently supports TOPSIS and WSM (Weighted Sum Model).

Concept	Purpose
Criterion Weight	Defines how much influence a criterion has.
Weight determination	Uses Decision Catalog recommended priorities, AHP-assisted priorities from client judgments, or client-provided weights.
Decision Algorithm	Uses criterion values and the resulting weights to rank options.

Algorithm	Basic approach	Primary strength
TOPSIS	Ranks options by closeness to an ideal solution and distance from the least desirable solution.	Useful for multi-criteria decisions involving trade-offs.
Weighted Sum Model (WSM)	Multiplies each normalized criterion score by its weight and adds the results.	A transparent weighted total that is easy to check manually.

1. Define criteria and Maximize/Minimize directions.2. Establish recommended, AHP-derived, or client-provided weights.3. Normalize eligible option values.4. Rank options with TOPSIS or WSM.5. Produce the recommendation, ranking, breakdown, and explanation.

Option-Ranking Algorithm choice guide

Choose WSM when…	Choose TOPSIS when…
You want the final score to be the weighted sum of all criterion scores.	Closeness to an ideal overall option is meaningful.
Strong performance in one criterion may offset weaker performance in another.	Trade-offs, relative performance, and both ideal and least-desirable profiles matter.
Stakeholders want a weighted scorecard they can reproduce with a calculator or spreadsheet.	Balance across competing criteria matters more than a direct weighted total.

Four supported combinations

Combination	Concise example
Recommended priorities + WSM	Parts supplier: Decision Catalog or an approved profile supplies priorities for a weighted total that can be reproduced in a spreadsheet.
Recommended priorities + TOPSIS	Fleet replacement: Decision Catalog or an approved profile supplies priorities; the closest vehicle to the preferred overall profile is wanted.
AHP + WSM	Repair priority: stakeholders compare safety, impact, downtime, and profitability in pairs; the final score stays easy to audit.
AHP + TOPSIS	Auction inspection technology: stakeholders structure priorities and compare trade-offs against an ideal solution.

Quick selection flow

Make two separate choices: establish the weights first, then select how options will be ranked.

Step 1 · Weight Strategy

Are meaningful criterion weights already known?

YesUse Client-Provided Weights when the established values remain appropriate.

NoIf stakeholders can compare criteria in pairs, consider AHP; otherwise begin with DecisioQ Recommended Priorities.

Step 2 · Ranking Algorithm

Does the organization want to add all weighted criterion scores into one spreadsheet-like total?

YesConsider WSM.

NoIf closeness to an ideal profile matters, consider TOPSIS.

Guidance, not hard rules: also consider governance, explainability, trade-offs, sensitivity, and the assumptions of the decision model.

AHP is a Weight Strategy, not a third option-ranking algorithm. It derives the weights that TOPSIS or WSM subsequently use.

Neither ranking algorithm is universally better. Choose a weighting path and ranking method before reviewing the winner. Changing the effective weight source can change weights; changing TOPSIS to WSM can change rankings even with the same weights.

Decision Results

A Decision Result contains the recommendation, ranking, scores, confidence, validation feedback, warnings, and optional sensitivity output. Present business-facing recommendation information prominently while keeping detailed technical diagnostics available to integrators and support teams when needed.

A useful result view should show the recommended option, why it ranked first, how close the other options were, which options were excluded by hard constraints, and whether any warnings or validation messages affect interpretation.

Interpretation guidance: the top-ranked candidate is recommended because it best satisfies the configured criteria, profile, scenario, and validation rules.

Decision Outputs

The Decision Response separates the recommendation from the evidence needed to interpret and operate it. Output availability is independent of whether input arrived through Business Data Mode or Prepared Criteria Mode.

Decision Confidence

A structured indication of recommendation strength based on ranking separation and available analysis. Confidence is decision evidence, not a probability or guarantee of a real-world outcome.

Execution Trace

A deterministic account of the configuration, weights, constraints, exclusions, and processing choices used during execution. Retain it with the Correlation ID, Decision ID, and validation outcomes when audit, troubleshooting, or support requirements call for diagnostic evidence.

Decision Explanation

A human-readable interpretation of the already finalized DecisioQ result. It translates the recommendation into business language and can communicate the recommended option, why it ranked first, the most important decision drivers and trade-offs, relevant warnings or limitations, and how decisive the result was.

A useful Decision Explanation helps users understand why the recommendation was produced instead of merely restating which option won.

The finalized deterministic result is authoritative. The explanation is an interpreter, not the decision maker. It does not recalculate scores, criterion values, weights, or confidence; rerank options; change eligibility; add or exclude options; select a different winner; or alter the recommendation.

Decision Explanation is not another ranking algorithm, decision engine, independent recommendation, or mechanism for modifying the finalized outcome.

Sensitivity Result

Evidence showing whether controlled changes to criterion weights preserve or change the winner. Request it with runSensitivity: true in either input mode.

Common misconception: A high confidence label or persuasive explanation is not a substitute for reviewing constraints, trace data, and sensitivity evidence appropriate to the decision's risk.

Related Concepts

Frequently Asked Questions

What is the easiest way to use DecisioQ?

Use the fully programmatic workflow in the Quick Start. Your application discovers a decision once—or uses a configured or cached decisionId—then submits businessData, receives the recommendation, and presents it to the user or continues the business process. Software normally performs these steps automatically. Decision Profiles, Weight Strategies, Ranking Algorithms, Constraints, Scenario Analysis, and Sensitivity Analysis are optional advanced capabilities.

When should I use Profiles?

Use them when the same decision needs different business priorities, such as Conservative, Balanced, or Aggressive.

When should I use Scenarios?

Use them when the operating context changes, such as high demand, low inventory, emergency dispatch, or seasonal pressure.

Do Profiles override weights?

A selected Decision Catalog Profile supplies recommended weights for its decision. Explicit client-provided weights or consistent AHP-derived weights override those Profile weights, and configurationUsed.effectiveWeights.source explains the result.

Is AHP an alternative to TOPSIS or WSM?

No. AHP determines criterion weights; TOPSIS or WSM uses the resulting weights to rank options.

Should Sensitivity Analysis always be enabled?

No. Use it where decision stability matters enough to justify extra analysis.

What is the difference between Decision Preparation Models and Profiles?

Decision Preparation Models map business data to criteria. Profiles change decision preference and weighting.

Ready to Use These Concepts?

Continue with the resource that best matches what you want to do next.