SequenceStack Open Specification (SSOS) Version: 1.0.0 Introduction

The SequenceStack Open Specification (SSOS) is a structured, JSON-based standard for defining business- and context-aware sequence diagrams. It is designed for interoperability, enabling industries and government to integrate and utilize sequence diagrams seamlessly within their workflows. The goal of SSOS is to provide a comprehensive format that supports exportability, importability, and extensibility.

View API Documentation Contribute

Core Structure

SSOS is composed of the following primary sections:

1.Info Object
2.Actors Object
3.Messages Object
4.Metadata Object
5.Extensions

1. Info Object

The Info object contains metadata about the sequence diagram specification.

FIELD	TYPE	DESCRIPTION	REQUIRED
title	String	A brief title for the specification.	Yes
description	String	A detailed description of the sequence diagram's purpose.	Yes
version	String	The version of the specification being used.	Yes
contact	Object	Contact information for the specification owner.	No

2. Actors Object

Defines the entities involved in the sequence diagram. Each entity must have a unique identifier and type.

FIELD	TYPE	DESCRIPTION	REQUIRED
id	String	A unique identifier for the actor.	Yes
type	Enum	The type of actor (`actor`, `participant`, `database`, etc.).	Yes
name	String	The display name of the actor.	Yes
metadata	Object	Business and context-specific metadata (e.g., roles, systems).	No

3. Messages Object

Defines the interactions between actors, specifying the direction, type, and content of each message.

FIELD	TYPE	DESCRIPTION	REQUIRED
from	String	ID of the sending actor.	Yes
to	String	ID of the receiving actor.	Yes
message	String	The content of the message.	Yes
style	Enum	The type of line (`solid`, `dashed`, `lost`, etc.).	No
metadata	Object	Additional context about the message (e.g., timestamps).	No

4. Metadata Object

A general-purpose object for embedding additional information, such as business rules, context, or custom attributes.

FIELD	TYPE	DESCRIPTION	REQUIRED
key	String	The metadata key (e.g., `priority`).	Yes
value	String	The value associated with the metadata key.	Yes

5. Extensions

Custom properties can be added via extensions to accommodate use cases not covered by the core specification. Extensions must use the prefix x-.

FIELD	TYPE	DESCRIPTION	REQUIRED
x-<key>	Any	User-defined property with the prefix `x-`.	No

Design Principles

1.
Interoperability: JSON-based format for easy integration with APIs and third-party tools.
2.
Simplicity: Focused fields to reduce complexity and improve readability.
3.
Business-Aware: Support for embedding contextual and business-specific metadata.
4.
Extensibility: Allow custom extensions without breaking compatibility.

Example Specification

Below is an example of how a sequence diagram could be defined using the SSOS format.

{
  "openSequenceSpec": "1.0.0",
  "info": {
    "title": "Order Processing Workflow",
    "description": "This diagram models the steps in processing an order.",
    "version": "1.0.0",
    "contact": {
      "name": "John Doe",
      "email": "john.doe@company.com"
    }
  },
  "actors": [
    {
      "id": "customer",
      "type": "actor",
      "name": "Customer"
    },
    {
      "id": "system",
      "type": "participant",
      "name": "Order System"
    },
    {
      "id": "db",
      "type": "database",
      "name": "Order Database"
    }
  ],
  "messages": [
    {
      "from": "customer",
      "to": "system",
      "message": "Place Order",
      "style": "solid"
    },
    {
      "from": "system",
      "to": "db",
      "message": "Save Order",
      "style": "dashed"
    },
    {
      "from": "db",
      "to": "system",
      "message": "Confirmation",
      "style": "solid"
    }
  ],
  "metadata": {
    "priority": "high",
    "use_case": "ecommerce"
  },
  "extensions": {
    "x-custom-attribute": "value"
  }
}

Adoption and Integration

1.
Exportability: Diagrams can be exported in the JSON format for compatibility with other systems.
2.
Importability: Supports the ingestion of compliant JSON diagrams to populate SequenceStack's tools.
3.
Auditability Use: Structured to meet government standards for interoperability and auditability.