ADL — アーキテクチャ記述言語

はじめに

人とAIがシステムへの認識を共有し、同じ目標にむかえる世界を。

ADLはシステムのユースケースを的確に表現することで、その目的や業務理解をAIに注入します。またADLは汎用JSONフォーマットで様々なツールと連携し、人によるAI理解の把握とその正しい導きを実現します。

この文書は、 The Apache License, Version 2.0 のもとで公開されます。

本書の各キーワード「せねばならない」、「してはならない」、「必要」、「する／することになる」、「することはない」、「すべき」、「すべきでない」、「推奨される」、「してもよい／構わない／可能性がある」、「オプション」は、RFC 2119に準じて解釈されるものとします。

紹介

ADL（アーキテクチャ記述言語）は、ユースケースを起点にシステムの構成情報を記述し、人とAIが相互にシステムの構成情報を理解するための、オープンなアーキテクチャ記述言語です。Reindeer Technology PTE.Ltd. が2019年に公開したCDS（CloudDesignSpecification）をオリジナルとし、2026年に名称をADLに変更、現在にいたります。

ツール

ADLはオープンでツール非依存の汎用フォーマットです。ADLのJSONスキーマに対応したツールであれば、簡易なテキストエディタから専用の設計環境まで、どのようなツールでも作成・保管・検索・検証・再利用することができます。本仕様は特定の製品やベンダーに依存せず、またそれらを必要としません。

ADL Schema 日本語
JSON Schemaに対応した任意のエディタや検証パイプラインに組み込むことで、ADLドキュメントの文法を検証できるJSONスキーマファイルです。

概要

ADLドキュメントの概要を記載します。

バージョン

ADLはSemantic Versioning 2.0.0 (SemVer)を利用してバージョン管理され、以下の仕様に従います。
バージョンナンバーはメジャー番号.マイナー番号.パッチ番号の形でインクリメンタルに増加します。 メジャー番号.マイナー番号は１つ以上の機能セットを指定することになります。そして.パッチ番号は後方互換性のあるバグ修正を指定することになります。よって、パッチバージョンはツールの利用において考慮されるべきではありません。例えば1.0.0と1.0.1の間で、機能またはツールの区別はすべきではありません。

形式

ADLドキュメントはJSONドキュメントです。妥当なJSONオブジェクトでなければなりません。

仕様内のすべてのフィールド名は、大文字と小文字が区別されます。これには、 map型のキーとして仕様されるすべてのフィールドが含まれます。ただし、キーが大文字と小文字を区別しないと明示されている場合を除きます。

構造

ADLドキュメントは単一のルート文書である必要があります。ルートファイルは 'adl.json' という命名にすべきです。
参照 ($ref) は次の 2 種類があります:

ADL内部参照 — 同一 ADL ドキュメント内のディレクティブを指す。#/ で始まり ADL root からのパスを記述 (例 #/actors/customer、#/components/infoTypes/pii、#/useCases/web/trigger)
provisioning リソース参照 — ADL の resources[] に列挙された provisioning ファイル内のリソースを指す。形式は <file>#/<section>/<RealKey>。<file> は resources[] に宣言したファイル名 (拡張子付き)、<section> は固定の小文字セクション識別子 (resources = CFn / Terraform / GDM / CIM / ARM / ROS、functions = Serverless Framework Lambda)、<RealKey> は provisioning ファイル内の実キー (大小文字区別あり)

