CatalogSharedParameter

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gribstream-com/json-schema/gribstream-com-catalog-shared-parameter-schema.json",
  "title": "CatalogSharedParameter",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gribstream-com-openapi.yml#/components/schemas/CatalogSharedParameter",
  "type": "object",
  "required": [
    "code",
    "label",
    "default_request",
    "default_request_literal"
  ],
  "properties": {
    "resolved_match": {
      "$ref": "#/$defs/CatalogSharedParameterMatch"
    },
    "resolution_guidance": {
      "type": "string",
      "description": "Recovery guidance when the requested dataset has no validated mapping; supported_datasets supplies alternatives."
    },
    "code": {
      "type": "string",
      "description": "Stable public preset identifier for this shared cross-dataset signal."
    },
    "label": {
      "type": "string"
    },
    "display_label": {
      "type": "string",
      "description": "Human-friendly picker label that includes the stable preset code and descriptive label."
    },
    "summary": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "units": {
      "type": "string"
    },
    "default_request": {
      "$ref": "#/$defs/CatalogRequestFragment"
    },
    "default_request_literal": {
      "type": "string",
      "description": "Compatibility helper containing the same content as `default_request`, rendered as a JSON object fragment without outer braces."
    },
    "dataset_requests": {
      "type": "array",
      "description": "Explicit per-dataset overrides for datasets that differ from `default_request`.",
      "items": {
        "$ref": "#/$defs/CatalogSharedParameterDatasetRequest"
      }
    },
    "supported_datasets": {
      "type": "array",
      "description": "Dataset codes for which this preset is intended to be supported.",
      "items": {
        "type": "string"
      }
    },
    "resolved_dataset": {
      "type": "string",
      "description": "Dataset code used to resolve the preset when the optional `dataset` query parameter is provided."
    },
    "resolved_supported": {
      "type": "boolean",
      "description": "Whether the requested `resolved_dataset` is supported by this preset."
    },
    "resolved_request": {
      "$ref": "#/$defs/CatalogRequestFragment"
    },
    "resolved_request_literal": {
      "type": "string",
      "description": "Compatibility helper containing the same content as `resolved_request`, rendered as a JSON object fragment without outer braces."
    },
    "catalog_updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CatalogRequestFragment": {
      "type": "object",
      "description": "Machine-readable request fragment that can be copied into forecast query payloads.\n\nThis is the primary structured representation for shared parameter presets.\n",
      "properties": {
        "variables": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/VariableSelector"
          }
        },
        "expressions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ExpressionField"
          }
        }
      },
      "additionalProperties": false
    },
    "CatalogSharedParameterDatasetRequest": {
      "type": "object",
      "required": [
        "dataset",
        "request",
        "request_literal"
      ],
      "properties": {
        "match": {
          "$ref": "#/$defs/CatalogSharedParameterMatch"
        },
        "dataset": {
          "type": "string"
        },
        "request": {
          "$ref": "#/$defs/CatalogRequestFragment"
        },
        "request_literal": {
          "type": "string",
          "description": "Compatibility helper containing the same request content as a JSON object fragment without outer braces, suitable for direct embedding into a forecast request body by string-templating clients."
        }
      },
      "additionalProperties": false
    },
    "CatalogSharedParameterMatch": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "exact",
            "approximate"
          ],
          "description": "Semantic match to the shared concept, not identical values across models. A 1.5 m near-surface substitute is approximate, with no height correction."
        },
        "method": {
          "type": "string",
          "enum": [
            "direct",
            "derived"
          ]
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "ExpressionField": {
      "type": "object",
      "required": [
        "expression"
      ],
      "properties": {
        "expression": {
          "type": "string",
          "description": "Expr-language formula compiled by the server."
        },
        "alias": {
          "type": "string",
          "description": "Response key for the expression output.\n\nThe wire format allows this to be omitted, but practical clients should set it.\n"
        },
        "hidden": {
          "type": "boolean",
          "description": "When `true`, the expression result remains available to later expressions and filters,\nbut is omitted from response rows.\n"
        }
      },
      "additionalProperties": false
    },
    "VariableSelector": {
      "type": "object",
      "description": "Exact dataset selector tuple used in forecast queries.\n\nSelectors are not free-form. `name`, `level`, and optional `info` must exactly match a\nselector published for the chosen dataset, either from the dataset catalog endpoints or the\ndataset model/inventory page. Do not invent selectors from natural-language descriptions.\n",
      "required": [
        "name",
        "level"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "GRIB short name exactly as exposed by the dataset inventory or catalog. Case-sensitive. Examples include `TMP`, `UGRD`, `APCP`, `100u`, and `2t`."
        },
        "level": {
          "type": "string",
          "description": "Level text exactly as exposed by the dataset inventory or catalog variation. Must match the published selector tuple exactly."
        },
        "info": {
          "type": "string",
          "description": "Optional extra qualifier from the published selector tuple. Blank string is common. Do not invent natural-language qualifiers here."
        },
        "alias": {
          "type": "string",
          "description": "Optional response key.\n\nIf omitted, the current handlers emit the column as `NAME|LEVEL|INFO`.\n"
        },
        "hidden": {
          "type": "boolean",
          "description": "When `true`, the field is loaded and remains available to expressions and filters,\nbut is omitted from response rows. Shared-parameter derived requests use this for\nintermediate helper inputs such as wind vector components.\n"
        }
      },
      "additionalProperties": false
    }
  }
}