Getting started
Get started with Cloud requirements definition with this reference and tools.
This document is licensed under The Apache License, Version 2.0.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Introduction
The Cloud Design Specification (the "CDS") defines cloud usage requirements by JSON/YAML codes for both human and computer comprehension.
In this document, CDS is the name of the language specification itself, and at the same time, it
indicates the code described based on the cloud design specification. Previously, the latter was clearly
distinguished as Cloud Design Definition ( the "CDD" ), but it has been unified into CDS to prevent a
mess of terms.
So there is a description of CDD in some tools and peripheral documents, still it is no problem that you
think it is synonymous with CDS.
Extension of the existing provisioning codes
CDS is a requirements definition code that complements existing provisioning code such as CloudFormation. System
requirements such as users and access volumes are described in this own specifications, and cloud resource
definitions are expressed by references to existing provisioning codes. This structure reduces the
learning cost of developers and encourages the utilization of existing code assets.
Please refer Resource object for the types of provisioning code that you can
use on CDD.
Tools
You can create, store, search, reuse the Cloud Designs by using various tools.
Cloud Design Schema
It is a JSON schema file that can be used to check the grammar of the CDS by
incorporating it into a third party editor.
ForkMe!
A cloud design management tool provided by Reindeer Technology PTE.LTD. It fulfills the
developer's desire to "fork (duplicate / derive) cloud design like software". (The Reindeer Project was
progressively incorporated into Reindeer Technology PTE. LTD.)
Reindeer Editor
A documentation generation tool supported by Reindeer Project. You can edit a CDS
and display
the cloud adoption report by using this.
General
Describing the general specification of Cloud Design.
Versions
The CDS is versioned using Semantic
Versioning 2.0.0 (SemVer) and follows
the below specification.
A version number is given incrementally as major.minor.patch. The
major.minor SHALL designate
the one or some feature set. And the .patch SHALL designate backward-compatible bug fixes.
So the patch version SHOULD NOT be considered by tooling, SHOULD NOT make any distinction about the feature
or tooling between 1.0.0 and 1.0.1 for example.
Format
The CDS is itself a JSON object, which MAY be represented either in JSON or YAML format. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
All field names in the specification are case confidential. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case inconfidential.
Structure
The CDS MAY consist of a single document or split into multiple parts at the user's discretion.
However, in the latter case, the root CDS MUST always contain all required parent
schemas.
Also, files referred to as parts are called CDS snippets, and SHOULD contain only components objects.
And the reference to the CDS snippet from the root file SHOULD be associated name in $ref
field.
And the root file SHOULD be named 'clouddesign.json' or 'clouddesign.yaml'.
Parent Schema
Describing the primary data structure of Cloud Design. In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
Cloud Design Object
This is the root object of the CDS.
Fixed Fields
Field Name
Type
Description
reindeer
string
REQUIRED.
This string MUST be the semantic version number of the CDS itself.
The reindeer field SHOULD be used by tools for interpreting the CDS.
This is not related to the info.version string.
Use '1.3.2' at ForkMe!
self
string
REQUIRED.
This string is the filename of the CDS. It MUST be with the extension, .json,
.yaml or .yml.
The self field SHOULD be used by tools for interpreting the CDS.
Use 'cloudDesign.json' at ForkMe!
info
REQUIRED. Provides metadata about the cloud adoption. The metadata MAY be used by tooling as required.
actors
[ Actor object |
string, Reference object]
REQUIRED. An array of actor objects, which provide information about the external user or system to which cloud computing is connected.
resources
Map[ string, Resource object ]
REQUIRED. An array of resource objects, which is pointing to the external documents (files written by provisioning codes) describing the cloud architecture.
contexts
Map[ string, Context object | string, Reference object]
REQUIRED. An array of context objects, which provide information about the relationship for achieving a specific purpose between actors and cloud resources.
components
Holds a set of reusable objects for different aspects of the CDS. All objects defined within the components object will have no effect on the Cloud Design unless they are explicitly referenced from properties outside the components object.
JSON example
{
"reindeer": "1.3.2",
"self": "cloudDesign.json"
"info": {
"title": {
"en": "Sample system",
"ja": "サンプルシステム",
},
Refer 'Info' schema
},
"actors": {
"customer": {
"title": {
"en": "Customers",
"ja": "顧客",
},
Refer 'Actor' schema
}
},
"resources": [
{
"$ref":"awsTemplate.json",
Refer 'Resources' schema
}
],
"contexts": {
"customerWebAccess": {
"title": {
"en": "Web access by customer",
"ja": "顧客によるウェブアクセス",
},
Refer 'Contexts' schema
}
},
"components": {
"actors": {
"operator": {
"title": {
"en": "Operator",
"ja": "運用者",
},
Refer 'Actor' schema
}
},
Refer 'Components' schema
(Components is an optional schema useful for reusing definitions)
}
Info object
The object provides metadata about the CDS. The metadata SHOULD be filled properly for helping others easy to search and find the CDS.
Fixed Fields
Field Name
Type
Description
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The title of the service, adopting this cloud design.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the service, adopting this cloud design.
It SHOULD be the concise memo including every keyword of the purpose and functions of the system.
This text MAY be used as the search index by external tools.
status
string
REQUIRED. The status of the CDS.
Valid values are idea, draft, production.
draft: Requirement unregistered or under definition.
prepared: State where requirements are defined.
designed: Design codes created based on requirements.
reviewed: Completed design review and modification.
designedAt
integer
REQUIRED. The time when the CDS was designed at. It MUST be the UNIXTIME format.
authors
Map[ string, string, Author object ]
REQUIRED. The authors of the CDS. This information MAY be used by external tools as the important evidence of involved person's skill and experience.
organizations
Map[ string, string, Organization object ]
Related organizations of the CDS. This information MAY be used by external tools as the important evidence of involved organization's skill and experience.
JSON example
{
"version": "1.0.0",
"license": {
"type": "CC0"
},
"title": {
"en": "Sample system",
"ja": "サンプルシステム",
"ru": "Образец системы"
},
"description": {
"en": "Sample description",
"ja": "説明サンプル",
"ru": "Пример описания"
},
"status": "draft",
"designedAt": "1548731447",
"authors": {
"sampleHandleNameA": {
"roles": ["designer"],
"joinedAt": 1548730447,
"leavedAt": 1548731447
},
"sampleHandleNameB": {
"roles": ["designer", "auditor"],
"joinedAt": 1548730447
}
},
"organizations": {
"sampleCompanyA": {
"joinedAt": 1548730447,
"leavedAt": 1548731447
},
"sampleCompanyB": {
"joinedAt": 1548730447,
"sign": xxxxxx123
}
}
}
YAML example
version: 1.0.0
license:
type: CC0
title:
en: Sample system
ja: サンプルシステム
ru: Образец системы
description:
en: Sample description
ja: 説明サンプル
ru: Пример описания
status: draft
designedAt: 1548731447
authors:
sampleHandleNameA:
roles:
- designer
joinedAt: 1548730447
leavedAt: 1548731447
sampleHandleNameB:
roles:
- designer
- auditor
sign: xxxxxxx123
joinedAt: 1548730447
organizations:
sampleHandleNameA:
joinedAt: 1548730447
leavedAt: 1548731447
sign: xxxxxxx123
sampleHandleNameB:
joinedAt: 1548730447
Actor objects
The objects provide information about users, operators or external systems the cloud will be connected with. It SHOULD be comprehensive for designing and auditing the CDS correctly.
Market type of actor object
This object provides information about an unspecified number of users, such as consumers and spectators belonging to a particular market. It is the kind of actor you SHOULD use, for example, when designing a limited network connection with an identifiable individual and cloud. The correct number SHOULD be provided in order to understand the number of users and the number of requests to be provided to the system.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'market'.
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The title of the actor.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the actor.
marketShare
float
REQUIRED. The share ratio of this
actor among the belonging market.
For example, 0.3 means 30%.
sourceIdentification
[ boolean ]
REQUIRED. Whether specific IP
address range or domains is assigned or not.
If true, identificationGroup property is required.
identificationGroup
string
The group name of IP address range, domains and so
on..
Required when sourceIdentification propery is true. And MUST NOT use when
sourceIdentification propery is false.
JSON Example
{
"type": "market",
"title": {
"en": "Customers",
"ja": "顧客",
"ru": "Клиенты"
},
"description": {
"en": "Users of our products.",
"ja": "当社製品の利用ユーザー",
"ru": "Пользователи нашей продукции."
},
"market": {
"title": {
"en": "65 years and over in U.S., July 2018",
"ja": "65才以上の人口 米国 2018年7月",
"ru": "65 лет и старше в США, июль 2018 года"
},
"description": {
"en": "General population data of U.S. at 2018 by govermental research.",
"ja": "米国政府による2018年の人口統計",
"ru": "Данные об общей численности населения США на 2018\nгод по данным государственных исследований."
},
"num": 51038120,
"estimatedBy": "U.S. Census Bureau",
"estimatedAt": 1530370800
},
"marketShare": 0.01,
"sourceIdentification": false
}
YAML Example
type: market
title:
en: Customers
ja: 顧客
ru: Клиенты
description:
en: Users of our products.
ja: 当社製品の利用ユーザー
ru: Пользователи нашей продукции.
market:
title:
en: 65 years and over in U.S., July 2018
ja: 65才以上の人口 米国 2018年7月
ru: 65 лет и старше в США, июль 2018 года
description:
en: General population data of U.S. at 2018 by govermental research.
ja: 米国政府による2018年の人口統計
ru: |
Данные об общей численности населения США на 2018
год по данным государственных исследований.
num: 51038120
estimatedBy: U.S. Census Bureau
estimatedAt: 1530370800
marketShare: 0.01
sourceIdentification: false
Persons type of actor object
The object provides information about a type of actor being consisted of one or a few persons like system operator. The kind of actor you SHOULD use, for example, when designing a limited network connection between an identifiable external system and cloud.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'persons'.
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The title of the group of persons.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the group of persons.
num
integer
REQUIRED. The number of members.
sourceIdentification
[ boolean ]
REQUIRED. Assigned specific IP
address range, domains and so on, or not.
If true, identificationGroup property is required.
identificationGroup
string
The group name of IP address range, domains and so
on.
Required when sourceIdentification propery is true. And MUST NOT use when
sourceIdentification propery is false.
JSON example
{
"type": "persons",
"title": {
"en": "Operators",
"ja": "運用担当者",
"ru": "операторы"
},
"description": {
"en": "Operators using management console.",
"ja": "管理コンソールを利用する運用担当者",
"ru": "Операторы, использующие консоль управления."
},
"num": 7,
"sourceIdentification": true,
"identificationGroup": "IPsOfOperatorGroupA"
}YAML example
type: persons
title: a
en: Operators
ja: 運用担当者
ru: операторы
description:
en: Operators using management console.
ja: 管理コンソールを利用する運用担当者
ru: Операторы, использующие консоль управления.
num: 7
sourceIdentification: true
identificationGroup: IPsOfOperatorGroupA
External system type of actor object
The object provides information about a type of actor being consisted of one or a few systems like external API, FILE interface and so on. The kind of actor you SHOULD use, for example, when designing a limited network connection between an identifiable external system and cloud.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'externalSystem'.
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The title of the external system interface.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the external system interface.
sourceIdentification
[ boolean ]
REQUIRED. Assigned specific IP
address range, domains and so on, or not.
If true, identificationGroup property is required.
identificationGroup
string
The group name of IP address range, domains and so
on..
Required when sourceIdentification propery is true. And MUST NOT use when
sourceIdentification propery is false.
JSON Example
{
"type": "externalSystem",
"title": {
"en": "API of SFA platform",
"ja": "SFAプラットフォームのAPI",
"ru": "API платформы SFA"
},
"description": {
"en": "Providing GET and POST interfaces of sales information.",
"ja": "販売情報のGETおよびPOSTインターフェースを提供する外部システム",
"ru": "Предоставление GET и POST интерфейсов информации о продажах."
},
"sourceIdentification": true,
"identificationGroup": "ipsOfSFA"
}YAML Example
type: externalSystem
title:
en: API of SFA platform
ja: SFAプラットフォームのAPI
ru: API платформы SFA
description:
en: Providing GET and POST interfaces of sales information.
ja: 販売情報のGETおよびPOSTインターフェースを提供する外部システム
ru: Предоставление GET и POST интерфейсов информации о продажах.
sourceIdentification: true
identificationGroup: ipsOfSFA
Resource object
The object provides information about cloud resources used by this system.
It MUST be references of the external file formatted by JSON or YAML.
And it SHOULD be well-formatted data for cloud automation tools like below.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED.
Type of the cloud automation language. It MUST be one of the following values.
acf : AWS CloudFormation.
arm : Azure Resource Manager.
gdm : Google Cloud Deployment Manager.
aro : Alibaba Cloud Resource Orchestration Service.
tfm : Terraform.
slf : Serverless Framework.
oth : Others.
$ref
string
REQUIRED.
Reference to the file written by cloud automation language. Same as the $ref item of Reference object.
This MUST point to the external file with extension, .json, .yaml, or
.yml.
And the extension SHOULD be used by external tools to detect the file format of the link.
JSON Example
{
"type": "acf",
"$ref": "xxx.json"
}
YAML Example
type: acf
$ref: xxx.json
Context object
The object provides information about the use case of the system by associating some actors and resources by the purpose of running the specific function. It SHOULD be comprehensive for designing and auditing the CDS correctly.
Fixed Fields
Field Name
Type
Description
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The title of the context.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the context.
trigger
Trigger objects | Reference object
REQUIRED. One of the types of trigger object. The trigger means the initial event of this context.
traffics
Map[ string, Traffic objects ] | [ Reference object ]
REQUIRED. Holding the list of traffic objects. Each traffic is one of the types of traffic objects. The traffic means related data transfer route within the context.
maxPerformanceDurationRatio
float
Shows the monthly duration ratio of maximum performance. When calculating the cost required for the context, this value is used to synthesize the max and min values of each Range values object included in trigger and traffic. For example, in the case of a design that improves DAU by advertising effect only 3 days a month, the DAU value is expressed as min: 0.01, max: 0.1, and this value is expressed as 0.1. CloudDesign expresses performance and cost based on monthly usage, but with this value, it is possible to record a design that expects a maximum instantaneous performance of 100 rps while the monthly average is 1 rps.
JSON Example
{
"title": {
"en": "Customers view",
"ja": "カスタマー閲覧",
"ru": "Просмотр клиента"
},
"description": {
"en": "Custormer's web site view of static contents through internet.",
"ja": "インターネット経由の静的コンテンツ閲覧",
"ru": "Просмотр статического содержимого через Интернет"
},
"trigger": {
"$ref": "#/components/triggers/trigger1"
},
"traffics": [
{"$ref": "#/components/traffics/traffic1"},
{"$ref": "#/components/traffics/traffic2"},
{"$ref": "#/components/traffics/traffic3"}
],
"maxPerformanceDurationRatio": 0.1
}YAML Example
title:
en: Customers view
ja: カスタマー閲覧
ru: Просмотр клиента
description:
en: Custormer's web site view of static contents through internet.
ja: インターネット経由の静的コンテンツ閲覧
ru: Просмотр статического содержимого через Интернет
trigger:
$ref: #/components/triggers/trigger1
traffics:
- $ref: #/components/traffics/traffic1
- $ref: #/components/traffics/traffic2
- $ref: #/components/traffics/traffic3
maxPerformanceDurationRatio: 0.1
Components object
Holds a set of reusable objects for different aspects of the CDS. All objects defined within the components object will have no effect on the CDS unless they are explicitly referenced from properties outside the components object.
Fixed Fields
Field Name
Type
Description
Child Schema
Describing the child of the primary data structure of Cloud Design. In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
License object
License information for the CDS.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED.
This is the CDS license type. MUST be one of the following values: (CC0 recommended)
CC0
Apache-2.0
MIT
BSD-2-Clause
OtherOpen
Closed
provider
string
The license provider or license name. You MUST not use this parameter when the type is not OtherOpen and Closed.
JSON Examples
RECOMMENDED
{
"type": "CC0"
}
{
"type": "Closed",
"provider": "Reindeer technology PTE.LTD."
}YAML Examples
RECOMMENDED
type: CC0
type: Closed
url: Reindeer technology PTE.LTD.Author object
The object provides information about authors and their roles on the CDS. It SHOULD be comprehensive for helping others find the person who has correct knowledge about the system, the cloud technology, and the market the system is serving.
Fixed Fields
Field Name
Type
Description
roles
[ string ]
REQUIRED. Holds a set of roles
related to the CDS.
Each role MUST be one of below strings.
planner: Planing the cloud adoption.
designer: Design the cloud architecture.
auditor: Audit the CDS.
operator: Operating the system designed by CDS.
others: Other role.
joinedAt
integer
REQUIRED. The time when the author was joined at this CDS creation / operation. It MUST be the UNIXTIME format.
leavedAt
integer
REQUIRED. The time when the author was leaved at this CDS creation / operation. It MUST be the UNIXTIME format.
sign
string
Sign of the author.
JSON Example
{
"roles": ["designer","auditor"],
"joinedAt": 1548730447,
"leavedAt": 1548731447,
"sign": ABC123DEF456HIJ789#abc
}
YAML Example
roles:
- designer
- auditor
joinedAt: 1548730447
leavedAt: 1548731447
sign: ABC123DEF456HIJ789#abc
Organization object
The object provides information about organizations related to the CDS. It SHOULD be comprehensive for helping others find the organization who has correct knowledge about the system, the cloud technology, and the market the system is serving.
Fixed Fields
Field Name
Type
Description
joinedAt
integer
REQUIRED. The time when the author was joined at this CDS creation / operation. It MUST be the UNIXTIME format.
leavedAt
integer
REQUIRED. The time when the author was leaved at this CDS creation / operation. It MUST be the UNIXTIME format.
sign
string
Sign of the author.
JSON Example
{
"joinedAt": 1548730447,
"leavedAt": 1548731447,
"sign": ABC123DEF456HIJ789#abc
}
YAML Example
joinedAt: 1548730447
leavedAt: 1548731447
sign: ABC123DEF456HIJ789#abc
Market object
The object provides information about the market. It MAY be including the result of your research or third party's survey.
Fixed Fields
Field Name
Type
Description
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The content SHOULD be unique on this CDS by including the words describing a member's properties,
interest, estimated year and so on.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the market.
It SHOULD be including the words describing the author, estimation purpose and so on.
This text MAY help the designer's decision whether this information can be reused by other design or
not.
num
integer
REQUIRED. The number of members.
estimatedBy
string
REQUIRED. The author of this estimation.
estimatedAt
integer
REQUIRED. The time when it was estimated at. It MUST be the UNIXTIME format.
JSON Example
{
"title": {
"en": "65 years and over in U.S., July 2018",
"ja": "65才以上の人口 米国 2018年7月",
"ru": "65 лет и старше в США, июль 2018 года"
},
"description": {
"en": "General population data of U.S.\n at 2018 by govermental research.",
"ja": "米国政府による2018年の人口統計",
"ru": "Данные об общей численности населения США\n на 2018 год по данным государственных исследований."
},
"population": 51038120,
"estimatedBy": "U.S. Census Bureau",
"estimatedAt": 1530370800
}
YAML Example
title:
en: 65 years and over in U.S., July 2018
ja: 65才以上の人口 米国 2018年7月
ru: 65 лет и старше в США, июль 2018 года
description:
en: |
General population data of U.S.
at 2018 by govermental research.
ja: 米国政府による2018年の人口統計
ru: |
Данные об общей численности населения США
на 2018 год по данным государственных исследований.
population: 51038120
estimatedBy: U.S. Census Bureau
estimatedAt: 1530370800
Trigger objects
The objects provide information about the initial event of the context. It MAY be person's web site access to the server, or it MAY be an automated timed call to the external API.
Web access type of trigger object
This is a kind of trigger by actors. Describing the actor's web access to cloud resources. The actor MAY be human, or external computing.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'webAccess'.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the trigger.
It SHOULD be the concise memo describing the purpose of this trigger.
infoType
REQUIRED. Reference to the InfoType object. Indicates the type of information handled in this trigger.
ports
[ integer ]
REQUIRED.
Port numbers required at the end points (defined at the end field) of this trigger.
internet
[ boolean ]
REQUIRED. Use internet or not for this trigger.
restriction
[ boolean ]
REQUIRED. Source IP, Domain or the other restriction at the end points of this trigger.
dau
REQUIRED.
Daily Active User ratio. For example,
it will be 0.01 in case of that avarage 1 percent of actors, referred at this
start field,
will access to the resources, referred at this end field, per day.
pagesVisit
REQUIRED. Average page numbers per visit. Representing how many pages visitors will open per visit.
reqPage
REQUIRED. Average request numbers per page. Representing how many requests (Requests to images and HTML etc. that make up the page) will be used per page.
busyHours
REQUIRED.
Busy hours per day. For example, it's 6, in the case of that most access is concentrated
amoung AM 9:00 - AM 11:00 and PM 17:00 - PM 19:00 per day.
Please note that the max value is "smaller" than the min value, as 1 hour is
generally considered to be "more concentrated" than 8 hours.
Example: If the case where users access evenly within 8 hours during the day is the minimum performance,
and the case where access is during the 1 hour of the lunch break is the maximum performance, it is
expressed as min: 8, max: 1.
postsVisit
REQUIRED.
Representing what percentage of the visitors will POST.
For example, it's 0.1 in case of that 100 POST will sent per day
among 100,000 actors and 0.01 dau.
start
REQUIRED. It MUST be a reference to the actor objects. The start point of this trigger.
end
REQUIRED. It MUST be references to the each resource item described in the resource object. The end point of this traffic.If multiple resources are specified, the traffic from start is determined to be evenly divided into each resource. Connections to resources with different traffic weights or different uses, connection ports, etc. should not be listed here. Write it as the end of the new context. Example: If you list two web servers for an actor sending a 10GB request, each server will receive 5GB of requests. In the case of designing to access the static content server and the dynamic content server at a ratio of 9: 1, do not write both servers together in one end, and the context that provides static content and the context that provides dynamic content. Please describe each server in each end separately.
endpointTitle
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The name of the endpoint.
storedRatio
REQUIRED.
The ratio of the end's stored data volume among the received data.
For example, if this trigger's end stores all of the data that the actor sends to
end, this value will be 1.0. And it's 0 if not stored.
storedInfoType
Reference to the InfoType object.
Indicates the type of information stored at the ends of this trigger.
storageDescription
Map[ string, string ]
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the endpoint.
It SHOULD be the concise memo describing the purpose of storage of the ends in this trigger.
JSON Example
{
"type": "webAccess",
"description": {
"en": "API call for movie data acquisition.",
"ja": "動画データ取得のためのAPI呼び出し。",
"ru": "API вызов для сбора данных фильма"
},
"infoType": {
"$ref": "#/components/infoType/general"
},
"ports": [443],
"internet": true,
"restriction": false,
"dau": {"max": 0.1, "min": 0.03},
"pagesVisit": {"max": 10, "min": 10},
"kbPage": {"max": 1024, "min": 1024},
"reqPage": {"max": 100, "min": 100},
"busyHours": {"max": 3, "min": 3},
"postRatio": {"max": 0.1, "min": 0.001},
"kbPost": {"max": 100, "min": 100},
"start": {
"$ref": "#/actors/customer"
},
"end": [
{"$ref": "#/resources/awsCloudEnvironment/data/Resources/cloudFront"}
],
"endpointTitle": {
"en": "LoadBalancer",
"ja": "ロードバランサ",
"ru": "Балансировщик нагрузки"
},
"storedRatio": {"max": 0.3, "min": 0.1},
"storedInfoType": {
"$ref": "#/components/infoType/general"
},
"storageDescription": {
"en": "Logging for API usage tracing.",
"ja": "API利用状況把握のためのログ保管",
"ru": "Хранение журнала для статуса использования API"
}
}YAML Example
type: webAccess
description: {
en: Static content distribution,
ja: 静的コンテンツの配信,
ru: Распределение статического контента
infoType:
$ref: #/components/infoType/general
ports: [443]
internet: true
restriction: false
dau: {max: 0.1, min: 0.03}
pagesVisit: {max: 10, min: 10}
kbPage: {max: 1024, min: 1024}
reqPage: {max: 100, min: 100}
busyHours: {max: 3, min: 3}
postRatio: {max: 0.1, min: 0.001}
kbPost: {max: 100, min: 100}
start:
$ref: #/actors/customer
end:
- $ref: #/resources/awsCloudEnvironment/data/Resources/cloudFront
endpointTitle:
en: LoadBalancer
ja: ロードバランサ
ru: Балансировщик нагрузки
storedRatio: {max: 0.5, min: 0.3}
storedInfoType:
$ref: #/components/infoType/general
storageDescription: {
en: Logging for API usage tracing.,
ja: API利用状況把握のためのログ保管,
ru: Хранение журнала для статуса использования API
Timed action type of trigger object
This is a kind of trigger by actors or resources. Describing the timed action from actors or cloud computing resources to other ones.
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'timedAction'.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the trigger.
It SHOULD be the concise memo describing the purpose of this trigger.
infoType
REQUIRED. Reference to the InfoType object. Indicates the type of information handled in this trigger.
ports
[ integer ]
REQUIRED. Port numbers required at the end points of this trigger.
internet
[ boolean ]
REQUIRED. Use internet or not for this connection.
restriction
[ boolean ]
REQUIRED. Source IP, Domain or the other restriction at the end points of this trigger.
onlineRps
REQUIRED.
Number of requests per second when this trigger fires.
Specify the required performance from the start point (start field) to the end point
(end field).
For example, if the batch system runs every Monday morning and each batch accesses the external API
with a throughput of 2 times per second it is 2.0.
reqMonth
REQUIRED.
Monthly request numbers from the start point to the endpoints.
For example, it's 9000 in case of that the batch system sends mail magazine 3 times to 1000
persons per month.
kbRequest
REQUIRED. Request data size per request from the start point to the end point as the unit of KB.
kbResponse
REQUIRED. Response data size per request from the start point to the end point as the unit of KB.
start
REQUIRED. It MUST be a reference to the actor object or the resource object. The start point of this trigger.
end
[ Reference object ]
REQUIRED. It MUST be a reference to the actor object or the resource object. The end point of this traffic.If multiple resources are specified, the traffic from start is determined to be evenly divided into each resource. Connections to resources with different traffic weights or different uses, connection ports, etc. should not be listed here. Write it as the end of the new context.
endpointTitle
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The name of the endpoint.
storedRatio
REQUIRED.
The ratio of the stored data volume among the received data to the ends. For example,
it is 1.0 in case of that the database resource in this trigger is received 10GB/Month from
the app server and store all of them to the database.
When the ends don't store the traffic data, it's 0.
storedInfoType
Reference to the InfoType object. Indicates the type of information stored at the ends of this trigger.
storageDescription
Map[ string, string ]
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the endpoint.
It SHOULD be the concise memo describing the purpose of storage of the ends in this trigger.
JSON Example
{
"type": "timedAction",
"description": {
"en": "API call for movie data acquisition.",
"ja": "動画データ取得のためのAPI呼び出し。",
"ru": "API вызов для сбора данных фильма"
},
"infoType": {
"$ref": "#/components/infoType/general"
},
"ports": [443],
"internet": false,
"restriction": false,
"onlineRps": {"max": 3, "min": 1},
"reqMonth": {"max": 9000, "min": 5000},
"kbRequest": {"max": 0.01, "min": 0.01},
"kbResponse": {"max": 1, "min": 1},
"start": {
"$ref": "#/resources/awsCloudEnvironment/resources/jobServer"
},
"end": [
{"$ref": "##/actors/api"}
],
"endpointTitle": {
"en": "LoadBalancer",
"ja": "ロードバランサ",
"ru": "Балансировщик нагрузки"
},
"storedRatio": {"max": 0.3, "min": 0.1},
"storedInfoType": {
"$ref": "#/components/infoType/general"
},
"storageDescription": {
"en": "Logging for API usage tracing.",
"ja": "API利用状況把握のためのログ保管",
"ru": "Хранение журнала для статуса использования API"
}
}YAML Example
type: timedAction
description: {
en: Static content distribution,
ja: 静的コンテンツの配信,
ru: Распределение статического контента
infoType:
$ref: #/components/infoType/general
ports: [443]
internet: false
restriction: false
onlineRps: {max: 3, min: 1}
reqMonth: {max: 9000, min: 5000}
kbRequest: {max: 0.01, min: 0.01}
kbResponse: {max: 1, min: 1}
start:
$ref: #/resources/awsCloudEnvironment/resources/jobServer
end:
- $ref: #/actors/api
endpointTitle:
en: LoadBalancer
ja: ロードバランサ
ru: Балансировщик нагрузки
storedRatio: {max: 0.5, min: 0.3}
storedInfoType:
$ref: #/components/infoType/general
storageDescription: {
en: Logging for API usage tracing.,
ja: API利用状況把握のためのログ保管,
ru: Хранение журнала для статуса использования API
Traffic objects
The objects provide information about related traffics within the context. This must be used in the subsequent processing of the trigger event. For example, dynamic content request from Web server to application server, data storage from application server to database, etc. are expressed.
Pass through ratio type of traffic object
This is a kind of traffic object.
It can represent traffic that occurs in the form of passing a part of the request
received from the start point to the subsequent resources.
For example, it can represent a chain of communication where a load balancer sends a received request to a
web server,
and an application generates a mail delivery queue based on the received request.
At this time, the size of the data received by this traffic endpoint (end field) is
the percentage of the request received by the previous communication (source field) of this
traffic.
Therefore, if you extend the data to 3 MB in the server and pass it to the end point of this traffic after
the previous communication receives the 1 MB POST value,
the data size can be expressed as 300% (passThroughReqRatio> field's value is 3).
Fixed Fields
Field Name
Type
Description
type
string
REQUIRED. Fixed value,
'passThroughRatio'.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the traffic.
It SHOULD be the concise memo describing the purpose of this traffic.
infoType
REQUIRED. Reference to the InfoType object. Indicates the type of information handled in this traffic.
ports
[ integer ]
REQUIRED. Port numbers required at the end points of this traffic.
internet
[ boolean ]
REQUIRED. Use internet or not for this connection.
restriction
[ boolean ]
REQUIRED. Source IP, Domain or the other restriction at the end points of this trigger.
source
REQUIRED.
References to the trigger object or the traffic
object.
The start point of this traffic. This effects to or is affected by all of the resources or actor object
described in the end fields.
end
[ Reference object ]
REQUIRED. References to the actor objects or the each resource item described in the resource object. The end point of this traffic.If multiple resources are specified, the traffic from start is determined to be evenly divided into each resource. Connections to resources with different traffic weights or different uses, connection ports, etc. should not be listed here. Write it as the end of the new context.
endpointTitle
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The name of the endpoint.
passThroughReqRatio
REQUIRED.
Indicates what percentage of the requests received by prior trigger or
traffic (source field) will flow to the endpoint (end) of this traffic.
For example, if the former trigger receives 100,000/M requests from the user and use internal cash for
50%
response and pass 50% request to this traffic, this value will be 0.5.
compositResRatio
REQUIRED.
Based on the size of the response data handled by the former trigger or traffic (source
field),
describes that this traffic response what percentage of that size to the source.
For example, if the former trigger returns data of 10GB/Month to the user and this
compositResRatio is 0.5,
this traffic will response 5GB/Month of data to the former trigger.
storedRatio
REQUIRED.
The ratio of the stored data volume among the received data to the ends. For example,
it is 1.0 in case of that the database resource in this traffic is received 10GB/Month from
the app server and store all of them to the database.
When the ends don't store the traffic data, it's 0.
storedInfoType
Reference to the InfoType object. Indicates the type of information stored at the ends of this traffic.
storageDescription
Map[ string, string ]
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The description of the endpoint.
It SHOULD be the concise memo describing the purpose of storage of the ends in this traffic.
JSON Example
{
"type": "passThroughRatio",
"description": {
"en": "Static content distribution",
"ja": "静的コンテンツの配信",
"ru": "Распределение статического контента"
},
"infoType": {
"$ref": "#/components/infoType/general"
},
"ports": [80],
"internet": false,
"restriction": false,
"source": {"$ref": "#/trigger/customer"},
"end": [
{"$ref": "#/resources/awsCloudEnvironment/data/Resources/s3"}
],
"passThroughReqRatio": {"max": 1, "min": 0.1},
"compositResRatio": {"max": 0.5, "min": 0.5},
"endpointTitle": {
"en": "LoadBalancer",
"ja": "ロードバランサ",
"ru": "Балансировщик нагрузки"
},
"storedRatio": {"max": 0.3, "min": 0.1},
"storedInfoType": {
"$ref": "#/components/infoType/general"
},
"storageDescription": {
"en": "Logging for API usage tracing.",
"ja": "API利用状況把握のためのログ保管",
"ru": "Хранение журнала для статуса использования API"
}
}YAML Example
type: passThroughRatio
description: {
en: Static content distribution,
ja: 静的コンテンツの配信,
ru: Распределение статического контента
infoType:
$ref: #/components/infoType/general
ports: [80]
internet: false
restriction: false
source:
$ref: #/trigger/customer
end:
- $ref: #/resources/awsCloudEnvironment/data/Resources/s3
passThroughReqRatio: {max: 1, min: 0.1}
compositResRatio: {max: 0.5, min: 0.5}
endpointTitle:
en: LoadBalancer
ja: ロードバランサ
ru: Балансировщик нагрузки
storedRatio: {max: 0.5, min: 0.3}
storedInfoType:
$ref: #/components/infoType/general
storageDescription: {
en: Logging for API usage tracing.,
ja: API利用状況把握のためのログ保管,
ru: Хранение журнала для статуса использования API
InfoType object
The objects represent the information's type and required security level. You SHOULD define the information types and classify the information received, stored, treated at the cloud resources.
Fixed Fields
Field Name
Type
Description
title
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
The name of the information type.
description
Map[ string, string ]
REQUIRED.
The key MUST be 2 letter language code of ISO
639-1.
And the value MUST be string of UTF-8.
Describing classification detail.
confidential
boolean
REQUIRED. Confidential information or not.
privacy
boolean
REQUIRED. Privacy information or not. It means the information is needed to be protected as legally.
definedBy
string
REQUIRED. The author of this definition.
definedAt
integer
REQUIRED. The time when it was defined at. It MUST be the UNIXTIME format.
JSON Example
{
"title": {
"en": "privacy level",
"ja": "個人情報取り扱いレベル",
"ru": "Чувствительный уровень"
},
"description": {
"en": "Contains privacy information.",
"ja": "個人情報を含む",
"ru": "Содержит конфиденциальную личную информацию."
},
"confidential": true,
"privacy": true,
"definedBy": "ABC company",
"definedAt": 1530370800
}YAML Example
title:
en: confidential level
ja: 個人情報取り扱いレベル
ru: Чувствительный уровень
description:
en: Contains privacy information.
ja: 個人情報を含む
ru: Содержит конфиденциальную личную информацию.
confidential: true
privacy: true
definedBy: ABC company
definedAt: 1530370800
Common Schema
Describing the common data structure of Cloud Design. In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
Range values object
An object representing the range values used at fields on CDS.
Fixed Fields
Field Name
Type
Description
max
float
REQUIRED. Max value of the range value.
min
float
REQUIRED. Min value of the range value.
JSON Example
{
"max": 1.0,
"min": 0.01
}
YAML Example
max: 1.0
min: 0.01
Reference object
This is a reference specification object used when referencing JSON/YAML objects in files for CDS or Cloud Automation Tools from various fields of CDS. Reference objects are defined by JSON references and follow the same structure, behavior, and rules. In this specification, reference resolution is done as defined in the JSON Reference Specification, not the JSON Schema Specification.
Fixed Fields
Field Name
Type
Description
$ref
string
REQUIRED. Reference strings.
In the case of referencing the object in the same file, you MUST start with #/,
and MUST always describe the path from the root object.
When specifying a reference to the external file, you MUST start with the file name with the extension
.json,
.yaml or .yml. After that, you MUST describe the same as in the same file
reference.
JSON Example
{
"$ref": "#/components/actors/custormers"
}JSON Relative Documents With Embedded Schema Example
{
"$ref": "externalfile.yaml#/components/actors/custormers"
}YAML Example
$ref: #/components/actors/custormers
YAML Relative Documents With Embedded Schema Example
$ref: externalfile.yaml#/components/actors/custormers
Appendix
Resources
The Cloud Design Specification has born as a part of
the Reindeer Project.
The Reindeer Project hopes to bring creating power for all by supporting the use of the cloud.
A society where everyone can create services on their own
will not only bring freedom of expression and diversity of lifestyles and values.
We believe it also promotes the redistribution of wealth to all
and improves the average wealth and well-being of people around the world.
Whitepaper
Describing the purpose and plan of the Reindeer project.
Six states of the Cloud
Design
Describing the plan of future tools and ecosystem.
Trademarks
*Google and Google Cloud Platform (GCP) is a registered trademark or trademarks of Google LLC.
*Micosoft and Microsoft Azure are registered trademarks or trademarks of Microsoft Corporation in the United States and other countries.
*Terraform is a registered trademark of HashiCorp, Inc.
*All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.
Revision
Version
Released
Notes
1.0.0
2019-07-31
Initial public release of the Cloud Design Specification.
1.0.0 (CDS itself is the same as previous)
2019-08-15
Add link to Reindeer Editor.
1.1.0
2020-03-18
Enhance the expression of stakeholders in the design (add organization and identity signature)
Add 'organizations' property to the info object.
Add 'sign' property to the author object.
1.2.0
2020-10-08
Add support for 'Serverless Framework.'
1.3.0
2020-11-10
Add 'maxPerformanceDurationRatio' to Context for supporting synthetic cost representation.
1.3.1
2020-11-10
Fix a bug for the type definition of 'maxPerformanceDurationRatio.'
1.3.1 (No change)
2020-11-12
Add an additional description to the 'busyhours' param on this document.
1.3.1(No change)
2021-01-14
Improved some descriptive expressions on this document.
1.3.2
2021-01-15
Change max letter size of title and description to 150.
1.3.2(No change)
2021-03-01
Improved some descriptive expressions on this document.
1.3.2(No change)
2021-06-11
Added trademark descriptions.
1.3.2(No change)
2023-04-17
Added json sample of root schema.