System Specification¶

Version 0.1.0¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under The Apache License, Version 2.0.

Introduction¶

The System Specification (system-spec) defines a standard, strongly-typed format for describing system topologies including microservices, their dependencies, infrastructure bindings, and network connectivity.

Unlike polymorphic specifications (e.g., Open Application Model), system-spec uses concrete Go types with no interface{} or any fields. JSON Schema is generated from Go structs, ensuring type safety and IDE support.

Design Principles¶

Go-first: Go structs are the source of truth; JSON Schema is generated
No polymorphism: All types are concrete; maps use typed values (map[string]Service)
Graph-aware: System topology is modeled as nodes (services, resources) and edges (connections)
Multi-cloud: First-class support for AWS, GCP, and Cloudflare resources
Deployment-aware: Links to Helm charts and Terraform modules

Use Cases¶

System topology visualization (D2, Mermaid, Cytoscape.js)
Service dependency analysis
Infrastructure documentation
Network policy generation
Deployment orchestration

Definitions¶

System¶

A System is a collection of services, their infrastructure bindings, and network topology. It is the root object of a system-spec document.

Service¶

A Service represents a microservice, worker, or other deployable unit. Each service has a container image, optional source repository, and connections to other services or resources.

Connection¶

A Connection represents a directed dependency from one service to another, including the protocol and port.

Resource¶

A Resource is a cloud-managed service (database, queue, storage, etc.) that a service depends on.

Specification¶

Format¶

A system-spec document MUST be a JSON object conforming to the JSON Schema defined in system.schema.json.

YAML is NOT supported in v0.1.0 to ensure consistent parsing behavior.

Versions¶

The system-spec is versioned using semantic versioning (major.minor.patch). The major.minor portion designates the feature set.

Schema Objects¶

System Object¶

The root object of a system-spec document.

Field	Type	Required	Description
`name`	`string`	Yes	System identifier
`description`	`string`	No	Human-readable description
`version`	`string`	No	Version of this document
`services`	`map[string]Service`	Yes	Services keyed by name
`networks`	`map[string]Network`	No	Network definitions
`deployments`	`Deployments`	No	Helm/Terraform mappings

Example:

{
  "name": "payments-platform",
  "description": "Payment processing system",
  "version": "1.0.0",
  "services": {
    "api-gateway": { ... },
    "payments-service": { ... }
  }
}

Service Object¶

Represents a single microservice or workload.

Field	Type	Required	Description
`description`	`string`	No	Service description
`repo`	`GitRepo`	No	Source code repository
`image`	`ContainerImage`	Yes	Container image specification
`registry`	`string`	No	Container registry path
`connections`	`map[string]Connection`	No	Outbound connections keyed by target service
`exposes`	`[]Endpoint`	No	Ports/protocols this service exposes
`aws`	`AWSResources`	No	AWS resource bindings
`gcp`	`GCPResources`	No	GCP resource bindings
`cloudflare`	`CloudflareResources`	No	Cloudflare resource bindings

Example:

{
  "description": "Core payment processing service",
  "repo": {
    "url": "https://github.com/org/payments-service",
    "ref": "main"
  },
  "image": {
    "name": "ghcr.io/org/payments-service",
    "digest": "sha256:abc123..."
  },
  "connections": {
    "users-service": {
      "port": 8080,
      "protocol": "grpc"
    }
  },
  "aws": {
    "rds": [
      { "name": "payments-db", "engine": "aurora-mysql" }
    ]
  }
}

GitRepo Object¶

Represents a source code repository.

Field	Type	Required	Description
`url`	`string`	Yes	Full repository URL
`path`	`string`	No	Path within repo (for monorepos)
`ref`	`string`	No	Git reference (branch, tag)
`commit`	`string`	No	Specific commit SHA

Example:

{
  "url": "https://github.com/org/payments-service",
  "ref": "main",
  "commit": "abc123def456"
}

ContainerImage Object¶

Represents a container image specification.

Field	Type	Required	Description
`name`	`string`	Yes	Image name without tag
`tag`	`string`	No	Image tag (e.g., "v1.2.3")
`digest`	`string`	No	Image digest for pinning

If both tag and digest are specified, digest takes precedence for image resolution.

Examples:

{ "name": "nginx", "tag": "1.25" }

{ "name": "ghcr.io/org/api", "digest": "sha256:abc123..." }

Connection Object¶

Represents a connection from one service to another.

Field	Type	Required	Description
`port`	`integer`	Yes	Target port number (1-65535)
`protocol`	`string`	Yes	Protocol: http, grpc, tcp, sql, amqp, redis
`description`	`string`	No	Purpose of this connection

Example:

