Bootstrap Accordant Models from OpenAPI (Swagger) documents

[Immad (imnaseer)]

Writing an Accordant model from scratch requires users to describe both the operations exposed by a system and the behavior those operations permit. For an HTTP API, much of the structural information already exists in its OpenAPI description.

An OpenAPI document can tell us:

• which operations exist;
• their request parameters and payloads;
• which fields are required;
• their response types and status codes;
• and example request and response values.

This is enough to generate many of the basic building blocks of an Accordant model. However, OpenAPI generally does not describe the behavioral relationships between operations.

For example, it usually does not formally state that:

• a POST operation creates a resource;
• a successful DELETE removes that resource;
• a successful GET means that the resource exists;
• one resource is the parent of another;
• or creating a child requires its parent to exist.

These relationships can often be inferred from paths, HTTP methods, operation names, and schemas, but those inferences will not always be correct.

Proposed feature

Create a feature that bootstraps an Accordant model from an OpenAPI document.

The feature will generate the structural parts of the model directly from OpenAPI and provide a simple way for users to describe or confirm the missing behavioral relationships, such as:

• which operations create, read, update, or delete resources;
• how resources are identified;
• which resources have parent-child relationships;
• and which conditions cause an operation to fail.

The result does not need to be a complete model immediately. Instead, it should provide a useful starting point that users can refine incrementally.

Supporting incomplete models

A central challenge is that the generated model will not initially know every rule enforced by the API.

In some cases, it can confidently determine that an operation must fail. For example:

• a required field is missing;
• a referenced parent does not exist;
• or a request violates a known schema constraint.

However, when none of these conditions applies, the feature may still not know that the operation must succeed. The API may enforce additional rules that are not described in OpenAPI, such as authorization checks, quotas, uniqueness requirements, or other business constraints.

The generated model should represent this uncertainty honestly.

For example, an initial model for creating a widget could use Accordant’s Expect.OneOf(...) syntax to permit either a successful creation or a failure:

spec.Operation<CreateWidgetRequest, ApiResult>(
    "CreateWidget",
    (request, state) =>
    {
        if (string.IsNullOrEmpty(request.Name))
        {
            return Expect.That<ApiResult>(r => r.IsBadRequest)
                .SameState();
        }

        return Expect.OneOf(
            // The API accepts the request and creates the widget.
            Expect.That<ApiResult>(r => r.IsSuccess)
                .ThenState(next =>
                    next.Widgets[request.WidgetId] =
                        new WidgetState { Name = request.Name }),

            // The API rejects the request for a rule that the
            // generated model does not know yet.
            Expect.That<ApiResult>(r => !r.IsSuccess)
                .SameState()
        );
    });

This model makes one definite claim: a request without the required name must fail.

For other requests, it remains deliberately noncommittal. A successful response means that the widget is added to the modeled state. A failure means that the state remains unchanged. Accordant already supports this kind of branching through Expect.OneOf(...), with all matching next states retained in the state profile.

The model is therefore underspecified, but honest. It does not claim to understand business rules that are absent from the OpenAPI document.

As users learn more about the API, they can progressively strengthen the model:

Creating a widget without its parent must fail.

Creating a duplicate widget must fail.

Creating a valid widget with an existing parent and an unused ID
must succeed.

This makes model development iterative rather than all-or-nothing. Users can begin with a conservative model and add precision over time.

Users should also be able to specify particular requests or sequences that must succeed, even when they have not yet expressed the complete general success rule. For example, they could require that a documented example payload succeeds or that a known create-then-read workflow completes successfully.

Role of AI

AI can help propose the behavioral relationships that are missing from OpenAPI. It can inspect routes, operation names, schemas, examples, and status codes to suggest likely CRUD behavior and resource relationships.

These suggestions should remain explicit and reviewable. Deterministic information from OpenAPI can be generated directly, while inferred behavioral rules can be confirmed, changed, or left underspecified by the user.

As a possible follow-on feature—or a separate project—an AI agent could interact with a running API, execute example workflows, and learn more about its semantics experimentally.

The main goal of this feature is narrower: make it easy to obtain a useful, honest, and incrementally refinable Accordant model from an existing OpenAPI description.