@shortlink-org/portolan 0.1.0

package/plugins/extract-openapi/extract_test.go

@@ -0,0 +1,545 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+	"gopkg.in/yaml.v3"
+)
+
+func fragment(t *testing.T) catalog.Catalog {
+	t.Helper()
+
+	resp, err := extract(
+		plugin.Input{Root: "testdata", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		Options{Context: "billing", Service: "invoices", Spec: "openapi.yaml"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(resp.Files) != 1 {
+		t.Fatalf("expected one fragment, got %d files", len(resp.Files))
+	}
+
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	return out
+}
+
+func testDocument(t *testing.T, source string) *document {
+	t.Helper()
+	var root yaml.Node
+	if err := yaml.Unmarshal([]byte(source), &root); err != nil {
+		t.Fatal(err)
+	}
+	node := root.Content[0]
+	return &document{root: node, path: "test.yaml", cache: map[string]*document{}}
+}
+
+func provided(t *testing.T) []catalog.RpcService {
+	t.Helper()
+
+	return fragment(t).Contexts[0].Services[0].Provides
+}
+
+// A method is an object now, and every assertion below is about the names.
+func names(methods []catalog.RpcMethod) []string {
+	out := make([]string, 0, len(methods))
+	for _, method := range methods {
+		out = append(out, method.Name)
+	}
+
+	return out
+}
+
+// Tags organise operations within one OpenAPI contract. They must not split a
+// document into duplicate interfaces with duplicate message inventories.
+func TestTagsStayWithinOneService(t *testing.T) {
+	provides := provided(t)
+	if len(provides) != 1 {
+		t.Fatalf("provides = %d, want one contract", len(provides))
+	}
+	if provides[0].ID != "billing.v2" {
+		t.Errorf("interface = %q", provides[0].ID)
+	}
+	if got := strings.Join(names(provides[0].Methods), ","); got != "raiseInvoice,GET /v2/health" {
+		t.Errorf("methods = %q", got)
+	}
+}
+
+func TestSharedSchemaIsNotRepeatedAcrossTags(t *testing.T) {
+	doc := testDocument(t, `
+openapi: 3.0.3
+info: {title: shared, version: 1.0.0}
+paths:
+  /orders:
+    get:
+      tags: [orders]
+      operationId: listOrders
+      responses:
+        '200':
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/Result'}
+  /refunds:
+    get:
+      tags: [refunds]
+      operationId: listRefunds
+      responses:
+        '200':
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/Result'}
+components:
+  schemas:
+    Result: {type: object}
+`)
+
+	services := rpcServices(doc, "shared.v1", "test.yaml", &plugin.Builder{})
+	if len(services) != 1 || len(services[0].Methods) != 2 || len(services[0].Messages) != 1 {
+		t.Fatalf("contract = %+v", services)
+	}
+}
+
+// The id is the document's own title and major version, so it survives a patch
+// release without every id in the catalog changing.
+func TestApiIDFromTitleAndMajorVersion(t *testing.T) {
+	for _, p := range provided(t) {
+		if !strings.HasPrefix(p.ID, "billing.v2") {
+			t.Errorf("unexpected id %q", p.ID)
+		}
+	}
+}
+
+// A shared response is how a spec says "the same error body as everywhere
+// else". Not following it would document the endpoint as returning nothing
+// when it fails.
+func TestFollowsRefsThroughSharedResponses(t *testing.T) {
+	var names []string
+	for _, p := range provided(t) {
+		if p.ID != "billing.v2" {
+			continue
+		}
+		for _, message := range p.Messages {
+			names = append(names, message.Name)
+		}
+	}
+
+	// Line arrives through RaiseRequest, Error through the shared BadRequest.
+	want := "RaiseRequest,Invoice,Error,Line"
+	if strings.Join(names, ",") != want {
+		t.Errorf("messages = %v, want %s", names, want)
+	}
+}
+
+func TestFieldTypesAndOptionality(t *testing.T) {
+	var request *catalog.RpcMessage
+	for _, p := range provided(t) {
+		for i := range p.Messages {
+			if p.Messages[i].Name == "RaiseRequest" {
+				request = &p.Messages[i]
+			}
+		}
+	}
+	if request == nil {
+		t.Fatal("no RaiseRequest message")
+	}
+
+	fields := map[string]catalog.Field{}
+	for _, field := range request.Fields {
+		fields[field.Name] = field
+	}
+
+	if got := fields["customerId"].Type; got != "string (uuid)" {
+		t.Errorf("format belongs in the type, got %q", got)
+	}
+	if got := fields["customerId"].Doc; got != "Who is being billed." {
+		t.Errorf("a required field carries its description alone, got %q", got)
+	}
+	if got := fields["lines"].Type; got != "[]Line" {
+		t.Errorf("an array of refs, got %q", got)
+	}
+	// Which fields must be sent is the first thing a caller needs, and the
+	// catalog has nowhere else to put it.
+	if got := fields["lines"].Doc; !strings.HasPrefix(got, "Optional.") {
+		t.Errorf("an optional field should say so, got %q", got)
+	}
+}
+
+func TestComposedSchemasMapsEnumsAndNullableTypes(t *testing.T) {
+	doc := testDocument(t, `
+components:
+  schemas:
+    Base:
+      type: object
+      required: [id]
+      properties:
+        id: {type: string, format: uuid}
+    Account:
+      allOf:
+        - $ref: '#/components/schemas/Base'
+        - type: object
+          required: [labels]
+          properties:
+            labels:
+              type: object
+              additionalProperties: {type: string}
+            state:
+              type: string
+              enum: [active, disabled]
+            contact:
+              nullable: true
+              oneOf:
+                - {type: string, format: email}
+                - {type: string, format: phone}
+`)
+	account := child(doc.root, "components", "schemas", "Account")
+	fields := map[string]catalog.Field{}
+	for _, field := range schemaFields(doc, account) {
+		fields[field.Name] = field
+	}
+
+	if fields["id"].Type != "string (uuid)" || strings.HasPrefix(fields["id"].Doc, "Optional.") {
+		t.Errorf("allOf required field = %+v", fields["id"])
+	}
+	if fields["labels"].Type != "map[string]string" || strings.HasPrefix(fields["labels"].Doc, "Optional.") {
+		t.Errorf("map field = %+v", fields["labels"])
+	}
+	if fields["state"].Type != "string enum(active | disabled)" || !strings.HasPrefix(fields["state"].Doc, "Optional.") {
+		t.Errorf("enum field = %+v", fields["state"])
+	}
+	if fields["contact"].Type != "string (email) | string (phone) | null" {
+		t.Errorf("oneOf nullable field type = %q", fields["contact"].Type)
+	}
+}
+
+func TestDiscriminatorKeepsPolymorphicMessagesVisible(t *testing.T) {
+	doc := testDocument(t, `
+openapi: 3.1.0
+info: {title: animals, version: 1.0.0}
+paths:
+  /pets/{id}:
+    get:
+      operationId: getPet
+      responses:
+        '200':
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/Pet'}
+components:
+  schemas:
+    Pet:
+      oneOf:
+        - {$ref: '#/components/schemas/Cat'}
+        - {$ref: '#/components/schemas/Dog'}
+      discriminator:
+        propertyName: kind
+        mapping:
+          feline: '#/components/schemas/Cat'
+    Cat:
+      type: object
+      required: [kind, lives]
+      properties:
+        kind: {type: string}
+        lives: {type: integer}
+    Dog:
+      type: object
+      required: [kind, good]
+      properties:
+        kind: {type: string}
+        good: {type: boolean}
+`)
+	services := rpcServices(doc, "animals.v1", "test.yaml", &plugin.Builder{})
+	if len(services) != 1 || len(services[0].Methods) != 1 {
+		t.Fatalf("services = %+v", services)
+	}
+	if got := services[0].Methods[0].Response; got != "Pet" {
+		t.Fatalf("response = %q, want Pet", got)
+	}
+
+	byName := map[string]catalog.RpcMessage{}
+	for _, message := range services[0].Messages {
+		byName[message.Name] = message
+	}
+	pet, ok := byName["Pet"]
+	if !ok || pet.Discriminator == nil {
+		t.Fatalf("Pet discriminator is missing: %+v", pet)
+	}
+	if pet.Discriminator.Property != "kind" {
+		t.Errorf("property = %q", pet.Discriminator.Property)
+	}
+	if len(pet.Discriminator.Variants) != 2 {
+		t.Fatalf("variants = %+v", pet.Discriminator.Variants)
+	}
+	if got := pet.Discriminator.Variants[0]; got.Value != "feline" || got.Message != "Cat" {
+		t.Errorf("mapped variant = %+v", got)
+	}
+	if got := pet.Discriminator.Variants[1]; got.Value != "Dog" || got.Message != "Dog" {
+		t.Errorf("implicit variant = %+v", got)
+	}
+	if _, ok := byName["Cat"]; !ok {
+		t.Error("Cat concrete message is missing")
+	}
+	if _, ok := byName["Dog"]; !ok {
+		t.Error("Dog concrete message is missing")
+	}
+}
+
+func TestRelativeExternalSchemaRefsAreLoaded(t *testing.T) {
+	dir := t.TempDir()
+	common := filepath.Join(dir, "common.yaml")
+	root := filepath.Join(dir, "openapi.yaml")
+	if err := os.WriteFile(common, []byte(`components:
+  schemas:
+    External:
+      type: object
+      required: [code]
+      properties:
+        code: {type: integer, format: int64}
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(root, []byte(`openapi: 3.1.0
+info: {title: external, version: 1.0.0}
+paths:
+  /external:
+    get:
+      operationId: getExternal
+      responses:
+        '200':
+          content:
+            application/json:
+              schema: {$ref: './common.yaml#/components/schemas/External'}
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	doc, err := load(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	services := rpcServices(doc, "external.v1", root, &plugin.Builder{})
+	if len(services) != 1 || len(services[0].Messages) != 1 {
+		t.Fatalf("services = %+v", services)
+	}
+	message := services[0].Messages[0]
+	if message.Name != "External" || len(message.Fields) != 1 || message.Fields[0].Type != "integer (int64)" {
+		t.Errorf("external message = %+v", message)
+	}
+}
+
+// The fragment describes what the service answers and nothing else; the name
+// and readme belong to whichever source knows them.
+func TestFragmentClaimsNothingItDoesNotKnow(t *testing.T) {
+	service := fragment(t).Contexts[0].Services[0]
+
+	if service.Name != "" || service.Readme != "" || service.Repo != "" {
+		t.Errorf("the api fragment should not name the service: %+v", service)
+	}
+	if len(service.Aggregates) != 0 {
+		t.Error("the api fragment should carry no aggregates")
+	}
+}
+
+// What the operation sends and answers with. The document names both whenever
+// the body is a $ref; a success with no body at all is answered by its status,
+// because 204 is a real answer and an empty string reads as an unread one.
+func TestShapesOnEitherSide(t *testing.T) {
+	byName := map[string]catalog.RpcMethod{}
+	for _, p := range provided(t) {
+		for _, method := range p.Methods {
+			byName[method.Name] = method
+		}
+	}
+
+	raise, ok := byName["raiseInvoice"]
+	if !ok {
+		t.Fatal("no raiseInvoice")
+	}
+	if raise.Request != "RaiseRequest" || raise.Response != "Invoice" {
+		t.Errorf("raiseInvoice sends %q and returns %q", raise.Request, raise.Response)
+	}
+
+	health, ok := byName["GET /v2/health"]
+	if !ok {
+		t.Fatal("no health operation")
+	}
+	if health.Request != "" || health.Response != "200" {
+		t.Errorf("health sends %q and returns %q", health.Request, health.Response)
+	}
+}
+
+// The same document, read as a copy vendored from outside the estate: the
+// fragment carries no context and no service, only the external and what it
+// answers on, under the id the manifest gave it.
+func TestExternalCarriesNoService(t *testing.T) {
+	resp, err := extract(
+		plugin.Input{Root: "testdata", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		Options{External: "psp", ExternalName: "PSP", ExternalURL: "https://psp.example/docs", API: "psp.v1", Spec: "openapi.yaml"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+	if len(out.Contexts) != 0 {
+		t.Errorf("an external's fragment names %d contexts", len(out.Contexts))
+	}
+	if len(out.Externals) != 1 {
+		t.Fatalf("externals = %+v", out.Externals)
+	}
+	ext := out.Externals[0]
+	if ext.ID != "psp" || ext.Slug != "psp" || ext.Name != "PSP" || ext.URL != "https://psp.example/docs" {
+		t.Errorf("external = %+v", ext)
+	}
+	var ids []string
+	for _, p := range ext.Provides {
+		ids = append(ids, p.ID)
+	}
+	if strings.Join(ids, ",") != "psp.v1" {
+		t.Errorf("interfaces = %v", ids)
+	}
+
+	// A dotted id would put the external inside a context nobody declared.
+	if _, err := extract(plugin.Input{Root: "testdata"}, Options{External: "shop.psp"}); err == nil {
+		t.Error("an external with a dot in its id was accepted")
+	}
+}
+
+// A Swagger 2.0 document keeps its schemas under definitions, sends its body
+// as a parameter and puts the response schema straight on the response. A
+// generator that still writes 2.0 - swag, for one - documents a service
+// exactly as well as one that writes 3.
+func TestSwagger2DefinitionsAndBodyParameters(t *testing.T) {
+	resp, err := extract(
+		plugin.Input{Root: "testdata/swagger2", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		Options{Context: "avia", Service: "aviasupp", Spec: "swagger.yaml"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	byName := map[string]catalog.RpcMethod{}
+	shapes := map[string][]string{}
+	for _, p := range out.Contexts[0].Services[0].Provides {
+		for _, method := range p.Methods {
+			byName[method.Name] = method
+		}
+		for _, message := range p.Messages {
+			var fields []string
+			for _, field := range message.Fields {
+				fields = append(fields, field.Name+" "+field.Type)
+			}
+			shapes[message.Name] = fields
+		}
+	}
+
+	book, ok := byName["POST /book"]
+	if !ok {
+		t.Fatalf("no POST /book among %v", byName)
+	}
+	if book.Request != "book.Request" || book.Response != "book.Response" {
+		t.Errorf("book sends %q and returns %q", book.Request, book.Response)
+	}
+
+	// The body parameter is inherited from the path item, and a list of a
+	// definition is that definition with brackets.
+	search, ok := byName["search"]
+	if !ok {
+		t.Fatalf("no search among %v", byName)
+	}
+	if search.Request != "search.Request" || search.Response != "search.Offer[]" {
+		t.Errorf("search sends %q and returns %q", search.Request, search.Response)
+	}
+
+	if got := strings.Join(shapes["book.Request"], ", "); got != "offer_id string, passengers []book.Passenger" {
+		t.Errorf("book.Request = %q", got)
+	}
+	if _, ok := shapes["book.Passenger"]; !ok {
+		t.Errorf("book.Passenger, reached through book.Request, is not among the messages: %v", shapes)
+	}
+	if _, ok := shapes["search.Offer"]; !ok {
+		t.Errorf("search.Offer, the response item, is not among the messages: %v", shapes)
+	}
+}
+
+// Nothing named: the tree says which documents this service implements and
+// which it calls. A server generated from a document means provides; a client
+// generated from one means a system outside the estate, named by the
+// document's own title, unless the manifest says the api is one of ours. A
+// document with neither beside it is reported and left alone.
+func TestATreeSaysWhatIsImplementedAndWhatIsCalled(t *testing.T) {
+	read := func(opts Options) (catalog.Catalog, plugin.Response) {
+		t.Helper()
+		opts.Context, opts.Service = "avia", "aviasupp"
+		resp, err := extract(plugin.Input{Root: "testdata/discover", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"}, opts)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var out catalog.Catalog
+		if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+			t.Fatal(err)
+		}
+		return out, resp
+	}
+
+	out, resp := read(Options{Peers: map[string]string{"partner-api.v2": "shop.partner"}})
+
+	var provided []string
+	for _, p := range out.Contexts[0].Services[0].Provides {
+		provided = append(provided, p.ID+" from "+p.Source)
+	}
+	if strings.Join(provided, ", ") != "aviasupp.v1 from testdata/discover/docs/swagger.yaml" {
+		t.Errorf("provides = %v", provided)
+	}
+
+	if len(out.Externals) != 1 {
+		t.Fatalf("externals = %+v", out.Externals)
+	}
+	acme := out.Externals[0]
+	if acme.ID != "acme-flights" || acme.Slug != "acme-flights" || acme.Name != "Acme Flights API" || acme.Summary != "Flights and ancillaries from Acme." || acme.URL != "https://developer.acme.example/flights" {
+		t.Errorf("external = %+v", acme)
+	}
+	if len(acme.Provides) != 1 || acme.Provides[0].ID != "acme-flights-api.v1" {
+		t.Errorf("acme provides %+v", acme.Provides)
+	}
+
+	warned := func(substring string) bool {
+		for _, w := range resp.Warnings() {
+			if strings.Contains(w.Message, substring) {
+				return true
+			}
+		}
+		return false
+	}
+	if !warned("found testdata/discover/internal/stray/openapi.yaml, and nothing beside it says") {
+		t.Errorf("the stray document was not reported; warnings = %+v", resp.Warnings())
+	}
+	if !warned("nameless/client/openapi.yaml is called from here and its document has no title") {
+		t.Errorf("the nameless document was not reported; warnings = %+v", resp.Warnings())
+	}
+
+	// The manifest may name the system itself; and a called document whose
+	// api no peers line claims is a system outside the estate too.
+	out, _ = read(Options{Externals: map[string]string{"acme-flights-api.v1": "acme"}})
+	var ids []string
+	for _, e := range out.Externals {
+		ids = append(ids, e.ID)
+	}
+	if strings.Join(ids, ",") != "acme,partner" {
+		t.Errorf("externals = %v", ids)
+	}
+}

package/plugins/extract-openapi/main.go

@@ -0,0 +1,75 @@
+// Package main is portolan-extract-openapi: an OpenAPI document in, a catalog
+// fragment out.
+//
+// It describes one aspect of a service - what it answers - and nothing else.
+// The aggregates come from a different extractor reading a different part of
+// the tree, and the two meet in the merge. Neither knows the other exists,
+// which is the whole reason each of them stays small.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor: the things an OpenAPI
+// document does not say about the estate it belongs to.
+type Options struct {
+	Context string `json:"context"`
+	Service string `json:"service"`
+
+	// Spec is the document, relative to the input root. Left out, the
+	// extractor walks the tree for every document and reads what sits beside
+	// each one: a server generated from it means this service implements it,
+	// a client generated from it means this service calls it, and a called
+	// document names a system outside the estate unless `peers` says the api
+	// is one of ours.
+	Spec string `json:"spec,omitempty"`
+
+	// Peers says which called documents are ours, as the api id to the
+	// service that implements it: {"auth.v1": "auth.auth"}. A called document
+	// whose api is named here is that service's to describe, and is skipped.
+	Peers map[string]string `json:"peers,omitempty"`
+
+	// Externals names a called document's system when the name its title
+	// would give is not the one wanted, as the api id to the external's bare
+	// id: {"stripe.v1": "stripe"}.
+	Externals map[string]string `json:"externals,omitempty"`
+
+	// API prefixes the ids of the rpc services this produces. Left out, it is
+	// built from the document's title and major version - `auth` 1.0.0 gives
+	// `auth.v1`, and a tag called `users` gives `auth.v1.Users`.
+	API string `json:"api,omitempty"`
+
+	// External names a system outside the estate the document belongs to,
+	// when it is not one of ours: the copy vendored beside an adapter, read
+	// for what the third party answers on. Set, the fragment carries no
+	// context and no service, only the external, and `context` and `service`
+	// are not read.
+	External        string `json:"external,omitempty"`
+	ExternalName    string `json:"externalName,omitempty"`
+	ExternalSummary string `json:"externalSummary,omitempty"`
+	ExternalURL     string `json:"externalUrl,omitempty"`
+
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-openapi:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+
+		return extract(req.Input, opts)
+	})
+}

package/plugins/extract-openapi/options.schema.json

@@ -0,0 +1,62 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context that owns the service this document belongs to. Defaults to the name of the input directory.",
+      "examples": ["auth"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service the document describes. Defaults to the name of the input directory.",
+      "examples": ["auth"]
+    },
+    "spec": {
+      "type": "string",
+      "description": "The OpenAPI document, relative to the input root. Left out, the extractor walks the tree for every document and reads what sits beside each: a server generated from it means this service implements it, a client generated from it means this service calls it, and a called document names a system outside the estate unless peers says the api is one of ours.",
+      "examples": ["internal/infrastructure/transport/http/gen/openapi.yaml"]
+    },
+    "peers": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which called documents are ours, as the api id to the service that implements it. A called document whose api is named here is that service's to describe, and is skipped rather than read as a system outside the estate.",
+      "examples": [{ "auth.v1": "auth.auth" }]
+    },
+    "externals": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "What a called document's system is called when the name its title would give is not the one wanted, as the api id to the external's bare id. Left out, a document titled \"Stripe API\" makes the external stripe.",
+      "examples": [{ "stripe.v1": "stripe" }]
+    },
+    "api": {
+      "type": "string",
+      "description": "Prefix for the ids of the rpc services this produces. Left out, it is the document's own x-portolan-api when it carries one, and otherwise built from its title and major version: auth 1.0.0 gives auth.v1, and a tag called users gives auth.v1.Users.",
+      "examples": ["auth.v1"]
+    },
+    "external": {
+      "type": "string",
+      "description": "Id of a system outside the estate the document belongs to, when it is not one of ours: a copy vendored beside the adapter that calls it, read for what the third party answers on. A bare name with no dot, the same one the caller's extractor is given under externals. Set, the fragment carries the external and no service, and context and service are not read.",
+      "examples": ["stripe"]
+    },
+    "externalName": {
+      "type": "string",
+      "description": "What the external is called on the page.",
+      "examples": ["Stripe"]
+    },
+    "externalSummary": {
+      "type": "string",
+      "description": "A sentence or two on what the estate uses it for."
+    },
+    "externalUrl": {
+      "type": "string",
+      "description": "Where the third party documents itself, for a reader who needs more than the vendored copy.",
+      "examples": ["https://docs.stripe.com/api"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "api.json"
+    }
+  }
+}