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.

API 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.

json
{ "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.