Reject Remote Schema Refs Before a Solo API Ships

A solo founder can ship an AI-drafted HTTP API on the same day the idea appears and still keep the infrastructure bill at zero. The gate is local. It rejects remote schema references, rejects any servers host outside a loopback allowlist, and rejects documented examples that exceed a fixed byte cap. The check ends before a process opens a socket, and before a free-tier prompt is spent proving what a file already knows.

Surprise cost starts in the contract, not in the cloud console. A drafting session asked to complete the API will often insert an https:// $ref, a hosted mock, or a bulky example copied from a vendor page. The editor still looks offline. The next resolver does not.

The bill hides in three fields

Remote $ref values fail in two directions. Offline, the laptop cannot fetch the schema, so the build breaks on a train. Online, the fetched host can add a key, a quota wall, or a paid tier without any change to application code. A root-local #/components/... reference stays inside one file. That is the reproducible choice.

servers is the second leak. One URL aimed at a metered mock, a gateway, or a vendor sandbox invents a host the founder never priced. Loopback is enough to ship today. A public base URL can live in a second file that is not the cost boundary this gate enforces.

Example payloads are the third leak. Large samples burn time, context, and any free request allowance long before the handler exists. A hard cap on example bytes keeps the contract small enough to reread. The 2048-byte number in the proposal is local policy. It is not a measured limit of any hosted plan.

Clear failures matter more than clever ones. Each error line names the JSON path and the rule that fired. A founder debugging at midnight should not have to infer whether the gate disliked a host, a ref, or a missing operationId.

Decision table

Spec signal	Gate	Why it matters on a zero bill
$ref starts with http://, https://, or //	Reject	Resolution can bill or break offline
$ref starts with #/	Allow	Stays inside the same JSON file
Any other $ref	Reject	File-relative refs wander across directories
servers[].url is http on 127.0.0.1 or localhost	Allow	Same-day loopback only
Any other server host or scheme	Reject	Stops an invented paid host
JSON size of an example over 2048 bytes	Reject	Keeps samples small enough to reread
Path operation missing operationId	Reject	Fixtures need a stable name
URL mentioned only in description	Allow	Prose is not a fetch

Steps

1. Freeze the allowlist before any draft

Write allowed hosts into the checker, not into a chat log. Two names are enough on day one: 127.0.0.1 and localhost. A longer list is a product decision. It should arrive as a reviewed diff, not as a model suggestion that a sandbox would be more realistic.

2. Demand OpenAPI JSON

The Python standard library parses JSON. It does not parse YAML. A zero-install gate should refuse a spec that needs a third-party parser before it can be trusted. Ask the drafting session for JSON only. Treat a YAML blob as unfinished, even if the prose is polished.

3. Run the budget gate

Save the proposal as spec_budget.py. Exit status 0 means the file may stay in the repo. Any other status means the spec does not leave the laptop. Do not override the gate to unblock a demo.

4. Bind one fixture to each operationId

Coverage here is a name check, not a live call. A fixture file maps operationId to a path and a status code. Missing names fail the binder. Recording fixtures by clicking a hosted mock would spend the budget this workflow refuses to open.

5. Smoke-test loopback, or stop

Start the founder's own process on 127.0.0.1 when that process exists. Cap the probe at two seconds. If the handler is not written yet, ship the spec, the gate, and the fixture binder. Those three files are a complete same-day result. A staging cluster is not part of the definition of done.

Same-day file set

A same-day ship, under this method, is four files and two commands. openapi.json holds the contract. spec_budget.py enforces the table. bind_fixtures.py checks names. fixtures.json stores path and status only. No container registry, no remote state, and no secret store is required to call the work finished.

That definition will feel small to a team with a platform group. It is the point. A solo founder who adds a hosted log drain just for the demo has already left the zero-bill path. Add that drain later, in a diff that names the host on purpose.

Proposal checker

This script is an unexecuted proposal. It was not run against a live account, and it claims no timing result. Python 3.9 or newer is assumed. No third-party package is imported.

#!/usr/bin/env python3
'''Local OpenAPI budget gate. Proposal only; not executed for this article.'''

import json
import sys
from urllib.parse import urlparse

ALLOWED_HOSTS = {'127.0.0.1', 'localhost'}
MAX_EXAMPLE_BYTES = 2048
HTTP_METHODS = {
    'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace',
}

def fail(errors):
    for item in errors:
        print(f'spec-budget: {item}', file=sys.stderr)
    return 1 if errors else 0

def walk(node, path, errors):
    if isinstance(node, dict):
        ref = node.get('$ref')
        if isinstance(ref, str):
            if ref.startswith(('http://', 'https://', '//')):
                errors.append(f'{path}: remote $ref blocked: {ref}')
            elif not ref.startswith('#/'):
                errors.append(
                    f'{path}: only root-local #/ refs are allowed: {ref}'
                )
        if 'example' in node:
            try:
                encoded = json.dumps(
                    node['example'], separators=(',', ':')
                ).encode('utf-8')
            except TypeError:
                errors.append(f'{path}: example is not JSON-serializable')
            else:
                size = len(encoded)
                if size > MAX_EXAMPLE_BYTES:
                    errors.append(
                        f'{path}: example is {size} bytes; cap is {MAX_EXAMPLE_BYTES}'
                    )
        for key, value in node.items():
            walk(value, f'{path}.{key}', errors)
    elif isinstance(node, list):
        for index, value in enumerate(node):
            walk(value, f'{path}[{index}]', errors)

