DesignSpec New in 4.0

The design document that every engine reads: sites, workloads, clouds, peers, constraints, objectives and commercial terms.

Role#

A DesignSpec describes the requirements of a design: where the users and facilities are, which workloads run, which clouds and networks must be reachable, the hard limits, the objectives and their weights, and the commercial terms. It contains no metros to deploy in and no connections to create, because the engines derive those from the requirements.

The document is immutable, carries a schemaVersion (currently "1"), and round-trips through JSON and YAML. A design can therefore be kept in version control, reviewed in a pull request, and run again later against current data.

Structure#

Section	Type	Content
`sites`	`SiteIntent`	A label, and a metro code or coordinates; optional role, headcount and weight
`workloads`	`WorkloadIntent`	A label, a workload type, bandwidth in Mbps, latency sensitivity, a latency ceiling in ms, the clouds it depends on, an optional pinned metro
`clouds`	`CloudIntent`	An id, a provider or a service profile, a region, whether it is required, monthly egress and ingress in GB
`peers`	`PeerIntent`	An ASN and a label
`constraints`	`DesignConstraints`	Required and excluded metros and regions, compliance zones, geo zones, minimum redundancy, maximum site latency, minimum and maximum metro count
`objectives`	`DesignObjectives`	A named weight profile, or explicit weights per objective
`commercial`	`CommercialTerms`	Currency, monthly budget, contract term, growth rate, planning horizon
`labels`	map	Free-form metadata

YAML#

YAML

name: payments-platform
description: Two regions, AWS and Azure, PCI workloads in the EU
sites:
  - label: New York HQ
    metro: NY
    role: headquarters
    headcount: 500
  - label: Frankfurt operations
    metro: FR
    role: data_center
clouds:
  - id: aws
    provider: aws
    region: us-east-1
    required: true
    monthlyEgressGb: 40000
  - id: azure
    provider: azure
    region: westeurope
    required: true
workloads:
  - label: card-authorisation
    type: transactional
    bandwidthMbps: 2000
    maxLatencyMs: 25
    clouds: [aws]
  - label: settlement-dr
    type: disaster_recovery
    bandwidthMbps: 500
    clouds: [azure]
constraints:
  minimumRedundancy: multi_region
  complianceZones: [eu_gdpr]
  maxLatencyMs: 100
  maxMetros: 4
objectives:
  profile: balanced
commercial:
  currency: USD
  budgetMaxMonthly: 60000

Enum values in a document are case-insensitive. Reading a document with an unknown property fails with an error that names the property.

Reading, validating and writing#

Java

import com.eqixiac.equinix.design.spec.DesignSpec;
import com.eqixiac.equinix.design.spec.DesignSpecIO;
import com.eqixiac.equinix.design.spec.SpecIssue;

DesignSpec spec = DesignSpecIO.read(Path.of("designs/payments-platform.yaml"));

for (SpecIssue issue : spec.validate()) {
    System.out.println(issue.severity() + " " + issue.path() + ": " + issue.message());
}
spec.requireValid();                          // throws IllegalArgumentException when there are errors

System.out.println(spec.fingerprint());       // stable identity of the content
DesignSpecIO.write(spec, Path.of("designs/payments-platform.json"));

validate() reports every problem with its path, for example a workload that names a cloud the document does not declare, a latitude outside the valid range, or minMetros above maxMetros. read and write choose JSON or YAML by file extension.

Building in code#

Java

import com.eqixiac.equinix.design.optimizer.enums.RedundancyTier;
import com.eqixiac.equinix.design.optimizer.enums.SiteRole;
import com.eqixiac.equinix.design.optimizer.enums.WorkloadType;
import com.eqixiac.equinix.design.spec.CloudIntent;
import com.eqixiac.equinix.design.spec.CommercialTerms;
import com.eqixiac.equinix.design.spec.DesignConstraints;
import com.eqixiac.equinix.design.spec.DesignObjectives;
import com.eqixiac.equinix.design.spec.SiteIntent;
import com.eqixiac.equinix.design.spec.WorkloadIntent;
import com.eqixiac.equinix.fabric.model.implementation.cloud.CloudProviderType;

DesignSpec built = DesignSpec.builder()
    .name("payments-platform")
    .site(SiteIntent.builder().label("New York HQ").metro("NY").role(SiteRole.HEADQUARTERS).headcount(500).build())
    .site(SiteIntent.builder().label("Singapore office").latitude(1.3521).longitude(103.8198).build())
    .cloud(CloudIntent.builder().id("aws").provider(CloudProviderType.AWS).region("us-east-1")
        .required(true).monthlyEgressGb(40_000d).build())
    .workload(WorkloadIntent.builder().label("card-authorisation").type(WorkloadType.TRANSACTIONAL)
        .bandwidthMbps(2000).maxLatencyMs(25d).clouds(List.of("aws")).build())
    .constraints(DesignConstraints.builder()
        .minimumRedundancy(RedundancyTier.MULTI_METRO).maxLatencyMs(100d).maxMetros(3).build())
    .objectives(DesignObjectives.balanced())
    .commercial(CommercialTerms.builder().currency("USD").budgetMaxMonthly(new BigDecimal("60000")).build())
    .label("owner", "network-platform")
    .build();

DesignSpec revised = built.toBuilder().description("Singapore added 2026-11").build();

The fluent MetroOptimizer.Builder assembles the same document, and fabric.optimizeMetros()...toSpec() returns it.

Fingerprint#

fingerprint() is a hash of the canonical content. Two documents with the same content have the same fingerprint, whatever the property order or format. An OptimizationResult records the fingerprint of its spec (getSpecFingerprint()), and a DeploymentPlan carries it forward, so the design that a plan was derived from can be identified from the plan.

Objectives and weights#

objectives.profile names one of five built-in weight profiles, and objectives.weights sets explicit weights by objective id, which override the profile.

Profile	Latency	Provider coverage	Cost	Resilience	Compliance
`balanced`	0.30	0.25	0.20	0.15	0.10
`latency_first`	0.50	0.20	0.10	0.10	0.10
`cost_first`	0.15	0.15	0.45	0.15	0.10
`redundancy_first`	0.20	0.15	0.15	0.40	0.10
`provider_coverage_first`	0.20	0.45	0.15	0.10	0.10

A weight must be a non-negative, finite number, and at least one weight must be above zero. The Metro Optimizer defines what each objective measures.

Use by the engines#

Engine	Reads	Status
Metro Optimizer	The whole document	In the tree
Deployment Wizard	Through the `OptimizationResult`; `designSpec(...)` and `specFingerprint(...)` attach it to the plan	In the tree
Savings and TCO calculators	Their own builder inputs. `CloudIntent.monthlyEgressGb` is the volume the optimizer's cost model prices.	Spec input for the calculators is Planned
Peering Intelligence	Its own builder inputs. `peers` is carried in the document.	Spec input is Planned
MCP tools	JSON arguments of each tool	Spec input is Planned

The package documentation states the goal that all engines and the MCP tools take the same document. On 2026-11-12 the optimizer and the wizard took it, and the other engines did not yet.