注: ADL ドキュメントを複数の外部ファイルに分割する「ADLスニペット」機構は 2026-05 に廃止されました。ADL 間のクロスファイル参照はサポートされません。プロジェクト横断の参照は将来的に project_id ベースの新仕様で提供予定です。provisioning リソース参照 (<file>#/<section>/<RealKey>) は ADL 間参照ではなく、ADL ドキュメントと自身が宣言する provisioning ファイル内エントリの紐付けなので引き続き有効です。

ADL Object

これはADLドキュメントのルートオブジェクトです。

固定フィールド

フィールド名

種類

説明

reindeer

string

必須. この文字列はADL自体のsemantic version numberでなければなりません。 reindeerフィールドは、ADLドキュメントを解釈するためのツールに使用されるべきです。これはinfo.versionフィールドとは関係ありません。
本仕様のバージョン（最新は2.0.x）をご指定ください。

self

string

必須. この文字列はADLドキュメントのファイル名です。拡張子は.jsonでなければなりません。 selfフィールドは、ADLドキュメントを解釈するためのツールに使用されるべきです。「adl.json」をご指定ください。

info

Info object

必須. クラウドの活用に関するメタデータを提供します。メタデータは、必要に応じてツールによって使用される場合があります。

actors

Map[ string, Actor object ]

必須. アクターオブジェクトの配列です。クラウドに接続する／される外部ユーザーまたはシステムに関する情報を提供します。

resources

Map[ string, Resource object ]

必須. クラウドの構造を記述する外部ドキュメント（プロビジョニングコードが記載されたファイル）への参照を示す、リソースオブジェクトの配列です。

useCases

Map[ string, ユースケースオブジェクト ]

必須. ユースケースオブジェクトの配列です。アクターとクラウドリソースの間で、特定の目的を達成するための関連性についての情報を提供します。

components

Components object

ADLドキュメントのさまざまな側面に対応する一連の再利用可能なオブジェクトを保持します。コンポーネントオブジェクト内で定義されたすべてのオブジェクトは、それらがコンポーネントオブジェクトの外部のプロパティから明示的に参照されない限り、クラウドの設計には影響しません。

JSON example

{
  "reindeer": "2.0.0",
  "self": "adl.json"
  "info": {
    "title": {
      "en": "Sample system",
      "ja": "サンプルシステム",
    },
    以下Infoスキーマ参照
  },
  "actors": {
      "customer": {
        "title": {
          "en": "Customers",
          "ja": "顧客",
        },
        以下Actorスキーマ参照
      }
  },
  "resources": [
      {
        "$ref":"awsTemplate.json",
        以下Resourcesスキーマ参照
      }
  ],
  "useCases": {
    "customerWebAccess": {
      "title": {
        "en": "Web access by customer",
        "ja": "顧客によるウェブアクセス",
      },
      以下UseCasesスキーマ参照
    }
  },
  "components": {
    "infoType": {
      "pii": {
        以下Information typeスキーマ参照
      }
    },
    以下Componentsスキーマ参照
    （Componentsは定義の再利用に便利なオプションスキーマです）
}

Info object

このオブジェクトはADLドキュメントに関するメタデータを提供します。他の人がADLドキュメントを簡単に検索、発見できるよう、メタデータは適切に記入されるべきです。

固定フィールド

フィールド名

種類

説明

version

string

必須. あなたの設計のバージョンです。（the ADL versionとは異なります）

license

License object

必須. ADLドキュメントのライセンス情報です。

title

Map[ string, string ]

必須. このクラウドの設計を適用するサービスの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

必須. このクラウドの設計を適用するサービスの説明です。それはシステムの目的と機能のすべてのキーワードを含む簡潔なメモであるべきです。このテキストは外部ツールによる検索インデックスとして使われる可能性があります。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

status

string

必須. ADLドキュメントの状態です。以下の値が利用できます。
draft: ドラフト
prepared: 準備済
designed: 設計済
reviewed: レビュー済

designedAt

integer

必須. ADLが作成された日時です。UNIXタイムスタンプ形式を利用する必要があります。

authors

Map[ string, string, Author object ]

必須. ADLドキュメントの作成者です。この情報は外部ツールによって利用される可能性があり、関係者のスキルや経験を証明する重要な情報となります。

organizations

Map[ string, string, Organization object ]

ADL作成に関与する組織です。この情報は外部ツールによって利用される可能性があり、組織のスキルや経験を証明する重要な情報となります。

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,
            "sign": xxxxxx123
      },
      "sampleHandleNameB": {
            "roles": ["designer", "auditor"],
            "joinedAt": 1548730447
      }
    },
    "organizations": {
      "sampleCompanyA": {
            "joinedAt": 1548730447,
            "leavedAt": 1548731447
      },
      "sampleCompanyB": {
            "joinedAt": 1548730447,
            "sign": xxxxxx123
      }
    }
}

Actor objects

クラウドにアクセスするユーザーや運用者、外部システムに関する情報を提供するオブジェクトです。 ADLドキュメントを正しく設計、監査するため、包括的に表現されるべきです。

マーケットタイプのアクターオブジェクト

このオブジェクトは特定のマーケットに属する消費者、観客など、不特定多数の利用者に関する情報を提供します。システム提供対象となるユーザ数やリクエスト数を把握するため、正しい数値を提供すべきです。

固定フィールド

フィールド名

種別

説明

type

string

必須. 固定値： 'market'.

title

Map[ string, string ]

必須. アクターの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

必須. アクターの説明です。このテキストは外部ツールによる検索インデックスとして使われる可能性があります。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

market

Market object

必須. アクターが属する市場に関する情報です。

marketShare

float

必須. 市場シェアを示します。例えば 0.3 は 30% を意味します。

sourceIdentification

[ boolean ]

必須. 特定のIPアドレス範囲やドメイン名などで識別できるかどうかを意味します。 trueの場合、identificationGroup フィールドは必須です。

identificationGroup

string

IPアドレス範囲やドメイン名など。 sourceIdentification フィールドがtrueの場合は必須です。そして、sourceIdentification が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
}

個人タイプのアクターオブジェクト

このオブジェクトは、運用担当者のような1人または複数の人物で構成されているアクターの種類に関する情報を提供します。識別可能な個人とクラウドとの制限されたネットワーク接続を設計する際などに、使用べき種類のアクターです。

固定フィールド

フィールド名

種類

説明

type

string

必須. 固定値： 'persons'.

title

Map[ string, string ]

必須. アクターの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

num

integer

必須. 本アクターを構成する人数です。

sourceIdentification

[ boolean ]

必須. 特定のIPアドレス範囲やドメイン名などで識別できるかどうかを意味します。 trueの場合、identificationGroup フィールドは必須です。

identificationGroup

string

JSON example

{
  "type": "persons",
  "title": {
      "en": "Operators",
      "ja": "運用担当者",
      "ru": "операторы"
  },
  "description": {
      "en": "Operators using management console.",
      "ja": "管理コンソールを利用する運用担当者",
      "ru": "Операторы, использующие консоль управления."
  },
  "num": 7,
  "sourceIdentification": true,
  "identificationGroup": "IPsOfOperatorGroupA"
}

外部システムタイプのアクターオブジェクト

このオブジェクトは外部システムのAPIやファイルインターフェイスなど、1つまたはいくつかのシステムで構成される種類のアクターに関する情報を提供します。識別可能な外部システムとクラウドとの制限されたネットワーク接続を設計する際などに、使用べき種類のアクターです。

固定フィールド

フィールド名

種類

説明

type

string

必須. 固定値： 'externalSystem'.

title

Map[ string, string ]

必須. アクターの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

sourceIdentification

[ boolean ]

必須. 特定のIPアドレス範囲やドメイン名などで識別できるかどうかを意味します。 trueの場合、identificationGroup フィールドは必須です。