def check_servers(doc, errors):
    servers = doc.get('servers')
    if not isinstance(servers, list) or not servers:
        errors.append('servers: at least one loopback URL is required')
        return
    for index, server in enumerate(servers):
        url = server.get('url') if isinstance(server, dict) else None
        parsed = urlparse(url or '')
        if parsed.scheme != 'http' or parsed.hostname not in ALLOWED_HOSTS:
            errors.append(
                f'servers[{index}]: only http loopback is allowed, got {url!r}'
            )

def check_operation_ids(doc, errors):
    paths = doc.get('paths')
    if not isinstance(paths, dict) or not paths:
        errors.append('paths: at least one path is required')
        return
    for path, item in paths.items():
        if not isinstance(item, dict):
            errors.append(f'paths.{path}: expected an object')
            continue
        for method, op in item.items():
            if method.lower() not in HTTP_METHODS or not isinstance(op, dict):
                continue
            if not op.get('operationId'):
                errors.append(f'paths.{path}.{method}: missing operationId')

def main():
    if len(sys.argv) != 2:
        print('usage: spec_budget.py openapi.json', file=sys.stderr)
        return 2
    with open(sys.argv[1], encoding='utf-8') as handle:
        doc = json.load(handle)
    if not isinstance(doc, dict):
        print('spec-budget: root must be an object', file=sys.stderr)
        return 1
    errors = []
    check_servers(doc, errors)
    check_operation_ids(doc, errors)
    walk(doc, '$', errors)
    return fail(errors)

if __name__ == '__main__':
    raise SystemExit(main())

The illustration below should fail. It is synthetic. It is not a captured third-party document.

{
  "openapi": "3.0.3",
  "info": {"title": "demo", "version": "0.0.1"},
  "servers": [{"url": "https://mock.example.test/v1"}],
  "paths": {
    "/health": {
      "get": {
        "responses": {
          "200": {
            "description": "ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://schemas.example.test/Health.json"
                }
              }
            }
          }
        }
      }
    }
  }
}

Commands to keep next to the script:

python3 spec_budget.py openapi.json
printf 'gate_exit=%s\n' "$?"
curl --fail --silent --show-error --max-time 2 http://127.0.0.1:8080/health

The curl line assumes a local process the founder already chose to start. Nothing in this article records a live response from that command.

Proposal fixture binder

The binder is also unexecuted. It only checks that every operationId has a row. It does not send HTTP.

#!/usr/bin/env python3
'''Fixture name binder. Proposal only; not executed for this article.'''

import json
import sys

HTTP_METHODS = {
    'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace',
}

def main():
    if len(sys.argv) != 3:
        print('usage: bind_fixtures.py openapi.json fixtures.json', file=sys.stderr)
        return 2
    with open(sys.argv[1], encoding='utf-8') as handle:
        spec = json.load(handle)
    with open(sys.argv[2], encoding='utf-8') as handle:
        fixtures = json.load(handle)
    missing = []
    for path, item in (spec.get('paths') or {}).items():
        if not isinstance(item, dict):
            continue
        for method, op in item.items():
            if method.lower() not in HTTP_METHODS or not isinstance(op, dict):
                continue
            op_id = op.get('operationId')
            if op_id and op_id not in fixtures:
                missing.append(op_id)
    if missing:
        print('missing fixtures: ' + ', '.join(missing), file=sys.stderr)
        return 1
    print('fixtures cover every operationId')
    return 0

if __name__ == '__main__':
    raise SystemExit(main())

A matching fixture file for a spec that already passed the host and ref rules:

{
  "getHealth": {"path": "/health", "status": 200}
}

python3 spec_budget.py openapi.json && python3 bind_fixtures.py openapi.json fixtures.json

Run the binder only after the budget gate exits 0. A spec with a remote ref should never reach fixture review.

Where free model access fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The operator describes MonkeyCode as an open-source coding project and states that free model access and a free server option are available. Those two availability claims are operator-supplied for this draft. No model name, token quota, hardware shape, or end date is stated here, because those details were not checked against a primary source dated 2026-09-25. Confirm current terms on the project site before treating the free path as a plan.

Free model access belongs at a single step: turn the decision table into a first JSON spec and a first patch against the checker. Put the allowlist and the byte cap in the prompt. Forbid remote $ref values in that same prompt. Once the files exist, stop the session. Re-running the scripts costs nothing and does not require the model to stay up.

A free server is optional, and it is manual. Use it only as a click-through after the local gate has passed. Do not copy its hostname into the gated servers array. The build should still pass with the network off. If capacity, fairness rules, or signup terms are unclear, skip the hosted click-through. The local files remain the ship.

Readers who want that draft pass can paste the decision table into MonkeyCode's free model access, require OpenAPI JSON, and run spec_budget.py before opening any hosted demo. The checker never calls the product.

Who should skip this gate

A team that vendors public JSON Schema through a pinned internal mirror needs a mirror policy, not a blanket ban. A product that must publish a public base URL in the same document CI validates should split the public file from the gated file, rather than weakening the allowlist. Founders who need full semantic lint, OAuth flow coverage, or a formal uptime target should not pretend a standard-library walk is that system. Anyone who cannot accept free-tier variance should not put a launch date on the free path. The checker does not need the product in order to be useful.

Limits

The walker is structural. A URL that appears only in a description is allowed, because the gate does not fetch prose. A sloppy implementation can still call a host the spec never named. This file check does not watch sockets. Add a separate runtime host allowlist if the process might drift from the contract. The byte cap is local policy, not a provider fair-use ceiling. Nested examples are visited, but format, nullable, and discriminators are not evaluated. Literal ::1 is outside the day-one allowlist until a founder adds it on purpose. WebSocket, gRPC, and GraphQL contracts are out of scope. No pass rate is claimed. The proposals were not executed for this article.

Ship the contract on loopback. Fail remote schema imports in the file itself. Spend a free model pass on the first draft only, then let the scripts keep the bill at zero.