{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bettermenu/json-schema/bettermenu-get-ingredient-response-schema.json",
  "title": "GetIngredientResponse",
  "description": "One resolved ingredient — custom or standard, by id.\n\n``status``/``used_in_recipes``/``density_g_per_ml``/``reference_amount``/\n``reference_unit``/``reference_quantity_g`` are populated for\n`kind: \"custom\"` results only; ``source``/``category``/``brand_name``/\n``brand_owner`` are populated for `kind: \"standard\"` results only.\n``nutrients``/``portions`` are populated for either kind — empty only\nfor a custom ingredient with no reference gram basis entered yet, or\nan id the rich resolver has nothing for.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bettermenu-studio-api-openapi.yml#/components/schemas/GetIngredientResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Ingredient id."
    },
    "name": {
      "type": "string",
      "title": "Name",
      "description": "Ingredient name."
    },
    "kind": {
      "type": "string",
      "title": "Kind",
      "description": "`custom` or `standard`."
    },
    "market": {
      "type": "string",
      "title": "Market",
      "description": "The market this ingredient was resolved for."
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Status",
      "description": "Lifecycle status (`draft`/`active`/`archived`). Populated for `kind: \"custom\"` results only."
    },
    "used_in_recipes": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Used In Recipes",
      "description": "Exact number of the caller's recipes that pin this ingredient. Populated for `kind: \"custom\"` results only."
    },
    "source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Source",
      "description": "`\"ingredient\"` (raw) or `\"product\"` (branded). Populated for `kind: \"standard\"` results only."
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Category",
      "description": "Reference-data food category. Populated for `kind: \"standard\"` results only."
    },
    "brand_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Brand Name",
      "description": "Branded-product brand name. Populated for `kind: \"standard\"` products only."
    },
    "brand_owner": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Brand Owner",
      "description": "Branded-product owner. Populated for `kind: \"standard\"` products only."
    },
    "nutrients": {
      "items": {
        "$ref": "#/$defs/NutrientDetail"
      },
      "type": "array",
      "title": "Nutrients",
      "description": "Nutrient values for this ingredient."
    },
    "portions": {
      "items": {
        "$ref": "#/$defs/IngredientPortionDetail"
      },
      "type": "array",
      "title": "Portions",
      "description": "Serving-size portions for this ingredient."
    },
    "density_g_per_ml": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Density G Per Ml",
      "description": "Density, for volume conversion. Populated for `kind: \"custom\"` results only."
    },
    "reference_amount": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Amount",
      "description": "Reference serving amount, e.g. 15 for '15g'. Populated for `kind: \"custom\"` results only."
    },
    "reference_unit": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Unit",
      "description": "Reference serving unit. Populated for `kind: \"custom\"` results only."
    },
    "reference_quantity_g": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Quantity G",
      "description": "As-sold gram basis for the reference serving. Populated for `kind: \"custom\"` results only."
    }
  },
  "type": "object",
  "required": [
    "id",
    "name",
    "kind",
    "market"
  ],
  "$defs": {
    "IngredientPortionDetail": {
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Id",
          "description": "Real portion id, or `null` for a synthesized entry."
        },
        "origin": {
          "type": "string",
          "title": "Origin",
          "description": "`\"measured\"`, `\"synthesized\"`, or `\"branded_default\"`."
        },
        "amount": {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
          "title": "Amount",
          "description": "Portion amount, e.g. 1 for '1 cup'."
        },
        "unit_name": {
          "type": "string",
          "title": "Unit Name",
          "description": "Measure unit name, e.g. 'cup' — or, for origin=`\"branded_default\"`, a display label verbatim (e.g. \"1 tsp (5g)\")."
        },
        "gram_weight": {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
          "title": "Gram Weight",
          "description": "Weight in grams for this portion."
        },
        "modifier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Modifier",
          "description": "Portion modifier or display label, if any."
        }
      },
      "type": "object",
      "required": [
        "origin",
        "amount",
        "unit_name",
        "gram_weight"
      ],
      "title": "IngredientPortionDetail",
      "description": "One serving-size portion on an ingredient, standard or custom.\n\n``origin`` states where this portion comes from — and for\n`\"branded_default\"`, changes how the other fields must be read:\n\n* `\"measured\"` — a real, independently measured reference-ingredient\n  portion. `amount` and `unit_name` are genuinely meaningful, e.g.\n  `amount=1, unit_name=\"cup\"`.\n* `\"synthesized\"` — derived from a custom ingredient's reference\n  serving; `id` is `null`.\n* `\"branded_default\"` — a branded product's single labeled serving.\n  `id` is a real portion id, but `amount` is always `1` and `unit_name`\n  holds a human-readable label verbatim (e.g. `\"1 tsp (5g)\"`), not a\n  real convertible unit — there is no independent \"amount of a unit\"\n  for a branded product. Render `unit_name` as-is; never decompose it."
    },
    "NutrientDetail": {
      "properties": {
        "bmid": {
          "type": "string",
          "title": "Bmid",
          "description": "Nutrient identity for this market."
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name",
          "description": "Human-readable nutrient name, normalized to market nomenclature by bmid where a mapping exists. Populated for a standard ingredient's nutrients only — a custom ingredient's nutrient carries no display name today."
        },
        "amount": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount",
          "description": "Present-with-value, present-as-zero, or unknown (`null`)."
        },
        "unit": {
          "type": "string",
          "title": "Unit",
          "description": "Unit the amount is expressed in."
        },
        "basis": {
          "type": "string",
          "title": "Basis",
          "description": "`\"per_100g\"` or `\"per_reference_serving\"`."
        }
      },
      "type": "object",
      "required": [
        "bmid",
        "unit",
        "basis"
      ],
      "title": "NutrientDetail",
      "description": "One nutrient value on a resolved ingredient, custom or standard.\n\n``basis`` states which physical quantity ``amount`` is expressed\nrelative to — `\"per_100g\"` for a standard ingredient (USDA\nconvention), `\"per_reference_serving\"` for a custom ingredient (its\nown reference serving). The two must never be compared directly."
    }
  }
}