動機と原則Motivations and Principles

アダプティブ カード形式の発展を管理するうえでの動機と原則について説明します。Below are the motivations and principles govering the evolution of the Adaptive Card format.

形式を管理する動機Motivations behind the format

2016 年初旬に、Microsoft のいくつかのチーム (Outlook、Windows、Bot Framework を含む) では、すべてのチームが非常によく似たもの ("カード") を必要としており、各チームが別々に独自のソリューションを設計していることに気が付きました。In early 2016, several teams at Microsoft (including Outlook, Windows and the Bot Framework) came to the realization that they all wanted something extremely similar ("cards") and that each of them were designing their own solutions independently:

  • Windows には独自のライブ タイルと通知形式がありましたWindows had its own Live Tiles and Notifications format
  • Bot Framework では、Bot メッセージを送信するときに開発者が選択できる、事前定義済みのカード テンプレートのセットを使用していましたThe Bot framework was using a set of predefined card templates developers could choose from when sending Bot messages
  • Outlook では、アクション可能メッセージ機能用の独自の MessageCard 形式を使用していましたOutlook was using its own MessageCard format for its Actionable Messages feature

同時に、LINE、FaceBook Messenger、Slack などの他のプラットフォームでは、独自の専用 "カード" 形式を定義していました。At the same time, other platforms such as LINE, FaceBook Messenger, Slack and more were defining their own, proprietary "card" format. このため、Microsoft の数名の従業員が集まり、次のような機能を持つ、単一のオープンなカード形式と SDK のセットを定義する取り組みを開始しました。So a few Microsoft employees gathered up and started an effort to define a single, open card format and a set of SDKs that:

  • ホスト間のカードの交換を促進するWould facilitate the interchange of cards between hosts
  • ビジュアルの一貫性を確保するために、カードのスタイル設定に対する制御を各ホストが保持できるようにするWould allow each host to keep control over the styling of cards to ensure visual consistency
  • すぐに使える SDK により、ホスト アプリケーションで最小限の労力によって簡単にカードを表示できるようにするWould make it easy for a host application to display cards with minimum effort via ready-to-use SDKs
  • サードパーティにも価値を提供し、最終的に業界で広く採用されるようにするAnd that would also provide value to third parties and eventually get adopted widely by the industry

