Architecture Schema

Introduction

The schema defines a way to describe the software architecture and its components. It is used to describe the architecture of a system, and to document the design decisions that have been made.

The document supports medical device manufacturers to perform regulatory activities defined in ISO 62304.

Definitions

Architecture Document

A self-contained or composite document that describes the architecture of a system, and the ways the software is deployed.

Specification

Version

The specification is versioned using a major.minor versioning scheme. The major version is incremented when the specification is changed in a way that is not backwards compatible. The minor version is incremented when the specification is changed in a way that is backwards compatible.

Format

An architecture document that conforms with the Software architecture specification is itself a JSON object, which may be represented either in JSON or YAML format.

Document Structure

The Software document is made up of a single document object.

It is RECOMMENDED that the document is named architecture.json or architecture.yaml.

Rich Text Formatting

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.30. Tooling MAY choose to ignore some CommonMark features to address security concerns.

Schema

Software object

This is the root object of the document. It MUST contain the following fields:

Field name	Type	Description	Required
specVersion	string	The version of the specification that the document conforms to. Currently this MUST be `0.1`.	yes
elements	[Element]	An array of Element objects.	yes
environment	[Environment]	An array of Environment objects.

Element object

The element object allows you to describe a component of the software architecture. The components can be grouped into a hierarchy by using the parent field. Each component can interact with other components by using the relationships field.

Field name	Type	Description	Required
id	string	The unique identifier of the element.	yes
role	enum	The role of the element. Can be one of `actor`, `system`, `item` and `external`.	yes
name	string	The name of the element.	yes
description	string	A description of the element.	yes
parent	string	The id of the parent element.
relationships	[Relationship]	An array of Relationship objects.

Environment object

The environment object allows to describe the environment in which the software is deployed, e.g. production, development, test, etc.

Field name	Type	Description	Required
name	string	The name of the environment. MUST be unique.	yes
description	string	A description of the environment.	yes
nodes	array	An array of objects. The property `type` serves as discriminator.	yes

The specification allows a loose and strict way of describing environments The loose mode is to describe the environment as a set of Node and Infra objects. The strict mode is to describe the environment as a set of nodes that.

BaseNode object

The base node object allows you to describe the common properties of the elements in environment in which the software is deployed. All environment objects MUST extend this object.

Field name	Type	Description	Required
type	[`node`, `infra`] or [`application`, `framework`, `library`, `container`, `service`, `device`, `operating-system`, `firmware`, `file`]	The type of the node.	yes
id	string	The unique identifier of the node. MUST be unique with an environment	yes
name	string	The name of the node.	yes
description	string	A description of the node.	yes
parent	string	The id of the parent node.
version	string	The version of the node.
relationships	[Relationship]	An array of Relationship objects.

Node object

The node object allows you to describe a node in the environment.

Field name	Type	Description	Required
type	`node`	The type of the node.	yes
parent	string	The id of the parent node. The parent node must be of type `node`.
instance	string	The id of the software `item` that is instantiated on the node.

Infra object

The infra object allows you to describe a piece of infrastructure in the environment. It is usually an external system that is used by the software.

Field name	Type	Description	Required
type	`infra`	The type of the infrastructure.	yes
relationships	[Relationship]	An array of Relationship objects.

Service object

Device object

Relationship object

The relationship object allows you to describe the interaction between two components. The component where the relationship is defined is the source of the relationship. The target of the relationship is defined by the target field.

Field name	Type	Description
target	string	The id of the target element.
description	string	A description of the relationship.

Examples

Software document

The following is an example of a Software document:

elements:
  - id: user
    name: User
    role: actor
    description: User
    relationships:
      - target: webapp
        description: Uses
  - id: system
    name: project
    role: system
    description: This is made for docs
  - id: webapp
    name: WebApp
    role: item
    parent: system
    description: The web application
    relationships:
      - target: api
        description: uses
  - id: api
    name: API
    role: item
    parent: system
    description: The backend API
specVersion: '0.1'

The document is rendered in CompliancePal as follows:

Software with environment

The following is an example of a Software document with an environment:

elements:
  - id: architect
    name: Architect
    role: actor
    description: Software architect is the best
    relationships:
      - target: webapp
        description: Uses
      - target: git
        description: ''
  - id: co
    name: Compliance Officer
    role: actor
    description: Compliance Officer
    relationships:
      - target: webapp
        description: Uses
  - id: system
    name: simple-app
    role: system
    description: This is a simple app used to test the boundaries of the system
  - id: app
    name: App server
    role: item
    type: container
    parent: system
    description: The application server
  - id: webapp
    name: WebApp
    role: item
    type: application
    parent: app
    description: The web application
    relationships:
      - target: api
        description: uses
  - id: api
    name: API
    role: item
    type: application
    parent: app
    description: The backend API
    relationships:
      - target: db
        description: reads/writes
      - target: mail
        description: sends
  - id: db
    name: Database
    role: item
    parent: system
    version: 1.2.3
    description: Database
  - id: mail
    name: Mail server
    role: item
    parent: system
    description: Sends mails
  - id: git
    name: Git
    role: external
    description: Git provider
    relationships:
      - target: api
        description: ''
specVersion: '0.1'
environments:
  - name: local
    nodes:
      - id: laptop
        key: value
        name: Laptop
        type: device
        description: Developer's laptop
      - id: macos
        name: MacOS
        type: operating-system
        parent: laptop
        description: ''
      - id: vscode
        name: VS Code
        type: application
        parent: macos
        description: IDE used for development
        relationships:
          - target: git
            description: save/commit
          - target: dev-container
            description: mounts
      - id: git
        name: Git
        type: application
        parent: macos
        description: Version control
        relationships:
          - target: gh
            description: pull/push
      - id: dev-container
        name: Dev container
        type: container
        parent: macos
        instance: app
        description: The development container
        relationships:
          - target: mariadb
            description: save/query
          - target: git
            description: reload
      - id: browser
        name: Web browser
        type: container
        parent: macos
        instance: webapp
        description: Web browser
        relationships:
          - target: dev-container
            description: hmr
          - target: storybook
            description: hmr
      - id: storybook-ui
        name: Storybook UI
        type: application
        parent: browser
        description: Component development
      - id: storybook
        name: Storybook
        type: application
        parent: macos
        description: Database
        relationships:
          - target: git
            description: reload
      - id: jest
        name: Jest
        type: application
        parent: macos
        description: Test harness
        relationships:
          - target: git
            description: reload
      - id: mariadb
        name: MariaDB
        type: container
        parent: macos
        instance: db
        description: Database
      - id: gh
        name: GitHub
        type: service
        provider:
          url: https://www.github.com
          name: GitHub
        endpoints:
          - https://api.github.com
        description: GitHub
    description: The local development environment

The environment is rendered by CompliancePal as follows:

Environment

Tooling

VS Code

The VS Code allows you to validate your YAML documents against the CompliancePal architecture schema. It also provides autocompletion for the elements in the document.

You need to install the YAML extension and configure the schema in your VS Code workspace settings. The following is an example of the settings, assuming that the architecture.yaml file is in the root of your workspace:

{
  "yaml.schemas": {
    "https://app.compliancepal.eu/api/v1/schemas/architecture": "architecture.yaml"
  }
}