TeamAPI documents
A TeamAPI document is a file that defines and annotates the different details of a team and their interactions with other teams within an organziation.
The format of the file must be JSON or YAML; however, only the subset of YAML that matches the JSON capabilities is allowed:
teamapi: 0.0.1
info:
name: Example stream A
focus: Core focus of the team
type: stream-aligned
channels:
- type: slack
name: example-stream-a
searchTerms:
- term: Example team search term
platform:
$ref: https://github.com/example.com/example-platform-team/teamapi.yml
services:
- name: Example Service A
url: https://anexampleservice.com
versioning:
type: semantic
repository: https://github.com/example.com/example-service-a
work:
services:
- name: Improve the example service a
$ref: https://github.com/example.com/example-service-a
waysOfWorking:
- name: Lean
$ref: https://example.internal-wiki.com/ways-of-working/lean
meetings:
- purpose: daily sync
dayOfWeek: Wednesday
timeOfDay: 09:00
durationMinutes: 15
interactions:
- teamName: Example Platform Team
mode: X-as-a-service
purpose: Consume the example platform services to reduce cognitive load
startDate: 01/01/2022
expectedDuration: 3
expectedDurationUnit: months
$ref: https://github.com/example.com/example-platform-team/teamapi.yml
- teamName: Automation Test Enabling Team
mode: Facilitating
purpose: Introduce automation tests into the example service
$ref: https://github.com/example.com/automation-test-team/teamapi.yml
dependencies:
- teamName: Example stream b
description: We currently rely on example stream b to make changes to component X.
type: Blocking
$ref: https://github.com/example.com/example-stream-b-team/teamapi.yml
- teamName: Example Platform Team
description: We use the platform team to provide CI/CD services
type: OK
$ref: https://github.com/example.com/example-platform-team/teamapi.yml
The TeamAPI document is a machine-readable definition of your team's API. This document can then be used to generate documentation and visualizations of how the teams within your organization are interacting and how that changes over time.
Using a TeamAPI document schema provides a machine-readable and easily parseable by code file that will provide a myriad of useful applications including things like automatic diagram creation or automatic team discovery i.e. something could scan each of your repositories, find the teamapi.yml file, parse it and collate all of the teams in your organization into a diagram that highlights the interactions and dependencies between them.
For more details on the specification please see the TeamAPI Specification