アダプティブ カードの管理における原則Principles governing Adaptive Cards

  1. アダプティブ カードは、_単純_で_宣言型の_カード形式であるAdaptive Card is a simple and declarative card format

    1. HTML や XAML に置き換わるものではありませんIt is not meant as an HTML or XAML replacement/alternative
    2. アダプティブ カードに "コードビハインド" を作成しないThere is no "code behind" with Adaptive Cards
      1. カードの作成者は、カスタム/任意のコードをペイロードに埋め込むことはできません。このため、アダプティブ カードのホストは、サードパーティのコードを実行する必要はありませんCard authors cannot embed custom/arbitrary code with their payloads, and as a result an Adaptive Card host never needs to run third party code
      2. ダイナミズムと対話機能は、宣言型マークアップのみによって実現されますDynamism and interactivity are achieved solely via declarative markup
    3. これにより、新しいプラットフォーム向けにアダプティブ カードの SDK を構築するために必要な労力を妥当に抑えますThis ensures that the effort necessary to build an Adaptive Card SDK for a new platform remains reasonable
  2. アダプティブ カードの形式により、特定の基盤となるテクノロジの使用を強いてはならないThe Adaptive Card format can't impose the use of any particular underlying technology

    1. アダプティブ カード形式では、JavaScript、C#、Python、およびその他の言語を使用しませんThe Adaptive Card format does not rely on JavaScript, C#, Python or any other language
    2. 同様に、HTML、XAML、その他のグラフィック/UI フレームワークも使用しませんSimilarly it doesn't rely on HTML or XAML or any other graphic/UI framework
    3. これにより、アダプティブ カードは、レンダラーが存在する限り、どのプラットフォームでもネイティブにレンダーできますThis way, Adaptive Cards can be rendered natively on any platform for as long as a renderer exists
  3. アダプティブ カード形式は、共有プロパティであるThe Adaptive Card format is a shared property

    1. SDK と共に、形式はオープン ソースであり、その発展はコミュニティによって促進されますAlong with its SDKs, the format is to be open source and its evolution community driven
    2. そのため、形式は 1 つのチームが所有するものでも促進するものでもありませんThe format is therefore not owned nor driven by any one team
  4. アダプティブ カードの形式は "Microsoft 専用" として設計しないThe Adaptive Card format is not designed "just for Microsoft's use"

    1. そうではなく、多様なアプリケーションやユースケースにおけるニーズに適合するように設計されますInstead it is designed to suit the needs of a wide variety of applications and use cases
  5. "アダプティブ カード ワーキング グループ" が形式の発展を管理するThe Adaptive Card Working Group governs the evolution of the format

    1. このワーキング グループは、全員が形式の成功に深く関与する、Microsoft の従業員によって構成されますThis working group is comprised of a set of Microsoft employees that are all deeply involved in the success of the format
    2. ワーキング グループは、週次の会議 (現在は月曜日) を実施し、機能の提案の検討、未解決の問題に関する議論とトリアージ、vNext の作業項目の全体的な進捗の追跡を行いますThe Working Group conducts weekly meetings (currently on Monday) during which feature proposals are reviewed, open issues are discussed and triaged and overall progress on vNext work items is tracked
    3. ワーキング グループでは、形式の発展に関する決断において、Microsoft 内部のチームを含む、コミュニティ全体からのフィードバックを活用しますThe Working Group uses feedback from the community at large, including internal Microsoft teams, to decide how the format evolves
      1. GitHub で問題を作成する (下記を参照) ことによって、だれでもワーキング グループに参加できますAnyone can participate in the working group through opening issues in GitHub (see below)
      2. アダプティブ カード フレームワークの実際の使用に基づく問題/機能に関する要望は、(ホストまたはカード作成者のどちらの場合も) 形式の今後の発展に最も大きな影響を及ぼしますIssues/feature requests rooted in actual usage of the Adaptive Cards framework (either as a host or as a card author) have the most impact on the future of the format
    4. ワーキング グループによって承認されるためには、新しい機能の提案では以下を満たす必要がありますTo be approved by the Working Group, proposed new features:
      1. 実際のユース ケースにおいて妥当であるMust be justified by real life use cases
      2. 機能仕様を持つMust have a functional specification
    5. 承認された新機能は、バックログに追加され、vNext で検討されますApproved new feature are added to the backlog and considered for vNext
      1. 新機能の優先順位付けに使用される基準には、その機能によって可能になる幅広いシナリオ、複雑さ、保守容易性などが含まれますThe criteria used to prioritize new features include the breadth of scenarios the feature enables, its complexity/maintainability and more
      2. 不確かな場合は見合わせましょう。When in doubt, keep it out! 適切に設計された機能を後で導入する方が、間違ったまま進むよりはるかに簡単です。It's a lot easier to introduce a well designed feature later than to live with a mistake forever.
    6. すべての新機能は、すべてのサポートされる SDK に実装されますAll new features are implemented in all supported SDKs
    7. すべての新機能は、文書化され、samples フォルダーで公開されるテスト カードと関連付けられますAll new features are documented and associated with a test card published in the samples folder
    8. 形式と SDK の新しいバージョンは、ベータ フェーズを経ますNew versions of the format and SDKs go through a beta phase
    9. アダプティブ カード スキーマと SDK のバージョンのリリース スケジュールは、日付ではなく、品質によって決まりますThe release schedule for Adaptive Card schema and SDK versions is driven by quality, not date
  6. 相互運用性Interoperability

    1. 文書化された形式 (例: ホスト固有の拡張機能を使用しない) に従って作成されたカードは、アダプティブ カード対応のすべてのホストで適切にレンダリングされますCards authored in accordance with the documented format (e.g. not using any host-specific extensions) will render properly in any Adaptive Card-capable host
    2. この原則に対する例外は以下のみです。The only exceptions to this principles are:
      1. 一部のホストでは相互運用性が許可されない場合があります。このため、入力もアクションもレンダリングされませんSome hosts might not allow interactivity, and will therefore not render inputs nor actions
      2. Action.Submit アクションは、ホストの判断で実行されます。このため、すべてのホストがすべての Action.Submit ペイロードを適切に処理するとは限りません。Execution of Action.Submit actions is at the discretion of the host, and not all hosts will necessarily properly handle all Action.Submit payloads. また、ホストによっては Action.Submit がまったくサポートされていない場合がありますFurthermore, some hosts might not support Action.Submit at all
  7. 形式は拡張可能でなければならないThe format needs to be extensible

    1. ホストでは、形式の機能を超えて、カスタムの要素やカスタムのアクションへのサポートを自由に追加できるようにする必要がありますHosts should have the freedom of adding support for custom elements or custom actions that go beyond what the format is capable of
    2. アクションについては、ホストによってサポートするアクションのセットが異なるため、これは特に重要ですThis is particularly important for actions, as various hosts don't necessarily support the same set of actions
    3. これらの追加は、ホストでの裁量に任されますThese additions are at the discretion of the host
      1. これらは、アダプティブ カードの仕様に対して "事実上" 追加されるものではありませんThey are not a de facto addition to the Adaptive Card specification
      2. このため、これらを使用するペイロードは、メインストリームのアダプティブ カード形式との互換性がなくなりますAs such, they make a payload that uses them incompatible with the mainstream Adaptive Card format
      3. ただし、5 で説明したように、ワーキング グループにこれらを提示し、形式の今後のバージョン向けの新機能として提案できますThey can however be presented to the Working Group and proposed as new features for a future version of the format, as described in point #5
  8. カードの作成者はコンテンツを所有し、ホスト アプリは外観を所有するCard authors own the content, host apps own the look and feel

    1. ホスト アプリによってスタイル設定が適用され、カードの外観が、アプリのエクスペリエンスのネイティブな拡張機能のようになりますHost apps impose their styling so cards look and feel like they are native extensions of the app's experience
    2. カードの作成者はスタイル設定を指定できますが、色やサイズなどのセマンティックな表現に限定されます。Card authors can still specify styling, but only via semantic expressions of colors, sizes, etc.
  9. 一般的な開発プラットフォーム向けに SDK を提供予定SDKs will be provided for the most popular developer platforms

    1. SDK により、すべてのホストでアダプティブ カードのペイロードを簡単にレンダリングできますSDKs make it easy to render Adaptive Card payloads in any host
    2. これにより、サードパーティの開発者と Microsoft チームの両方にとって、参加への障壁が非常に低くなりますThis ensures the barrier to entry is as low as can be both for third party developers and Microsoft teams