Description
Filter supplied normalized food-composition records by an inclusive per-100-gram nutrient range in one explicit unit, then reuse the food catalog selector and return full selected records with provenance; missing nutrients are unknown, not zero, and no dietary recommendation is implied.
Nutrient amounts per 100 g compare foods on a common mass basis. Selecting a food within a numeric nutrient range is different from choosing a serving size, evaluating a diet, or checking individual medical and allergy needs.
Filter supplied normalized food-composition records by an inclusive per-100-gram nutrient range in one explicit unit, then reuse the food catalog selector and return full selected records with provenance; missing nutrients are unknown, not zero, and no dietary recommendation is implied.
When to use this tool
Use this generator to create reproducible food by nutrient cases from the supplied model or bank. Inspect the returned evidence before using cases in a test or exercise.
How to use the tool and how it works
- Supply foods, nutrientId, unit, minimumPer100g, maximumPer100g, datasetId, datasetVersion, sourceId, selectionCount, withReplacement in the field shapes below. Set seed when you need an explicit replay.
- Run the tool and correct any input error. For generated controls, distinguish a successful fixture containing an invalid case from failure to generate the fixture.
- Read selectedFoods, eligibleCount, datasetId, datasetVersion, sourceId. Use the conventions below. Keep answer-bearing fields separate when presenting an exercise.
Validate supplied food IDs and source metadata, find the requested nutrient with exactly matching units, and filter inclusively by amount per 100 g. Delegate sampling from eligible food IDs under the replacement policy and retain dataset/version/source provenance.1
Delegated operations used for this result: food. Their calculation or parsing conventions apply to the corresponding result fields.2
| Input field | Meaning and units | Accepted input |
|---|---|---|
| foods | Foods | Required. Array of Object; no unknown keys.; maximum items 128. |
| foods[].aliases | Aliases | Required. Array of Text; minimum UTF-16 length 1; maximum UTF-16 length 128.; maximum items 32. |
| foods[].category | Category | Required. Text; maximum UTF-16 length 256. |
| foods[].dataType | Data Type | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| foods[].description | Description | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 2048. |
| foods[].fdcId | Fdc Id | Required. Safe integer; minimum 1. |
| foods[].id | Literal identifier used independently of display labels. | Required. Text; maximum UTF-16 length 64. |
| foods[].name | Name | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 512. |
| foods[].nutrients | Nutrients | Required. Array of Object; no unknown keys.; minimum items 1; maximum items 64. |
| foods[].nutrients[].amountPer100g | Amount Per100g | Required. Finite number; minimum 0. |
| foods[].nutrients[].derivationCode | Derivation Code | Required. Text; maximum UTF-16 length 128. or Null. |
| foods[].nutrients[].id | Literal identifier used independently of display labels. | Required. Text; minimum UTF-16 length 10; maximum UTF-16 length 128. |
| foods[].nutrients[].label | Supplied display label. | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| foods[].nutrients[].sourceNutrientId | Source Nutrient Id | Required. Safe integer; minimum 1. |
| foods[].nutrients[].unit | Unit | Required. Text; one of "g", "kcal", "kJ", "mg", "ug". |
| foods[].portions | Portions | Required. Array of Object; no unknown keys.; maximum items 24. |
| foods[].portions[].description | Description | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 512. |
| foods[].portions[].grams | Grams | Required. Finite number; strictly above 0. |
| foods[].publicationDate | Publication Date | Required. Text; maximum UTF-16 length 128. or Null. |
| foods[].source | Source | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| nutrientId | Nutrient Id | Required. Text; minimum UTF-16 length 10; maximum UTF-16 length 128. |
| unit | Unit | Required. Text; one of "g", "kcal", "kJ", "mg", "ug". |
| minimumPer100g | Minimum Per100g | Required. Finite number; minimum 0. |
| maximumPer100g | Maximum Per100g | Required. Finite number; minimum 0. |
| datasetId | Dataset Id | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| datasetVersion | Dataset Version | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| sourceId | Source Id | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| selectionCount | Selection Count | Required. Safe integer; minimum 1; maximum 128. |
| withReplacement | With Replacement | Required. Boolean. |
| seed | Optional numeric seed; takes precedence over context randomness. Without either, use the fixed tool.io default seed. | Optional. Safe integer. |
| Output field | Interpretation | Returned shape |
|---|---|---|
| selectedFoods | Selected Foods | Required. Array of Object; no unknown keys.; minimum items 1; maximum items 128. |
| selectedFoods[].aliases | Aliases | Required. Array of Text; minimum UTF-16 length 1; maximum UTF-16 length 128.; maximum items 32. |
| selectedFoods[].category | Category | Required. Text; maximum UTF-16 length 256. |
| selectedFoods[].dataType | Data Type | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| selectedFoods[].description | Description | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 2048. |
| selectedFoods[].fdcId | Fdc Id | Required. Safe integer; minimum 1. |
| selectedFoods[].id | Literal identifier used independently of display labels. | Required. Text; maximum UTF-16 length 64. |
| selectedFoods[].name | Name | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 512. |
| selectedFoods[].nutrients | Nutrients | Required. Array of Object; no unknown keys.; minimum items 1; maximum items 64. |
| selectedFoods[].nutrients[].amountPer100g | Amount Per100g | Required. Finite number; minimum 0. |
| selectedFoods[].nutrients[].derivationCode | Derivation Code | Required. Text; maximum UTF-16 length 128. or Null. |
| selectedFoods[].nutrients[].id | Literal identifier used independently of display labels. | Required. Text; minimum UTF-16 length 10; maximum UTF-16 length 128. |
| selectedFoods[].nutrients[].label | Supplied display label. | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| selectedFoods[].nutrients[].sourceNutrientId | Source Nutrient Id | Required. Safe integer; minimum 1. |
| selectedFoods[].nutrients[].unit | Unit | Required. Text; one of "g", "kcal", "kJ", "mg", "ug". |
| selectedFoods[].portions | Portions | Required. Array of Object; no unknown keys.; maximum items 24. |
| selectedFoods[].portions[].description | Description | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 512. |
| selectedFoods[].portions[].grams | Grams | Required. Finite number; strictly above 0. |
| selectedFoods[].publicationDate | Publication Date | Required. Text; maximum UTF-16 length 128. or Null. |
| selectedFoods[].source | Source | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| eligibleCount | Eligible Count | Required. Safe integer; minimum 1; maximum 128. |
| datasetId | Dataset Id | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| datasetVersion | Dataset Version | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| sourceId | Source Id | Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128. |
| randomness | Replay source and normalized 32-bit seed, or null seed for an advancing context source. | Required. Object; no unknown keys. |
| randomness.seed | Optional safe-integer replay seed; normalization and precedence are explained below. | Required. Safe integer. or Null. |
| randomness.source | Source | Required. Text; one of "context", "seed". |
An explicit safe-integer seed takes precedence over injected context randomness and is normalized to an unsigned 32-bit integer. With no seed and no context source, replay uses the fixed tool.io default seed. A context source must return finite values from zero inclusive to one exclusive; its advancing state must be retained separately. randomness records the source and normalized seed, or null for context. These generators are not cryptographic random sources.
json
{
"input": {
"foods": [
{
"aliases": [
"Synthetic pulse A"
],
"category": "Synthetic fixtures",
"dataType": "Synthetic",
"description": "Synthetic food-composition fixture A, not a published USDA record.",
"fdcId": 1,
"id": "usda-fdc-1",
"name": "Synthetic pulse A",
"nutrients": [
{
"amountPer100g": 21,
"derivationCode": null,
"id": "nutrient.protein",
"label": "Protein",
"sourceNutrientId": 1003,
"unit": "g"
}
],
"portions": [
{
"description": "Synthetic 150 g portion",
"grams": 150
}
],
"publicationDate": null,
"source": "synthetic-fixtures-v1"
},
{
"aliases": [],
"category": "Synthetic fixtures",
"dataType": "Synthetic",
"description": "Synthetic food-composition fixture B, not a published USDA record.",
"fdcId": 2,
"id": "usda-fdc-2",
"name": "Synthetic grain B",
"nutrients": [
{
"amountPer100g": 12,
"derivationCode": null,
"id": "nutrient.protein",
"label": "Protein",
"sourceNutrientId": 1003,
"unit": "g"
}
],
"portions": [],
"publicationDate": null,
"source": "synthetic-fixtures-v1"
},
{
"aliases": [],
"category": "Synthetic fixtures",
"dataType": "Synthetic",
"description": "Synthetic food-composition fixture C, not a published USDA record.",
"fdcId": 3,
"id": "usda-fdc-3",
"name": "Synthetic seed C",
"nutrients": [
{
"amountPer100g": 28,
"derivationCode": null,
"id": "nutrient.protein",
"label": "Protein",
"sourceNutrientId": 1003,
"unit": "g"
}
],
"portions": [],
"publicationDate": null,
"source": "synthetic-fixtures-v1"
}
],
"nutrientId": "nutrient.protein",
"unit": "g",
"minimumPer100g": 15,
"maximumPer100g": 30,
"datasetId": "nutrition/synthetic-food-fixtures",
"datasetVersion": "1",
"sourceId": "synthetic-fixtures-v1",
"selectionCount": 2,
"withReplacement": false,
"seed": 42
},
"output": {
"selectedFoods": [
{
"aliases": [],
"category": "Synthetic fixtures",
"dataType": "Synthetic",
"description": "Synthetic food-composition fixture C, not a published USDA record.",
"fdcId": 3,
"id": "usda-fdc-3",
"name": "Synthetic seed C",
"nutrients": [
{
"amountPer100g": 28,
"derivationCode": null,
"id": "nutrient.protein",
"label": "Protein",
"sourceNutrientId": 1003,
"unit": "g"
}
],
"portions": [],
"publicationDate": null,
"source": "synthetic-fixtures-v1"
},
{
"aliases": [
"Synthetic pulse A"
],
"category": "Synthetic fixtures",
"dataType": "Synthetic",
"description": "Synthetic food-composition fixture A, not a published USDA record.",
"fdcId": 1,
"id": "usda-fdc-1",
"name": "Synthetic pulse A",
"nutrients": [
{
"amountPer100g": 21,
"derivationCode": null,
"id": "nutrient.protein",
"label": "Protein",
"sourceNutrientId": 1003,
"unit": "g"
}
],
"portions": [
{
"description": "Synthetic 150 g portion",
"grams": 150
}
],
"publicationDate": null,
"source": "synthetic-fixtures-v1"
}
],
"eligibleCount": 2,
"datasetId": "nutrition/synthetic-food-fixtures",
"datasetVersion": "1",
"sourceId": "synthetic-fixtures-v1",
"randomness": {
"seed": 42,
"source": "seed"
}
}
}Limitations and assumptions
- The tool consumes a supplied food snapshot; it does not download USDA records or verify their freshness. Missing nutrients exclude foods, while unit mismatch is an error rather than a conversion. Eligibility is not a dietary recommendation.
- A replay requires the same complete input and implementation. The stated sampling convention applies within its eligible space. A finite draw does not exhaust all possible outputs; repeats remain possible unless a distinct-selection rule is explicit.
- The field tables state structural bounds; cross-field constraints and bounded search or output budgets also apply. Unknown keys are rejected where the object contract disallows them. Input errors are distinct from null fields and deliberate invalid controls in a successful output.
Alternative or Complementary methods
For a supplied example, inspect the returned construction or delegated check directly. To evaluate a consumer, also test cases chosen for its own boundaries; a generated finite corpus does not establish exhaustive coverage.
References
Similar or alternative tools
- Macronutrient split
Convert a calorie target and carbohydrate, protein, and fat percentage split into corresponding gram targets using the standard 4–4–9 energy factors.
- Stratified row sample
Sample supplied records under exact stratum quotas and replacement rules, retaining row inclusion probabilities and observed draw counts.