{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gunspec-io/json-schema/gunspec-io-attachment-fit-schema.json",
  "title": "AttachmentFit",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gunspec-io-compatibility-api-openapi.yml#/components/schemas/AttachmentFit",
  "allOf": [
    {
      "$ref": "#/$defs/Attachment"
    },
    {
      "type": "object",
      "properties": {
        "fits": {
          "type": "boolean",
          "description": "Whether this attachment fits the firearm. False rows appear only when `include=all` was asked for, and carry `blockedBy`."
        },
        "fitType": {
          "anyOf": [
            {
              "$ref": "#/$defs/FitType"
            },
            {
              "type": "null"
            }
          ],
          "description": "How it fits: `direct` on the firearm own interface, `adapter` through the part named in `adapter`, or `curated` from an override on the attachment. Null when it does not fit."
        },
        "source": {
          "anyOf": [
            {
              "$ref": "#/$defs/FitSource"
            },
            {
              "type": "null"
            }
          ],
          "description": "The weakest evidence behind the fit. Null when it does not fit."
        },
        "via": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FitVia"
          },
          "description": "The interfaces that satisfied the attachment requirements, with where each came from."
        },
        "adapter": {
          "anyOf": [
            {
              "$ref": "#/$defs/AdapterRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "The adapter that bridged the fit, when fitType is adapter"
        },
        "confidence": {
          "type": "number",
          "description": "How well evidenced this row is, 0 to 1. **A minimum, not an average**: an inferred row caps every fit computed through it, and `min_confidence` on the endpoint hides rows below a threshold."
        },
        "reason": {
          "type": "string",
          "description": "Plain-language account of why it fits, safe to show in a UI."
        },
        "blockedBy": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why it does not fit, when `fits` is false: a missing standard, or the caliber, bore and minimum-barrel gate, which no adapter bridges. Null on a fitting row."
        },
        "routes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FitRoute"
          },
          "description": "Every way it goes on, best first; the fields above are the first. Empty for a curated override, a universal fit and a row that does not fit."
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The best route's caveats."
        }
      }
    }
  ],
  "$defs": {
    "AdapterRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Slug of the adapter part."
        },
        "name": {
          "type": "string",
          "description": "Display name, as the maker writes it."
        }
      }
    },
    "Attachment": {
      "description": "One catalogued attachment, as the list returns it.",
      "allOf": [
        {
          "$ref": "#/$defs/AttachmentBase"
        },
        {
          "type": "object",
          "properties": {
            "provides": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Standard ids this adds to the firearm once fitted. Resolved to `{ id, name, kind }` rows on `/v1/attachments/{id}`."
            }
          }
        }
      ]
    },
    "AttachmentBase": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "URL-safe slug identifying the part, e.g. `magpul-zhukov-s-stock`."
        },
        "name": {
          "type": "string",
          "description": "Display name, as the maker writes it."
        },
        "category": {
          "type": "string",
          "description": "What kind of part it is: `stock`, `optic`, `muzzle`, `magazine`, `grip`."
        },
        "manufacturer": {
          "anyOf": [
            {
              "$ref": "#/$defs/ManufacturerRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "Who makes it."
        },
        "modelNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The maker's own SKU, where they publish one."
        },
        "weightG": {
          "type": [
            "number",
            "null"
          ],
          "description": "Weight in grams."
        },
        "lengthMm": {
          "type": [
            "number",
            "null"
          ],
          "description": "Length in millimetres."
        },
        "capacity": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Magazines only"
        },
        "boreDiameterMm": {
          "type": [
            "number",
            "null"
          ],
          "description": "Suppressors and muzzle devices"
        },
        "requiresPosition": {
          "type": [
            "string",
            "null"
          ],
          "description": "The mount position this part occupies, or null when it takes none."
        },
        "isFactoryPart": {
          "type": "boolean",
          "description": "True when the part ships on the firearm from the factory. A factory part carries no `statMods` or `specDeltas`, because the firearm's own figures already include it."
        },
        "factoryFor": {
          "type": [
            "string",
            "null"
          ],
          "description": "The firearm this is the factory part for, when `isFactoryPart` is true."
        },
        "statMods": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Editorial adjustments to the game statistics once fitted, keyed by stat. Same status as `game_*` on a firearm: **not measured**."
        },
        "specDeltas": {
          "type": "object",
          "additionalProperties": {
            "type": [
              "number",
              "null"
            ]
          },
          "description": "Specification changes once fitted, keyed by field: a folding stock changes the folded length, for example."
        },
        "imageUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Absolute URL of the manufacturer product photo on the assets CDN, ready to render. Null when no photo has been sourced yet."
        },
        "status": {
          "$ref": "#/$defs/AttachmentStatus"
        },
        "dataConfidence": {
          "type": [
            "number",
            "null"
          ],
          "description": "How completely the record is specified and how well it is sourced, 0 to 1. A record-level completeness and provenance measure, **not** a per-field probability of correctness. Use it to rank and triage; use `sources` to verify an individual number."
        },
        "updatedAt": {
          "type": "string",
          "description": "When a field we serve last changed. Maintained by the database rather than by whatever wrote the row, so it moves for a corrected specification and does not move for a re-run of the importer."
        },
        "version": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque fingerprint of this record. It changes when and only when a field we serve changes, so a client holding the same value already has the record and need not fetch it. Equality is the only supported operation: do not parse it, and do not assume how it is computed. Null means the record has not been written since versioning began, not that it is unchanged."
        },
        "provenance": {
          "$ref": "#/$defs/Provenance"
        }
      }
    },
    "AttachmentStatus": {
      "type": "string",
      "enum": [
        "in_production",
        "discontinued",
        "limited"
      ],
      "description": "Production status of an attachment. `limited` corresponds to a firearm's `limited_production`."
    },
    "FitRoute": {
      "type": "object",
      "description": "One way an attachment goes on: directly, or through one adapter. Routes are ordered best first: direct before an adapter, over the receiver before forward of it for a sight, then by confidence. The top-level fields of the fit are the first route.",
      "properties": {
        "fitType": {
          "type": "string",
          "enum": [
            "direct",
            "adapter"
          ],
          "description": "How it fits: `direct` on the firearm own interface, `adapter` through the part named in `adapter`, or `curated` from an override on the attachment. Null when it does not fit."
        },
        "adapter": {
          "anyOf": [
            {
              "$ref": "#/$defs/AdapterRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "The adapter this route goes through, or null when the attachment fits directly."
        },
        "via": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FitVia"
          },
          "description": "The interfaces that satisfied the attachment requirements, with where each came from."
        },
        "confidence": {
          "type": "number",
          "description": "How well evidenced this row is, 0 to 1. **A minimum, not an average**: an inferred row caps every fit computed through it, and `min_confidence` on the endpoint hides rows below a threshold."
        },
        "source": {
          "$ref": "#/$defs/FitSource"
        },
        "adapterConfidence": {
          "type": [
            "number",
            "null"
          ],
          "description": "How well the adapter's own record is sourced, 0 to 1, when the route goes through one. Beside `confidence`, which is the evidence for the mount points, rather than folded into it. Null for a direct route."
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What a person fitting it should know that does not stop it fitting: a sight mounted forward on a handguard rail, a scope that needs rings the catalogue does not list, a drop-in handguard cut for one gas system, receivers the maker says it does not fit."
        }
      }
    },
    "FitSource": {
      "type": "string",
      "enum": [
        "curated",
        "universal",
        "inferred",
        "inherited:parent",
        "inherited:platform"
      ],
      "description": "The weakest evidence behind a fit. A retailer or engineering consumer should treat `inferred` as unverified; `min_confidence` hides it."
    },
    "FitType": {
      "type": "string",
      "enum": [
        "direct",
        "adapter",
        "curated"
      ],
      "description": "How a fit was reached: on the firearm's own interface, through one adapter, or by a curated override."
    },
    "FitVia": {
      "type": "object",
      "properties": {
        "position": {
          "type": "string",
          "description": "Where on the firearm the interface sits: `muzzle`, `rear`, `top`, `bottom`."
        },
        "standardId": {
          "type": "string",
          "description": "Id of the interface standard, kind-prefixed, e.g. `thread:1/2x28`. Ids are never renamed; new spellings become aliases."
        },
        "source": {
          "$ref": "#/$defs/InterfaceSource"
        },
        "adapterId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The adapter that bridges this fit, or null when none is needed. Threads, magazine wells and the caliber gate are never bridged."
        }
      }
    },
    "InterfaceSource": {
      "type": "string",
      "enum": [
        "curated",
        "inferred",
        "inherited:parent",
        "inherited:platform"
      ],
      "description": "Where an interface row on a firearm came from. `curated` is a person; `inferred` is the backfill, capped at 0.6 confidence; the inherited kinds came through the parent chain or a platform."
    },
    "ManufacturerRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Slug of the manufacturer."
        },
        "name": {
          "type": "string",
          "description": "Display name, as the maker writes it."
        }
      }
    },
    "Provenance": {
      "type": "object",
      "description": "Where a record's figures came from and how far they have been checked, in one place. `sources` are the pages consulted; check a specific figure against those. `sourceKinds` says what each page is and `bestSourceKind` the strongest of them, on the hierarchy `SourceKind` defines: a maker or standards-body page is evidence for a figure, a retailer or forum page is evidence the item exists. `dataConfidence` is the 0 to 1 score set from what was actually sourced and never raised by hand. `verifiedAt` and `verifiedFields` say when a source was last read against the record and which fields it stated; null means the row is still seed knowledge. `updatedAt` and `version` are the same cache signals the record carries at the top level.",
      "properties": {
        "sources": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The pages consulted when the record was compiled, as an array. Check a specific figure against these rather than against `dataConfidence`."
        },
        "sourceKinds": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Absolute, directly fetchable URL."
              },
              "kind": {
                "$ref": "#/$defs/SourceKind"
              },
              "archivedFrom": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The original address when `url` is a Wayback Machine capture of it. A cited page that no longer answers is replaced by its last capture that answered 200, so the citation still shows what its author read; `kind` is the original page's."
              },
              "rank": {
                "type": "integer",
                "description": "The kind's place in the source hierarchy: 0 is the maker, the strongest; higher is weaker."
              },
              "tier": {
                "type": "string",
                "enum": [
                  "authority",
                  "classified",
                  "unclassified"
                ],
                "description": "Where the site stands in the source registry (`/v1/data/sources`): an authority (the maker, a standards body, a government), a classified site, or one not yet classed."
              },
              "basis": {
                "type": "string",
                "enum": [
                  "declared",
                  "maker",
                  "rule",
                  "unclassified"
                ],
                "description": "What the class rests on: classed by a person, a catalogued maker's own site, a .gov or .mil domain, or nothing yet."
              },
              "evidence": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The words the site was classed on, where a person recorded them."
              }
            },
            "required": [
              "url",
              "kind",
              "archivedFrom",
              "rank",
              "tier",
              "basis",
              "evidence"
            ]
          },
          "description": "What each cited page is, in `sources` order, on the `SourceKind` hierarchy. A host not in the source map is `other`, never guessed."
        },
        "bestSourceKind": {
          "anyOf": [
            {
              "$ref": "#/$defs/SourceKind"
            },
            {
              "type": "null"
            }
          ],
          "description": "The strongest kind among the citations, or null when nothing is cited. `manufacturer` or `standards_body` means a figure can be checked against an authority; `retailer` or `community` alone means the record is still supported by copies of copies."
        },
        "makerSource": {
          "type": [
            "string",
            "null"
          ],
          "description": "The first cited page on the record's own manufacturer's website, or null when it cites none. A page on another maker's site does not count. Cited from the maker is not the same as checked against it: `verifiedFields` names the figures that were read against a source."
        },
        "evidence": {
          "type": "string",
          "enum": [
            "verified",
            "maker",
            "authority",
            "secondary",
            "none"
          ],
          "description": "How far the record's figures are backed, strongest first, for a badge: `verified` when at least one figure was read against a source (`verifiedFields`), `maker` when it cites a page on its own manufacturer's site (`makerSource`), `authority` when it cites a maker, standards body or government page, `secondary` when it cites only press, retailers, references or forums, `none` when it cites nothing. Derived from the fields beside it."
        },
        "checks": {
          "type": "object",
          "description": "The checks the record has been through, on a single record's response only: every task the data agent (Redback) or a person was given about it, what each proposed, the pages it read, and whether a person accepted it. Nothing an agent proposes reaches the record until a person accepts it, so this is the trail behind `verifiedFields`. Who reviewed is not published; an agent's instance name is.",
          "properties": {
            "raised": {
              "type": "integer",
              "description": "Every task ever raised on the record, answered or not."
            },
            "open": {
              "type": "integer",
              "description": "Tasks still waiting to be worked."
            },
            "history": {
              "type": "array",
              "description": "The latest twenty, newest first.",
              "items": {
                "type": "object",
                "properties": {
                  "task": {
                    "type": "string",
                    "description": "The task id, stable across runs; the same id `/v1/data/tasks/{taskKey}` answers for."
                  },
                  "number": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "The task's number; `/v1/data/tasks/{number}` loads it as its key does."
                  },
                  "check": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The check that raised it, where one did."
                  },
                  "kind": {
                    "type": "string",
                    "description": "`verify` reads the record against its maker's page, `gap` researches an empty field, `contradiction` judges fields that disagree, `vocabulary` a value outside a list."
                  },
                  "agent": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "`redback` when the agent worked it, `staff` when a person did, null when nobody has."
                  },
                  "worker": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The agent instance that worked it; null for a person."
                  },
                  "status": {
                    "type": "string",
                    "description": "`resolved` (a proposal was filed), `unverifiable` (nothing could be established; retried after a cooldown), `not_a_fault`, or open."
                  },
                  "decidedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "When the task was answered; null while it is open."
                  },
                  "proposed": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "What it proposed, in its own words; null while it is open."
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Per-field completeness, keyed by column name."
                  },
                  "sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The pages it read and quoted."
                  },
                  "review": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "decision": {
                        "type": "string",
                        "enum": [
                          "accepted",
                          "rejected"
                        ],
                        "description": "Whether a person accepted the proposal."
                      },
                      "at": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "When they decided."
                      }
                    },
                    "description": "A person's decision on the proposal; null until reviewed."
                  },
                  "finding": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "What the check found, where a check raised the task: its own line for this record and the figures it measured, so a reader sees how the value breaks the method. The same the public task board serves with `include=research`.",
                    "properties": {
                      "why": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The check's line for this record."
                      },
                      "evidence": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "additionalProperties": true,
                        "description": "The figures the check measured."
                      }
                    },
                    "required": [
                      "why",
                      "evidence"
                    ]
                  }
                },
                "required": [
                  "task",
                  "number",
                  "check",
                  "kind",
                  "agent",
                  "worker",
                  "status",
                  "decidedAt",
                  "proposed",
                  "fields",
                  "sources",
                  "review",
                  "finding"
                ]
              }
            }
          },
          "required": [
            "raised",
            "open",
            "history"
          ]
        },
        "dataConfidence": {
          "type": [
            "number",
            "null"
          ],
          "description": "The 0 to 1 score set from what was actually sourced, never raised by hand. See the confidence bands in the docs."
        },
        "verifiedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "When a source was last read against this record. Null means the row is still seed knowledge."
        },
        "verifiedFields": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Which fields the source stated, as an array. Everything else on a verified row is still unverified. Null where no source has been read."
        },
        "specSource": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cartridges only: the page the drawing figures were taken from. Null on every other kind of record."
        },
        "updatedAt": {
          "type": "string",
          "description": "When a served column last changed; the same value the record carries at the top level."
        },
        "version": {
          "type": [
            "string",
            "null"
          ],
          "description": "The record's content version, equal to the top-level `version`; equal versions mean equal data."
        }
      },
      "required": [
        "sources",
        "sourceKinds",
        "bestSourceKind",
        "makerSource",
        "evidence",
        "dataConfidence",
        "verifiedAt",
        "verifiedFields",
        "specSource",
        "updatedAt",
        "version"
      ]
    },
    "SourceKind": {
      "type": "string",
      "enum": [
        "manufacturer",
        "standards_body",
        "government",
        "peer_reviewed",
        "reference",
        "aggregator",
        "press",
        "retailer",
        "community",
        "other"
      ],
      "description": "What kind of page a cited source is, strongest first: the maker's own page, a standards body (SAAMI, C.I.P.), a government or military document, an independent reference work, a specification aggregator, the press, a retailer or auction listing, a community site, or an unclassified page. Weigh a figure by the best kind behind it, never by how many pages were cited."
    }
  }
}