go-adaptivecards

README

go-adaptivecards

Experimental Go library for building and validating Microsoft Adaptive Cards.

Important Status

This project is experimental and not production-ready.

• API and behavior can change without notice.
• Breaking changes are expected.
• The implementation is not at 100% Microsoft Adaptive Cards feature parity.
• Use with caution, especially in production systems.

Scope

This repository provides:

• Strongly typed Go models for selected Adaptive Card features
• Builder-style APIs for composing cards
• Logical validation and JSON Schema validation support against schema versions 1.5.0
• JSON factory-based decoding for interface fields (Element, Action)
• Optional webhook posting helper for Teams/workflow endpoints

Install

go get github.com/untcha/go-adaptivecards

Quick Example

Quick "Hello, World!" example (from examples/simple/main.go):

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/untcha/go-adaptivecards/adaptivecards/card"
	"github.com/untcha/go-adaptivecards/adaptivecards/elements"
	"github.com/untcha/go-adaptivecards/adaptivecards/webhook"
)

func main() {
	// Webhook URL
	url := os.Getenv("TEAMS_TEST_WORKFLOW_URL")

	textblock := elements.NewTextBlock("Hello, World!")

	card, err := card.NewCard().
		AddElement(textblock).
		Build()

	if err != nil {
		panic(err)
	}

	json, _ := card.MarshalJSON()
	fmt.Println(string(json))

	// Post to Teams webhook if URL is provided
	if url != "" {
		if err := webhook.PostToWorkflowRaw(context.Background(), url, card); err != nil {
			panic(err)
		}
	}
}

Feature Matrix (Current State)

Legend:

• [x] Type/feature exists in this repo
• [ ] Not implemented yet
• Checked items can still be partial vs full official schema behavior

AdaptiveCard Root

• AdaptiveCard
• body
• actions
• selectAction
• backgroundImage
• minHeight
• rtl
• lang
• speak
• fallbackText
• verticalContentAlignment
• refresh (placeholder only)
• authentication (placeholder only)
• metadata (placeholder only)

Actions

• Action.OpenUrl
• Action.Submit
• Action.ToggleVisibility
• Action.ShowCard
• Action.Execute

Elements

• TextBlock
• RichTextBlock
• TextRun
• Image
• Media

Containers

• Container
• Column
• ColumnSet
• ActionSet
• FactSet
• ImageSet
• Table (including TableRow, TableCell, TableColumnDefinition)

Inputs

• Input.Text
• Input.Number
• Input.Date
• Input.Time
• Input.ChoiceSet
• Input.Toggle

Tooling / Validation

• Logical validation methods on card/types
• JSON factory decode for action/element interfaces
• Embedded Adaptive Card schema validation support
• Webhook helper (webhook.PostToWorkflowRaw)

Package Layout

• adaptivecards/card: AdaptiveCard root model and card-level builders/validation
• adaptivecards/actions: action types and action factory
• adaptivecards/elements: leaf elements and element validation
• adaptivecards/containers: container-style elements, including Table
• adaptivecards/inputs: input elements and validation
• adaptivecards/core/model: shared enums, value objects, low-level validation
• adaptivecards/core/element: element interfaces, fallback model, element factory
• adaptivecards/schema: schema validation integration
• adaptivecards/webhook: helpers to send card JSON to webhook endpoints

Development

Common commands:

task test
task lint
task check
task update:schema

License

This project is licensed under the MIT License - see the LICENSE file for details.