identificationGroup

string

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

Resource object

このオブジェクトは、利用するクラウドリソースに関する情報を提供します。 JSONでフォーマットされた外部ファイルに対する参照でなければなりません。そして、以下のようなクラウド自動化ツールのために、整形されたデータであるべきです。

AWS CloudFormation

Azure Resource Manager

Google Cloud Deployment Manager

Alibaba Cloud Resource Orchestration Service

Terraform

Serverless Framework

固定フィールド

フィールド名

種類

説明

type

string

必須. プロビジョニングコードの種別です。以下値の中の１つである必要があります。
acf : AWS CloudFormation.
arm : Azure Resource Manager.
gdm : Google Cloud Deployment Manager.
cim : Google Cloud Infrastructure Manager.
aro : Alibaba Cloud Resource Orchestration Service.
tfm : Terraform.
slf : Serverless Framework.
oth : その他

$ref

string

必須. プロビジョニングコードで記述されたファイルへの参照で、Reference objectの$refアイテムと同じです。 .jsonの拡張子を持つ外部ファイルを参照しなければなりません。そしてその拡張子は、外部ツールによってリンク先のファイルフォーマットを検出するために利用されるべきものです。

JSON Example

{
  "type": "acf",
  "$ref": "xxx.json"
}

ユースケースオブジェクト

このオブジェクトは、特定の機能を実行する目的でいくつかのアクターとリソースを関連付けることにより、システムの利用ケースに関する情報を提供します。それはADLドキュメントを正しく設計、監査するために、包括的に記述されるべきです。

固定フィールド

フィールド名

種類

説明

title

Map[ string, string ]

必須. ユースケースの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

必須. ユースケースの説明です。このテキストは外部ツールによる検索インデックスとして使われる可能性があります。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

trigger

Trigger objects

必須. トリガーオブジェクトを指定します。トリガーはこのユースケースの開始イベントを意味します。

traffics

Map[ string, Traffic objects ]

必須. トラフィックオブジェクトを格納します。各トラフィックはトラフィックオブジェクトを指定します。トラフィックはユースケース内の通信経路を意味します。

maxPerformanceDurationRatio

float

最大性能の月間持続時間比率を示します。ユースケースに求められるコストを計算する際、本値を利用してtriggerやtrafficsに含まれる各Range values objectのmaxとmin値を合成します。例えば月間3日だけ広告効果でDAUを向上させる設計の場合、DAU値をmin:0.01, max:0.1、本値を0.1と表現します。 CloudDesignは月間使用量を基準に性能とコストを表現しますが、本値により月間平均は1rpsながらも瞬間最大性能100rpsを期待する設計が記録できます。

JSON Example

{
  "title": {
        "en": "Customers view",
        "ja": "カスタマー閲覧",
        "ru": "Просмотр клиента"
  },
  "description": {
        "en": "Custormer's web site view of static contents through internet.",
        "ja": "インターネット経由の静的コンテンツ閲覧",
        "ru": "Просмотр статического содержимого через Интернет"
  },
  "trigger": {
        "type": "webAccess",
        "...": "..."
  },
  "traffics": {
        "traffic1": { "type": "passThroughRatio", "...": "..." },
        "traffic2": { "type": "passThroughRatio", "...": "..." }
  },
  "maxPerformanceDurationRatio": 0.1
}

Components object

componentsオブジェクトは情報種別（Information type）の再利用可能な定義を保持します。

固定フィールド

フィールド名

種類

説明

infoType

Map [ string, Information type object]

再利用可能なInformation type objectを保持します。

子スキーマ

ADLドキュメントの主要なデータ構造の子を説明します。以下の説明では、フィールドが明示的に「必須」と定義されない、または「しなければならない」または「する／することになる」と記載されていない場合、オプションと見なすことができます。

License object

ADLドキュメントのライセンス情報です。

固定フィールド

フィールド名

種類

説明

type

string

必須. ADLのライセンス種別です。以下何れかの値である必要があります。(CC0推奨)
CC0
Apache-2.0
MIT
BSD-2-Clause
OtherOpen
Closed

provider

string

ライセンスの提供者、またはその名称です。typeがOtherOpenまたはClosedの場合以外は記載してはいけません。

JSON Examples

RECOMMENDED
{
  "type": "CC0"
}

{
  "type": "Closed",
  "provider": "Reindeer technology PTE.LTD."
}

Author object

このオブジェクトは、ADLドキュメントの作者とその役割についての情報を提供します。対象のシステム、クラウド技術、そして同システムのサービス提供市場について正しい知識を持っている人を他の人が見つけるのを助けるため、包括的に記載されるべきです。

固定フィールド

フィールド名

種類

説明

roles

[ string ]

必須. ADLドキュメントに関与した役割を保持します。役割は、以下の何れかの値でなければなりません。
planner: 企画者
designer: 設計者
auditor: ADLドキュメントの監査者
operator: ADLで設計されたシステムの運用者
others: その他

joinedAt

integer

必須. 作者が本ADLドキュメントに関与しはじめた日時です。UNIXTIME形式で記載されねばなりません。

leavedAt

integer

必須. 作者が本ADLドキュメントの作成、運用から離任した日時です。UNIXTIME形式で記載されねばなりません。

sign

string

作者の署名です。本値は署名支援ツールによって自動生成されるべきもので、通常は空白です。

JSON Example

{
  "roles": ["designer","auditor"],
  "joinedAt": 1548730447,
  "leavedAt": 1548731447,
  "sign": ABC123DEF456HIJ789#abc
}

Organization object