{
  "port": 8080,
  "protocol": "grpc",
  "description": "User authentication"
}

Endpoint Object¶

Represents an exposed port/protocol.

Field	Type	Required	Description
`port`	`integer`	Yes	Port number
`protocol`	`string`	Yes	Protocol
`description`	`string`	No	Endpoint description

AWSResources Object¶

Contains AWS-specific resource bindings.

Field	Type	Description
`rds`	`[]RDSInstance`	RDS database instances
`dynamodb`	`[]DynamoDBTable`	DynamoDB tables
`sqs`	`[]SQSQueue`	SQS queues
`sns`	`[]SNSTopic`	SNS topics
`s3`	`[]S3Bucket`	S3 buckets
`bedrock`	`[]BedrockModel`	Bedrock AI models
`vpc`	`string`	VPC identifier
`subnets`	`[]string`	Subnet identifiers
`securityGroups`	`[]string`	Security group identifiers

RDSInstance Object¶

Field	Type	Required	Description
`name`	`string`	Yes	Instance identifier
`engine`	`string`	No	Database engine (mysql, postgres, aurora-mysql, etc.)
`port`	`integer`	No	Port number (defaults based on engine)

GCPResources Object¶

Contains GCP-specific resource bindings.

Field	Type	Description
`cloudsql`	`[]CloudSQLInstance`	Cloud SQL instances
`pubsub`	`[]PubSubTopic`	Pub/Sub topics
`gcs`	`[]GCSBucket`	GCS buckets
`vpcNetwork`	`string`	VPC network name

CloudflareResources Object¶

Contains Cloudflare resource bindings.

Field	Type	Description
`zone`	`string`	DNS zone
`workers`	`[]CloudflareWorker`	Cloudflare Workers
`r2Buckets`	`[]R2Bucket`	R2 storage buckets

Deployments Object¶

Maps deployment configurations to services.

Field	Type	Description
`helm`	`map[string]HelmDeployment`	Helm chart references
`terraform`	`map[string]TerraformDeployment`	Terraform module references

HelmDeployment Object¶

Field	Type	Required	Description
`chart`	`string`	Yes	Chart name or URL
`version`	`string`	No	Chart version
`repo`	`string`	No	Helm repository URL
`valuesFile`	`string`	No	Path to values file
`services`	`[]string`	No	Services this chart deploys

TerraformDeployment Object¶

Field	Type	Required	Description
`source`	`string`	Yes	Module source
`version`	`string`	No	Module version
`path`	`string`	No	Path within source
`resources`	`[]string`	No	Resources this module manages

Network Object¶

Represents a network boundary.

Field	Type	Description
`description`	`string`	Network description
`cidr`	`string`	CIDR block
`rules`	`[]NetworkRule`	Firewall rules

NetworkRule Object¶

Field	Type	Required	Description
`direction`	`string`	Yes	"inbound" or "outbound"
`fromService`	`string`	No	Source service (inbound)
`toService`	`string`	No	Target service (outbound)
`port`	`integer`	Yes	Port number
`protocol`	`string`	Yes	tcp or udp
`action`	`string`	Yes	"allow" or "deny"

Rendering¶

System-spec documents can be rendered to multiple visualization formats:

Format	Description	Use Case
D2	D2 diagram language	Static diagrams, documentation
Mermaid	Mermaid syntax	Markdown embedding, GitHub
Cytoscape	Cytoscape.js JSON	Interactive web visualization
Sigma	Sigma.js JSON	Large graph visualization
DOT	GraphViz DOT	PDF/PNG generation

Validation¶

A valid system-spec document MUST:

Have a non-empty name field
Have at least one service in services
Have a valid image.name for each service
Only reference services that exist in services within connections
Have valid port numbers (1-65535) in all connections

Security Considerations¶

Repository URLs MAY contain authentication tokens; treat system-spec documents as potentially sensitive
Image digests SHOULD be used in production to prevent supply chain attacks
VPC and security group identifiers are infrastructure metadata; access SHOULD be controlled

Appendix A: JSON Schema¶

The authoritative JSON Schema for this version is located at system.schema.json in this directory.

The schema is generated from Go types using github.com/invopop/jsonschema and validated with schemalint.

Appendix B: Go SDK¶

The Go SDK is available at github.com/plexusone/system-spec.

import (
    "github.com/plexusone/system-spec/spec"
    "github.com/plexusone/system-spec/graph"
    "github.com/plexusone/system-spec/render"
)

// Load and validate
sys, err := spec.LoadFromFile("system.json")

// Convert to graph
g := graph.FromSystem(sys)

// Render to D2
renderers := render.NewRenderers()
output, err := renderers.D2.Render(g)