{
  "openapi": "3.1.0",
  "info": {
    "title": "barcoding.dev",
    "version": "0.1.0",
    "description": "The universal barcode and identifier layer of the visibility.cloud family — resolve / verify / generate, pure and local, on every scheme in the pinned registry (GS1 GTIN/GLN/SSCC/Digital Link, VIN, ISBN, UDI, NDC, tracking numbers, AAMVA DL). api.barcoding.dev is its POST-verb machine face. Codec + data, never a resolver: resolution is id.org.ai's, served through this property's delegating doors."
  },
  "servers": [
    {
      "url": "https://barcoding.dev"
    }
  ],
  "paths": {
    "/schemes": {
      "get": {
        "operationId": "listCollection",
        "summary": "The scheme registry — one row per identifier scheme, from the same pinned engine artifacts every other skin renders",
        "description": "The keyless, branching collection (AXP Clauses 4 + 7): plain GET answers 200 OK with substantive typed content to an anonymous caller; a non-matching filter answers 200 EMPTY; a reserved scope answers 403 BLOCKED. Collection member name: \"schemes\".",
        "parameters": [
          {
            "name": "family",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter the collection by family; a non-matching value answers a typed 200 EMPTY, never a fake success"
          },
          {
            "name": "scheme",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter the collection by scheme; a non-matching value answers a typed 200 EMPTY, never a fake success"
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "reserved scopes (admin, internal) answer a typed 403 BLOCKED"
          }
        ],
        "responses": {
          "200": {
            "description": "OK or EMPTY envelope",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/OkEnvelope"
                    },
                    {
                      "$ref": "#/components/schemas/EmptyEnvelope"
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BLOCKED envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockedEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "The Pricing Document (AXP Appendix A.2)",
        "description": "This API is free: {\"model\":\"free\"} — the declaration itself is the obligation (the no-ask-zone law). This price is NOT bound by published terms: it is a stated intent, and the document says so in its `binding` and `statement` members. Budget against it; do not contract on it.",
        "responses": {
          "200": {
            "description": "the Pricing Document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingDocument"
                }
              }
            }
          }
        }
      }
    },
    "/family.json": {
      "get": {
        "operationId": "getFamilyRegistry",
        "summary": "The family registry — sibling properties and their seams as typed edges",
        "description": "Lists the sibling doors of this property's family so an agent at this door discovers the others as contracts, not links.",
        "responses": {
          "200": {
            "description": "the family registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/gs1resolver": {
      "get": {
        "summary": "GS1-Conformant Resolver 1.2.0 description document — the delegating door's own description; resolution itself is id.org.ai's",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/01/{gtin14}": {
      "get": {
        "summary": "Digital Link delegating door: GTIN — typed identity envelope (scheme, canonical form, check verdict)",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "gtin14",
            "description": "the GTIN in 8/12/13/14-digit form; canonicalized to GTIN-14"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/00/{sscc18}": {
      "get": {
        "summary": "Digital Link delegating door: SSCC-18 — typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "sscc18",
            "description": "the 18-digit SSCC"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/417/{gln13}": {
      "get": {
        "summary": "Digital Link delegating door: GLN — typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "gln13",
            "description": "the 13-digit GLN"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/vin/{vin}": {
      "get": {
        "summary": "VIN door — ISO 3779 grammar + check digit, typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "vin",
            "description": "the 17-character VIN"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/isbn/{isbn}": {
      "get": {
        "summary": "ISBN door — an ISBN is a GTIN in the 978/979 prefix; typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "isbn",
            "description": "ISBN-10 or ISBN-13"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/ndc/{ndc}": {
      "get": {
        "summary": "NDC door — US drug code behind the '3'-prefixed UPC; typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "ndc",
            "description": "the NDC in 4-4-2 / 5-3-2 / 5-4-1 form"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/usps-impb/{tracking}": {
      "get": {
        "summary": "USPS IMpb tracking-number door — typed identity envelope; malformed input answers a typed 400, never a silent pass",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "tracking",
            "description": "the USPS IMpb tracking number"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/ups-1z/{tracking}": {
      "get": {
        "summary": "UPS 1Z tracking-number door — typed identity envelope",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "tracking",
            "description": "the UPS 1Z tracking number"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/proofs/{sha256}": {
      "get": {
        "summary": "Proof receipts — content-addressed, immutable, keyless: sha256 of the canonical receipt bytes; an unknown address answers a typed 404",
        "parameters": [
          {
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "name": "sha256",
            "description": "the receipt's sha256 (64 hex chars)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OkEnvelope": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "const": "OK"
          }
        },
        "description": "200 — substantive content. The collection member name (results/items/events…) is this API's own choice, documented on the operation."
      },
      "EmptyEnvelope": {
        "type": "object",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "const": "EMPTY"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "200 — a truthful empty collection, never a bare [] masquerading as data."
      },
      "BlockedEnvelope": {
        "type": "object",
        "required": [
          "type",
          "reason"
        ],
        "properties": {
          "type": {
            "const": "BLOCKED"
          },
          "reason": {
            "type": "string"
          }
        },
        "description": "401/403 — a permission boundary with a worded reason."
      },
      "OfferEnvelope": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "const": "OFFER"
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "price": {},
          "checkoutUrl": {
            "type": "string"
          },
          "alternatives": {
            "type": "array"
          }
        },
        "description": "402 — a payment or ceiling re-authorization boundary; an offer to proceed, never a refusal."
      },
      "PricingDocument": {
        "type": "object",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "enum": [
              "free",
              "metered"
            ]
          },
          "hardCeiling": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "unit": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "binding": {
            "type": "boolean",
            "description": "Whether published terms bind this price. `model` answers what it costs; `binding` answers whether you can hold us to it. Absent means not declared — never assume bound."
          },
          "statement": {
            "type": "string",
            "description": "Present when binding is false: the stated intent, in the same words the human pages use."
          },
          "termsUrl": {
            "type": "string",
            "description": "Present when binding is true: the terms document that binds this price."
          },
          "ledgerUrl": {
            "type": "string",
            "description": "Where the open item to bind this price is tracked."
          }
        },
        "description": "AXP Appendix A.2 — closed model \"free\" | \"metered\"; hardCeiling required and > 0 when metered. `binding` is a descriptive member on an axis orthogonal to `model`: binding: true carries termsUrl, binding: false carries statement."
      }
    }
  }
}