このオブジェクトは、ADLドキュメントの関連組織とその役割についての情報を提供します。対象のシステム、クラウド技術、そして同システムのサービス提供市場について正しい知識を持っている組織を他の人が見つけるのを助けるため、包括的に記載されるべきです。

固定フィールド

フィールド名

種類

説明

joinedAt

integer

必須. 組織が本ADLドキュメントに関与しはじめた日時です。UNIXTIME形式で記載されねばなりません。

leavedAt

integer

必須. 組織が本ADLドキュメントの作成、運用から離任した日時です。UNIXTIME形式で記載されねばなりません。

sign

string

組織の署名です。本値は署名支援ツールによって自動生成されるべきもので、通常は空白です。

JSON Example

{
"joinedAt": 1548730447,
"leavedAt": 1548731447,
"sign": ABC123DEF456HIJ789#abc
}

Market object

マーケットに関する情報を提供します。あなた自身、または第三者の調査結果を内包する可能性があります。

固定フィールド

フィールド名

種類

説明

title

Map[ string, string ]

必須. マーケットの名称です。会員の特性、興味、推定年などを説明する言葉を含めることにより、このADLドキュメント上でユニークであるべきです。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

必須. マーケットの説明です。それは詳細な算定者や算定目的などを説明する言葉を含むべきです。この説明は、設計者がこの情報を他のデザインで再利用できるかどうかを判断するのに役立ちます。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

num

integer

必須. 構成メンバーの数です。

estimatedBy

string

必須. 算定者の名称です。

estimatedAt

integer

必須. 算定された日時です。UNIXTIME形式で記載されねばなりません。

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
}

Trigger objects

ユースケースの初期イベントに関する情報を提供します。それはサーバへの人的なWebアクセス、または外部APIへの自動化された時限呼び出しである可能性があります。

Webアクセスタイプのトリガーオブジェクト

これはアクターによるトリガーの一種です。アクターによるクラウドリソースへのWebアクセスを表現します。アクターは人間または外部システムの可能性があります。

固定フィールド

フィールド名

種類

説明

type

string

必須. 固定値： 'webAccess'.

description

Map[ string, string ]

必須. トリガーの説明です。トリガーの目的を端的に示すメモであるべきです。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

infoType

Reference object (#/components/infoTypes/<key>)

必須. InfoType objectに対する参照です。このトリガーが扱う情報の種別を定義します。

ports

[ integer ]

必須. このトリガーのエンドポイント（endフィールドで定義）が利用するポート番号です。

internet

[ boolean ]

必須. この接続がインターネット経由か否かを示します。

restriction

[ boolean ]

必須. このトリガーのエンドポイントにおける、接続元IP、ドメインなどの接続制限の有無を示します。

dau

Range values object

必須. 日間アクティブユーザー率（Dayly Active User)です。例えば１日平均で、このstartフィールドで参照されたアクターの1%がこのendフィールドで参照されるリソースにアクセスする場合、それは0.01となります。

pagesVisit

Range values object

必須. 訪問あたりの平均ページ数です。訪問者が訪問毎にどのくらいのページにアクセスするかを示します。

kbPage

Range values object

必須. 平均ページサイズです。（KB単位）

reqPage

Range values object

必須. ページあたりのリクエスト数です。ページあたりにどのくらいのリクエスト数（ページを構成する画像やHTMLなどへのリクエスト）が発生するかを示します。

busyHours

Range values object

必須. １日あたりのアクセス集中時間です。例えば日々のアクセスがほぼ AM 9:00 - AM 11:00 と PM 17:00 - PM 19:00 に集中している場合、この値は 6 です。 一般的に8時間より1時間のほうが「集中度は高い」とみなされるため、min値よりmax値のほうが値が「小さくなる」ことにご注意ください。> 例：利用者が日中8時間以内に均等にアクセスするケースを最小性能、昼休みの1時間にアクセスが集中するケースを最大性能とする場合、min:8, max:1 と表現します。

postsVisit

Range values object

必須. 投稿する訪問者の割合を示します。例えば1日あたり、100,000人のアクターがDAU1%の割合で訪問する中で100件の投稿がある場合、この値は0.1となります。

kbPost

Range values object

必須. 平均投稿データサイズです。（KB単位）

start

Reference object

必須. actor objectsへの参照です。このトリガーの開始点を意味します。

end

