`_resource.json`

Path: apis/<api>/resources/<resource>/_resource.json

Holds the IDE-specific metadata for a resource that isn't in the OpenAPI spec: creation defaults, notes, spec overrides, extra parameters, locally-defined operations, and plugin data. Operation details (schemas, responses) stay in the spec; this file only stores what you add on top.

Example

{
  "version": 1,
  "defaults": {
    "headers": { "Accept": "application/json" }
  },
  "overrides": {
    "description": "Everything about your pets."
  },
  "operations": {
    "create": {
      "defaults": { "body": { "status": "available" } },
      "notes": "Requires the write:pets scope.",
      "overrides": {
        "summary": "Add a new pet to the store",
        "responses": { "405": { "description": "Invalid input" } }
      },
      "parameters": {
        "X-Trace-Id": { "in": "header", "schema": { "type": "string" }, "description": "Tracing id" }
      }
    }
  }
}

Fields

Field	Type	Description
`version`	`1`	File format version.
`baseUrl`	string	Base URL for this resource's requests, overriding the API's. Usually a `{{variable}}`.
`defaults`	object	Creation defaults for this resource's requests (`auth`, `headers`, `cookies`, `middlewares`), merged after the API defaults. Same shapes as in api.json.
`overrides`	object	Resource-level spec overrides (projected onto the resource's tag, e.g. `description`).
`operations`	object	Per-operation metadata, keyed by operation name (see below).
`plugins`	object	Plugin-specific data, namespaced per plugin.

`operations.<name>`

Field	Type	Description
`define`	object	Present only for a locally-defined operation: `{ method, path, operationId }`. Its presence is what distinguishes a defined operation from a mapped one.
`defaults`	object	Creation defaults for this operation: `auth` and `baseUrl` (overriding the resource and API), a template `body`, `middlewares` (with their `options`).
`notes`	string	Free-form notes, shown in the app.
`overrides`	object	Operation-level spec overrides (see below).
`parameters`	object	Additional/overridden parameters, keyed by name.

Overrides

Overrides are projected onto the effective spec. At the operation level the overridable fields are summary, description, tags, deprecated, security, externalDocs, responses.<code>, requestBody, and x-* extensions. Identity fields (method, path, operationId) are not overridable; change those through schema rules.

Parameters

The parameters dictionary is keyed by parameter name. Each entry is merged into the effective spec's parameter list by identity (name + in). Setting an entry to nullremoves that parameter from the effective spec.

Locally-defined operations

The define block lets you add an operation the source spec doesn't have, useful for undocumented endpoints or APIs without a spec. The organizational part (which resource, what name) is created with craftr schema define; the full definition lives here:

"operations": {
  "vaccinations": {
    "define": { "method": "GET", "path": "/pet/{petId}/vaccinations", "operationId": "getPetVaccinations" },
    "overrides": { "summary": "List a pet's vaccinations" },
    "parameters": { "petId": { "in": "path", "required": true, "schema": { "type": "integer" } } }
  }
}

For a defined operation, parameters and overrides (summary, description, requestBody, responses…) are its whole contract, which the operation's Definition tab edits. Promoting it moves that contract into spec.imported.json and removes the define block; see Defining & promoting operations.

Coming soonPlugin data

The plugins namespace is part of the format so plugin config has a home, but the plugin system isn't built yet; see Plugins.