BUG: Fix TypeError in json_normalize with non-str meta key and record_path

[dongwonmoon]

• closes BUG: pd.json_normalize has inconsistent validation for non-string keys - accepts integers in some parameter combinations but rejects in others #63019 (Replace xxxx with the GitHub issue number)
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[dongwonmoon]

Hi reviewers,

P.S. While working on this fix, I noticed that the type hint for the meta parameter is currently specified as str | list[str | list[str]].

My PR ensures that non-string keys (like the int key in our test case) are handled consistently, whether record_path is specified or not. This aligns with the existing behavior when record_path=None, which already supports non-string keys (mirroring pd.DataFrame's ability to have non-string column names).

I've kept this PR scoped strictly to fixing the TypeError and ensuring consistent behavior.

Would a separate, follow-up issue or PR to discuss updating the type hint (perhaps to something like Hashable or Any) to match this behavior be welcome? Just wanted to bring it to your attention.

Thanks!

[rhshadrach]

The docs state meta should be a string or list of strings.

https://pandas.pydata.org/docs/reference/api/pandas.json_normalize.html

Why are we supporting non-strings?

[dongwonmoon]

When record_path is None: pd.json_normalize([{'a': 1, 12: 'val'}], meta=[12]) already works perfectly. It correctly creates an integer column named 12, which is very useful and consistent with pd.DataFrame itself supporting non-string column names.

When record_path is set: As this issue shows, the exact same call (meta=[12]) suddenly fails with a TypeError simply because record_path was added.

This felt like a clear bug. My PR doesn't introduce new support for non-strings; it just fixes the TypeError so the function behaves consistently with itself, whether record_path is used or not.

It seemed better to fix this inconsistency (Path 1) rather than introduce a new breaking change to remove the existing, undocumented support from Path 2 (e.g., by adding a TypeError to the record_path=None case).

[rhshadrach]

I'm negative on expanding the scope of json_normalize to handle invalid JSON data.

My PR doesn't introduce new support for non-strings; it just fixes the TypeError so the function behaves consistently with itself, whether record_path is used or not.

This is supporting non-strings.

[dongwonmoon]

You are correct that the docs specify str, but the function's actual behavior already differs from the docs.
When record_path=None, json_normalize already works perfectly with non-string keys (like int). This is the existing behavior my PR is based on.
My PR is just a bug fix to make the function behave consistently, fixing the TypeError that only happens when record_path is added.

[dongwonmoon]

import pandas as pd

data = [
    {
        "a": 1,
        12: "meta_value_1",  # int key
        "nested": [{"b": 2, "c": 3}],
    },
    {
        "a": 6,
        12: "meta_value_2",
        "nested": [{"b": 7, "c": 8}],
    },
]

df = pd.json_normalize(
    data,
    record_path=None,
    meta=[12, "a"],
)

print(df)
print(type(df.columns[1]))