Previous value: -"Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value."New value: +"Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). On the balancing-authority facets of electricity routes (respondent, fromba, toba, parent, balancing_authority_code), a value also matches when its ISO/RTO acronym contains the text: \"ERCOT\" finds ERCO, \"CAISO\" finds CISO, \"SPP\" finds SWPP and SWPW. A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value."

Previous value: -"Measurement units (e.g. \"cents per kilowatt-hour\")."New value: +"Measurement units (e.g. \"cents per kilowatt-hour\"). An empty string means the route metadata names no unit for this column; the notice then names the eia_query_route row field that holds its unit when a row has one, and a column whose rows have no such field has no unit."

Previous value: -"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP. With values_query, only the matching values, in upstream order."New value: +"Valid values for this facet dimension, starting at values_offset and capped at the window size this server sets. With values_query, only the matching values, in upstream order."

Previous value: -"Values of this facet whose id, name, or alias contains values_query — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set."New value: +"Values of this facet whose id, name, or alias contains values_query — or, on a balancing-authority facet, whose ISO/RTO acronym does — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."New value: +"Default-frequency date-range context, composed with the row field carrying the unit of each data column the route metadata gives no unit, the facet value lists EIA publishes partial, and guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, or unavailable facet values."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."

Previous value: -"Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated. Omit to get every facet."New value: +"Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated, or with values_query to find a value in it. Omit to get every facet."

Previous value: -"Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap."New value: +"Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap. With values_query, indexes the matching values."

Added value: +{
+  "description": "Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value.",
+  "minLength": 1,
+  "type": "string"
+}

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer the route metadata request or the route-tree build in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. A value list that times out is named in unavailable_facets instead. `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "upstream_invalid_response",
-  "upstream_unavailable",
-  "route_not_found",
-  "route_not_queryable",
-  "facet_not_found",
-  "facet_unavailable",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "upstream_timeout",
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Total values this facet has upstream, independent of the returned window."New value: +"Total values this facet has upstream, independent of the returned window and of values_query."

Previous value: -"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP."New value: +"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP. With values_query, only the matching values, in upstream order."

Added value: +{
+  "description": "Values of this facet whose id, name, or alias contains values_query — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set.",
+  "type": "number"
+}

Previous value: -"True when values stops short of value_count. Call eia_describe_route again with this facet ID and values_offset set to values_offset + values.length for the next page."New value: +"True when values stops short of values_matched when values_query is set, otherwise of value_count. Call eia_describe_route again with this facet ID, the same values_query, and values_offset set to values_offset + values.length for the next page."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows or unavailable facet values."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, or unavailable facet values."

Added value: +{
+  "description": "The values_query each facet was narrowed by, as matched after trimming. Absent when no values_query was sent.",
+  "type": "string"
+}

Previous value: -"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\". Full URLs and /data suffixes are not normalized."

Previous value: -"Available date range for this route."New value: +"Route metadata date range in the default-frequency context, not a bound across all frequencies."

Previous value: -"Latest available period."New value: +"Metadata end period for the default frequency; another frequency may extend later."

Previous value: -"Earliest available period."New value: +"Metadata start period for the default frequency; another frequency may extend earlier."

Previous value: -"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "route_not_found",
-  "route_not_queryable",
-  "facet_not_found",
-  "facet_unavailable",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Guidance when values_offset lands past the last value of one or more facets — naming each emptied facet, its value_count, and its last valid offset — or when EIA did not return the value list of a facet named in unavailable_facets. Absent when neither applies."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows or unavailable facet values."

Previous value: -"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `rate_limited`: EIA rate limit hit during facet fan-out. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "route_not_found",
-  "route_not_queryable",
-  "facet_not_found",
-  "rate_limited"
-]New value: +[
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set."New value: +"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set. A facet named in unavailable_facets is left out."

Previous value: -"Guidance when values_offset lands past the last value of one or more facets — names each emptied facet, its value_count, and its last valid offset. Absent when every facet returned values."New value: +"Guidance when values_offset lands past the last value of one or more facets — naming each emptied facet, its value_count, and its last valid offset — or when EIA did not return the value list of a facet named in unavailable_facets. Absent when neither applies."

Added value: +{
+  "description": "Facet IDs whose value lists EIA did not return after retries, left out of facets. Each ID still filters eia_query_route — only its values are missing. Call eia_describe_route again to re-fetch these lists alone. Absent when every facet is in facets.",
+  "items": {
+    "description": "Facet ID whose value list EIA did not return.",
+    "type": "string"
+  },
+  "type": "array"
+}

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "route",
+      "description",
+      "facets",
+      "values_offset",
+      "data_columns",
+      "frequencies",
+      "date_range",
+      "default_frequency",
+      "default_date_format"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `rate_limited`: EIA rate limit hit during facet fan-out. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "route_not_found",
+            "route_not_queryable",
+            "facet_not_found",
+            "rate_limited"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "route",
-  "description",
-  "facets",
-  "values_offset",
-  "data_columns",
-  "frequencies",
-  "date_range",
-  "default_frequency",
-  "default_date_format"
-]

Previous value: -"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."

Previous value: -"Human-readable name."New value: +"Human-readable name. Falls back to the alias, then to the id, on the values EIA sends without one."

Added value: +{
+  "description": "Guidance when values_offset lands past the last value of one or more facets — names each emptied facet, its value_count, and its last valid offset. Absent when every facet returned values.",
+  "type": "string"
+}

Added value: +{
+  "description": "Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated. Omit to get every facet.",
+  "minLength": 1,
+  "type": "string"
+}

Added value: +{
+  "default": 0,
+  "description": "Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

Previous value: -"Filterable dimensions. Each facet has an ID and a set of valid values."New value: +"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set."

Added value: +{
+  "description": "Total values this facet has upstream, independent of the returned window.",
+  "type": "number"
+}

Previous value: -"Valid values for this facet dimension."New value: +"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP."

Added value: +{
+  "description": "True when values stops short of value_count. Call eia_describe_route again with this facet ID and values_offset set to values_offset + values.length for the next page.",
+  "type": "boolean"
+}

Previous value: -[
-  "id",
-  "description",
-  "values"
-]New value: +[
+  "id",
+  "description",
+  "values",
+  "value_count",
+  "values_truncated"
+]

Added value: +{
+  "description": "Index of the first facet value returned, echoing the requested offset.",
+  "type": "number"
+}

Previous value: -[
-  "route",
-  "description",
-  "facets",
-  "data_columns",
-  "frequencies",
-  "date_range",
-  "default_frequency",
-  "default_date_format"
-]New value: +[
+  "route",
+  "description",
+  "facets",
+  "values_offset",
+  "data_columns",
+  "frequencies",
+  "date_range",
+  "default_frequency",
+  "default_date_format"
+]