[ Reference object (<file>#/<section>/<RealKey>) ]

必須. resource objectに記載されたリソースへの参照でなければなりません。このトリガーのエンドポイントを示します。プロビジョニングファイル参照（<file>#/<section>/<RealKey>）のみ有効です。複数のリソースが指定された場合、startからの通信量は各リソースに均等に分割されるものと判断されます。リソースごとに通信量の比重が異なる場合、また用途や接続ポートなどが異なるリソースへの接続が必要な場合はここに列記すべきではありません。新しいユースケースのendとして記述してください。 ⚠️ ADL内部参照（#/ で始まる形式）はスキーマで弾かれます。必ず <file>#/<section>/<RealKey> 形式で実リソースを参照してください。 例：10GBのリクエストを送信するアクターに対して2台のWebサーバを列記した場合、各サーバが受信するリクエストは5GBとなります。静的コンテンツ用サーバと動的コンテンツ用サーバに9:1の割合でアクセスする設計の場合は両サーバを一つのendに併記せず、静的コンテンツを提供するユースケースと動的コンテンツを提供するユースケースを分けて、それぞれのendに各サーバを記述してください。

endpointTitle

Map[ string, string ]

必須. エンドポイントの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

storedRatio

Range values object

必須. endが受信したデータのうち、endで保管するデータサイズの比率を示します。例えば、このトリガーでアクターがendに送信するデータの全てをend上で保管する場合、この値は1.0になります。データを保管しない場合は0です。

storedInfoType

Reference object (#/components/infoTypes/<key>)

InfoType objectへの参照です。このトリガーのendが保管するデータの種類を示します。

storageDescription

Map[ string, string ]

ストレージの説明です。このテキストは外部ツールによる検索インデックスとして使われる可能性があり、ストレージの目的を的確に表現すべきです。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

JSON Example

{
  "type": "webAccess",
  "description": {
    "en": "API call for movie data acquisition.",
    "ja": "動画データ取得のためのAPI呼び出し。",
    "ru": "API вызов для сбора данных фильма"
  },
  "infoType": {
        "$ref": "#/components/infoTypes/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": "awsCloudEnvironment.json#/resources/cloudFront"}
  ],
  "endpointTitle": {
    "en": "LoadBalancer",
    "ja": "ロードバランサ",
    "ru": "Балансировщик нагрузки"
  },
  "storedRatio": {"max": 0.3, "min": 0.1},
  "storedInfoType": {
    "$ref": "#/components/infoTypes/general"
  },
  "storageDescription": {
    "en": "Logging for API usage tracing.",
    "ja": "API利用状況把握のためのログ保管",
    "ru": "Хранение журнала для статуса использования API"
  }
}

時限アクションタイプのトリガーオブジェクト

これはアクターまたはコンピューティングリソースによって発動されるタイプのトリガーです。アクターまたはcloud computingリソースからの時限アクションを表現します。

固定フィールド

フィールド名

種類

説明

type

string

必須. 固定値： 'timedAction'.

description

Map[ string, string ]

infoType

Reference object (#/components/infoTypes/<key>)

必須. InfoType objectへの参照です。トリガーが扱う情報の種類を明示します。

ports

[ integer ]

必須. トリガーのエンドポイントが利用するポート番号です。

internet

[ boolean ]

必須. トリガーがインターネット経由の通信を行うかどうかを明示します。

restriction

[ boolean ]

必須. トリガーのエンドポイントが接続元IP、ドメイン、その他の接続制限をかけているかどうかを明示します。

onlineRps

Range values object

必須. このトリガーが発火した時の、1秒当たりの要求数。開始点（startフィールド）からエンドポイント（endフィールド）に対するリクエストの要求性能を明示します。たとえば、毎週月曜日の朝にバッチシステムが動作し、各バッチが1秒間に2回のスループットで外部APIにアクセスする場合は2.0です。

reqMonth

Range values object

必須. 開始点からエンドポイントへの月間リクエスト数です。たとえば、バッチシステムが毎月1000人に3回メールマガジンを送信する場合、この値は9000になります。

kbRequest

Range values object

必須. 開始点からエンドポイントに対するリクエストあたりのデータサイズをKB単位で明示します。

kbResponse

Range values object

必須. 開始点からエンドポイントへのリクエスト毎に生じるレスポンスのデータサイズをKB単位で明示します。

start

Reference object

必須. トリガーの開始点を示します。actor object または resource objectへの参照でなければなりません。

end

[ Reference object (<file>#/<section>/<RealKey> または #/actors/<key>) ]

必須. トリガーのエンドポイントを示します。プロビジョニングファイル参照（<file>#/<section>/<RealKey>）または ADL 内部アクター参照（#/actors/<key>）のみ有効です。複数のリソースが指定された場合、startからの通信量は各リソースに均等に分割されるものと判断されます。リソースごとに通信量の比重が異なる場合、また用途や接続ポートなどが異なるリソースへの接続が必要な場合はここに列記すべきではありません。新しいユースケースのendとして記述してください。 ⚠️ ADL内部参照のうち、アクター（#/actors/<key>）以外（traffics・useCases等）はスキーマで弾かれます。

endpointTitle

Map[ string, string ]

必須. エンドポイントの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

storedRatio

Range values object

必須. endが受信したデータのうち、endに保管されるデータサイズの比率を示します。例えば、このトリガーでアクターがendに送信するデータの全てをend上で保管する場合、この値は1.0になります。データを保管しない場合は0です。

storedInfoType

Reference object (#/components/infoTypes/<key>)

InfoType objectへの参照です。このトリガーのendが保管するデータの種類を示します。

storageDescription

Map[ string, string ]

JSON Example

{
  "type": "timedAction",
  "description": {
    "en": "API call for movie data acquisition.",
    "ja": "動画データ取得のためのAPI呼び出し。",
    "ru": "API вызов для сбора данных фильма"
  },
  "infoType": {
        "$ref": "#/components/infoTypes/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": "awsCloudEnvironment.json#/resources/jobServer"
  },
  "end": [
        {"$ref": "##/actors/api"}
  ],  
  "endpointTitle": {
    "en": "LoadBalancer",
    "ja": "ロードバランサ",
    "ru": "Балансировщик нагрузки"
  },
  "storedRatio": {"max": 0.3, "min": 0.1},
  "storedInfoType": {
    "$ref": "#/components/infoTypes/general"
  },
  "storageDescription": {
    "en": "Logging for API usage tracing.",
    "ja": "API利用状況把握のためのログ保管",
    "ru": "Хранение журнала для статуса использования API"
  }

}

Traffic objects

ユースケース内の通信に関する情報を提供します。これはトリガーイベントの後続処理で利用されなければなりません。例えばWebサーバーからアプリケーションサーバへの動的コンテンツ要求や、アプリケーションサーバからデータベースへのデータ保存などが表現されます。

パススルー比率タイプのトラフィックオブジェクト

これはトラフィックオブジェクトの一種です。開始点が受信したリクエストの一部を後続のリソースに受け渡すという形で発生する通信を表現できます。例えばロードバランサが受けたリクエストをWebサーバに送信する、アプリケーションが受けたリクエストにもとづいてメール配信キューを生成するといった通信の連鎖が表現できます。その際、本トラフィックのエンドポイント(endフィールド)が受信するデータサイズは、本トラフィックの前段の通信（sourceフィールド）が受信したリクエストの何パーセントにあたるかといった表現方法になります。したがって、前段の通信が1MBのPOST値を受け取った後にサーバ内で3MBにデータを拡張して本トラフィックのエンドポイントに受け渡すといった場合には、データサイズは300%になる（passThroughReqRatio>フィールドが3）と表現できます。

異種リソースのチェーン: CloudFront → API Gateway → Lambda のような異なる種別のリソースを直列に繋ぐ場合は、1ステップにつき1つのtrafficオブジェクトを作成し、各trafficのsourceフィールドに前段のtrafficへの参照を指定します。異なる種別のリソースを1つのtrafficのend配列にまとめて列記することは仕様違反です。 end配列はオートスケールグループのEC2インスタンス群など、同一種別のリソースを並列に並べる場合専用です。

正しいチェーンの記述例（CloudFront → API Gateway → Lambda）:

traffics:
  t1:
    type: passThroughRatio
    source:
      $ref: "#/useCases/myUseCase/trigger"
    end:
      - $ref: "#/resources/myCloudFront"
  t2:
    type: passThroughRatio
    source:
      $ref: "#/useCases/myUseCase/traffics/t1"
    end:
      - $ref: "#/resources/myApiGateway"
  t3:
    type: passThroughRatio
    source:
      $ref: "#/useCases/myUseCase/traffics/t2"
    end:
      - $ref: "#/resources/myLambda"

固定フィールド

フィールド名

種類

説明

type

string

必須. 固定値： 'passThroughRatio'.

description

Map[ string, string ]

必須. トラフィックの説明です。このテキストは外部ツールによる検索インデックスとして使われる可能性があります。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

infoType

Reference object (#/components/infoTypes/<key>)

必須. InfoType objectへの参照です。トラフィックが扱う情報の種類を明示します。

ports

[ integer ]

必須. トラフィックのエンドポイントが利用するポート番号です。

internet

[ boolean ]

必須. トラフィックがインターネット経由の通信を行うかどうかを明示します。

restriction

[ boolean ]

必須. トラフィックのエンドポイントが接続元IP、ドメイン、その他の接続制限をかけているかどうかを明示します。

source

Reference object (#/useCases/<uc>/trigger または #/useCases/<uc>/traffics/<key>)

必須. trigger object または traffic objectへの参照です。このトラフィックの開始点を意味します。これは、endフィールドに記述されているすべてのリソースまたはアクターオブジェクトに影響を及ぼします。 異なる種別のリソースを直列に繋ぐ場合（例：CloudFront → API Gateway → Lambda）は、このフィールドに前段のtrafficオブジェクトへの参照を指定します。 これが異種リソースの直列接続における規定の記述方法です。

end

[ Reference object (<file>#/<section>/<RealKey> または #/actors/<key>) ]

必須. このトラフィックのエンドポイントを意味します。プロビジョニングファイル参照（<file>#/<section>/<RealKey>）または ADL 内部アクター参照（#/actors/<key>）のみ有効です。複数のリソースが指定された場合、startからの通信量は各リソースに均等に分割されるものと判断されます。これはオートスケールグループのEC2インスタンス群などの同種リソース群のほか、 DBインスタンスとそのパラメータグループのように一体としてプロビジョニングする必要がある密結合リソース群にも適用されます。ただし、列記したリソース同士がチェーン関係にある場合（CloudFront → API Gateway → Lambda のようにトラフィックが順次流れる場合）は、このフィールドにまとめてはなりません（MUST NOT）。各ホップを別々のtrafficオブジェクトとして作成し、sourceフィールドで連結して表現してください。チェーン関係にあるリソースをendにまとめると、直列フローと並列分散が混同され、トラフィック計算が不正確になります。

endpointTitle

Map[ string, string ]

必須. エンドポイントの名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

passThroughReqRatio

Range values object

必須. 前段のトリガーやトラフィック（sourceフィールド）が受信したリクエストのうち、何パーセントが後続となる本トラフィックのエンドポイント（end）に流入するかを示します。例えば前段のトリガーがユーザーから100,000/月のリクエストを受信し、50%を自身のキャッシュ、50%を本トラフィックに送信する場合、この値は0.5となります。

compositResRatio

Range values object

必須. 前段のトリガーやトラフィック（sourceフィールド）が扱うレスポンスデータのサイズを基準として、本トラフィックがその何パーセントにあたるサイズのデータを前段のトリガーやトラフィックに返却するかを記述します。例えば前段のトリガーがユーザーに10GB/月のデータを返却する場合、この値が0.5であれば本トラフィックから前段のトリガーに対して5GB/月のデータを返却することになります。

storedRatio

Range values object

必須. endが受信したデータのうち、endで保管するデータサイズの比率を示します。例えば、このトラフィックで送信元がendに送信するデータの全てをend上で保管する場合、この値は1.0になります。データを保管しない場合は0です。

storedInfoType

Reference object (#/components/infoTypes/<key>)

InfoType objectへの参照です。このトラフィックのendが保管するデータの種類を示します。

storageDescription

Map[ string, string ]

JSON Example

{
  "type": "passThroughRatio",
  "description": {
    "en": "Static content distribution",
    "ja": "静的コンテンツの配信",
    "ru": "Распределение статического контента"
  },
  "infoType": {
        "$ref": "#/components/infoTypes/general"
  },
  "ports": [80],
  "internet": false,
  "restriction": false,
  "source": {"$ref": "#/useCases/customerWebAccess/trigger"},
  "end": [
        {"$ref": "awsCloudEnvironment.json#/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/infoTypes/general"
  },
  "storageDescription": {
    "en": "Logging for API usage tracing.",
    "ja": "API利用状況把握のためのログ保管",
    "ru": "Хранение журнала для статуса использования API"
  }
}

InfoType object

情報の種類と必要なセキュリティレベルを表します。本オブジェクトにより、取り扱う情報タイプを定義し、クラウドリソースで受信、保存、処理される情報を分類すべきです。

固定フィールド

フィールド名

種類

説明

title

Map[ string, string ]

必須. 情報種別の名称です。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

description

Map[ string, string ]

必須. 情報種別の説明です。このテキストは外部ツールによる検索インデックスとして使われる可能性があります。キーはISO 639-1の2文字の言語コードでなければなりません。そして値はUTF-8の文字列でなければなりません。

confidential

boolean

必須. 機密情報か否かを定義します。

privacy

boolean

必須. プライバシー情報を含むか否かを定義します。法的に守られるべき情報の存在を意味します。

definedBy

string

必須. 作成者です。

definedAt

integer

必須. 作成日です。UNIXTIME形式で記述されなければなりません。

JSON Example

{
  "title": {
        "en": "privacy level", 
        "ja": "個人情報取り扱いレベル",
        "ru": "Чувствительный уровень"
  },
  "description": {
        "en": "Contains privacy information.",
        "ja": "個人情報を含む",
        "ru": "Содержит конфиденциальную личную информацию."
  },
  "confidential": true,
  "privacy": true,
  "definedBy": "ABC company",
  "definedAt": 1530370800
}

Common Schema

ADLドキュメントの汎用データ構造について説明します。以下の説明では、フィールドが明示的に「必須」と定義されない、または「しなければならない」または「する／することになる」と記載されていない場合、オプションと見なすことができます。

Range values object

ADLの様々なフィールドで利用される、値範囲を示すオブジェクトです。

固定フィールド

フィールド名

種類

説明

max

float

必須. 値範囲の最大値を意味します。

min

float

必須. 値範囲の最小値を意味します。

JSON Example

{
  "max": 1.0,
  "min": 0.01
}

由来メタデータオブジェクト (`_meta`)

ADL ノード（actor、resource、 traffic、trigger）の作成者と確信度を記録する OPTIONAL なオブジェクトです。省略時は AI が確信度 1.0 で作成したとみなされます。ツールにおいて、AI 推論と人間の手修正を区別するために使用されます。

固定フィールド

フィールド名

型

説明

string

OPTIONAL. 作成者を示す識別子。 "ai" は AI 生成、"h:<userId>" は人間が定義したことを示します。省略時は "ai" とみなされます。

integer

OPTIONAL. d で示される作成者によりノードが最後に変更された時刻（epoch 秒）。

float (0-1)

OPTIONAL. AI が生成した値への確信度。 d が "ai" または省略時のみ意味を持ちます。省略時は 1.0 とみなされます。

使用ルール

AI 生成ノードで確信度が高い場合：_meta 全体を省略してバイト数を抑える。
AI 生成で確信度が低い場合：c のみ記述。例 "_meta": { "c": 0.6 }。
人間が編集したノード：必ず _meta を保持または設定し、 "d": "h:<userId>" を含める。人間の編集ノードから _meta を削除しないこと。
AI が人間定義ノードを変更する場合：ユーザから明示的に指示されたときのみ実施。

JSON 例

{
  "_meta": {
    "d": "h:U123",
    "t": 1714400000,
    "c": 0.9
  }
}

Reference object

ADLの様々なフィールドからADLやクラウドオートメーションツール用ファイル内のjsonオブジェクトを参照する際に利用する参照先指定オブジェクトです。参照オブジェクトはJSON参照によって定義されており、同じ構造、動作、および規則に従います。この仕様では、参照の解決はJSONスキーマ仕様ではなく JSON参照仕様で定義されているとおりに行われます。

固定フィールド

フィールド名

種類

説明

$ref

string

必須. 参照文字列。次の 2 形式:

ADL 内部参照: #/ で始まり ADL root からのパス (例 #/actors/customer、#/components/infoTypes/pii)
provisioning リソース参照: <file>#/<section>/<RealKey>。<file> は ADL resources[] で宣言したファイル名 (拡張子付き)、<section> は resources (CFn / Terraform / GDM / CIM / ARM / ROS) または functions (Serverless Framework Lambda)、<RealKey> は provisioning ファイル内の実キー (大小文字区別あり)

ADL 間のクロスファイル参照 (旧「ADLスニペット」形式、例 other.json#/actors/x) はサポートされません。

JSON Example (infoType への参照)

{
  "$ref": "#/components/infoTypes/classA"
}

JSON Example (プロビジョニングリソースへの参照)

{
  "$ref": "awsTemplate.json#/resources/ApplicationLoadBalancer"
}

フィールド別の有効な $ref 形式

ADL 内で $ref を使用できるフィールドと、それぞれで有効な参照形式を以下に示します。記載外の形式（例: $ref を使った actor・useCase・market・trigger・traffic エントリそのもの）はスキーマで弾かれます。

フィールド

有効な $ref 形式

webAccess trigger.start

#/actors/<key> のみ

timedAction trigger.start

#/actors/<key> または <file>#/<section>/<RealKey>

webAccess trigger.end[]

<file>#/<section>/<RealKey> のみ（provisioning リソース参照）

timedAction trigger.end[]
traffic.end[]

<file>#/<section>/<RealKey> または #/actors/<key>

traffic.source

#/useCases/<uc>/trigger または #/useCases/<uc>/traffics/<key>

infoType / storedInfoType

#/components/infoTypes/<key> のみ

付録

参考資料

ADLは Reindeer Projectの一環として生まれました。
Reindeer Projectはクラウド活用の支援を通じて、すべての人々につくる力を届けたいと願っています。
誰もが自分の力でサービスを創造できる社会は、表現の自由と生活様式や価値観の多様性をもたらすだけではありません。それはまた、すべての人々に対する富の再分配を促進し、世界中の人々の平均的な富と幸福を改善すると信じています。

ホワイトペーパー
Reindeer projectの目的と計画が記されています。

商標

・アマゾンウェブサービス、Amazon Web Services、AWS、およびかかる資料で使用されるその他のAWS商標は、Amazon.com, Inc.またはその関連会社の商標です。
・Google、「 Google Cloud Platform (GCP) 」「 Google Cloud Platform (GCP) ロゴ」は、 Google LLCの商標または登録商標です。
・Microsoft、Microsoft Azureは、米国Microsoft Corporationの、米国およびその他の国における登録商標または商標です。
・Terraformは、HashiCorpの登録商標または商標です。
・その他、記載されている会社名および商品・サービス名は各社の登録商標または商標です。

リビジョン

バージョン

リリース日

備考

1.0.0

2019-07-31

Cloud Design Specificationの最初の公式リリース

1.0.0（バージョン変更なし）

2019-08-15

本資料にReindeer Editorへのリンクを追加

1.1.0

2020-03-18

デザインの関係者表現を拡充（組織と本人証明サインを追加）
'info' オブジェクトに 'organizations' プロパティを追加
'author' オブジェクトに 'sign' プロパティを追加

1.2.0

2020-10-08

Serverless Framework をサポート

1.3.0

2020-11-10

UseCaseにmaxPerformanceDurationRatioを追加し、合成コスト表現をサポート

1.3.1

2020-11-10

maxPerformanceDurationRatioの型定義ミスを修正

1.3.1(変更なし)

2020-11-12

本ドキュメントのbusyHoursパラメータに説明を補足

1.3.1(変更なし)

2021-01-14

本ドキュメントのいくつかの説明表現を改善

1.3.2

2021-01-15

titleとdescriptionの最大文字長を150字に変更

1.3.2(変更なし)

2021-03-01

本ドキュメントのいくつかの説明表現を改善

1.3.2(変更なし)

2021-06-11

商標表記を追加

1.3.2(変更なし)

2023-04-17

ルートスキーマのjsonサンプルを追加

1.3.2(廃止）

2026-05-08

プロジェクト横断で外部ファイルを参照するための CDS Snippet 仕様を廃止しました（<file>.ext#/... 形式の $ref はサポート停止）。以降、すべての $ref は #/... 内部参照のみとなります。プロジェクト横断でリソースやアクターを参照する用途は、将来的に project_id ベースのリンク仕様を別途追加予定です（本スキーマには未影響）。

1.3.2(補足)

2026-05-11

2026-05-08 の廃止対象を明確化: 廃止されたのは CDS 間のクロスファイル参照（旧「CDSスニペット」機構）のみ。 provisioning リソース参照（CDS から自身が resources[] で宣言する provisioning ファイル内エントリへのリンク）は引き続き有効で、形式は <file>#/<section>/<RealKey> です。 <section> は小文字固定のセクション識別子 (resources または functions)。ドキュメント、スキーマ、コード例をこの形式に統一しました。

1.4.0

2026-06-16

親スキーマ「Context」を「UseCase」に変更。

2.0.0（リブランディング）

2026-06-16

（リブランディング）Cloud Design Specification（CDS）を ADL（アーキテクチャ記述言語）に改称。

はじめに

紹介

ツール

概要

バージョン

形式

構造

ADL Object

固定フィールド

JSON example

Info object

固定フィールド

JSON example

Actor objects

マーケットタイプのアクターオブジェクト

固定フィールド

JSON Example

個人タイプのアクターオブジェクト

固定フィールド

JSON example

外部システムタイプのアクターオブジェクト

固定フィールド

JSON Example

Resource object

固定フィールド

JSON Example

ユースケースオブジェクト

固定フィールド

JSON Example

Components object

固定フィールド

子スキーマ

License object

固定フィールド

JSON Examples

Author object

固定フィールド

JSON Example

Organization object

固定フィールド

JSON Example

Market object

固定フィールド

JSON Example

Trigger objects

Webアクセスタイプのトリガーオブジェクト

固定フィールド

JSON Example

時限アクションタイプのトリガーオブジェクト

固定フィールド

JSON Example

Traffic objects

パススルー比率タイプのトラフィックオブジェクト

固定フィールド

JSON Example

InfoType object

固定フィールド

JSON Example

Common Schema

Range values object

固定フィールド

JSON Example

由来メタデータオブジェクト (_meta)

固定フィールド

使用ルール

JSON 例

Reference object

固定フィールド

JSON Example (infoType への参照)

JSON Example (プロビジョニングリソースへの参照)

フィールド別の有効な $ref 形式

付録

参考資料

商標

リビジョン

由来メタデータオブジェクト (`_meta`)