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:
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"
}
}