Periodic-Table-JSON is a chemical dataset with a fixed schema

A data file, not a library

Periodic-Table-JSON is a json of the entire periodic table, and the README opens by saying feel free to use it in your projects. There is no package to install and no API to call. The deliverable is PeriodicTableJSON.json at the repository root, and the primary language of the repository is recorded as Python only because the generator scripts in the scripts directory are written in it.

That makes the project interesting precisely because it is a dataset with a documented contract. Anyone who has tried to build a periodic table UI has ended up assembling one of these files from Wikipedia, a chemistry API and a pile of per-element exceptions, and the value here is that somebody else did that work and wrote down the rules.

The README is written as a specification, and it does not oversell anything. Every key that appears is described, every unit is stated, and the awkward cases are called out rather than hidden. The repository carries a LICENSE.md file, and the licence field on GitHub shows as a custom licence that GitHub cannot classify, so that file is the authoritative text if you intend to redistribute the data.

The last push was on 2026-10-04, so the data is being maintained. The release tags tell a different story about cadence: v.4.0.0, described as Electron semantics, lookup json and fixes, is from 2020-07-26, v3.0.0 as Electron Shells is from 2017-02-27, and v2.0.0, described as Revised JSON, now formatted as an array and has new elements, is from 2017-01-02. The data is current; the release naming is not a reliable indicator of how often it changes.

How the units and edge cases are documented

The densest and most useful part of the README is the units section, because this is where chemical datasets usually go wrong.

Temperatures such as boiling points and melting points are given in Kelvin. Densities are given in g/L for gases and g/cm³ for solids and liquids, and molar heat in J/(mol*K). Because the unit of density depends on the phase, every element also has a density_unit key, either g/L or g/cm3, and a density_g_cm3 key.

So there are three density fields, not one, and that is deliberate: a single numeric field with a per-element unit string forces every consumer to branch on phase, while a second numeric field gives a uniform comparison value. A UI can render the native unit, a chart can use density_g_cm3, and neither has to know the phase.

The reference conditions are stated too. Gas densities are for 0 °C and 1 atm. For elements that sublime at atmospheric pressure, carbon and arsenic are named, melt is the triple-point temperature. And values for the heaviest elements are theoretical predictions.

That last clause is the one to carry into your own documentation. A dataset that mixes measured values with predicted ones without saying so is a trap, and this one says so in a single sentence.

Atomic radii are given in pm and are from the Wikipedia data page on atomic radii of the elements, and the radii is given as an array as some elements have multiple radii. The array form matters, because van der Waals radii in particular are reported as a range rather than a single number.

The shape of one element

The README gives the full hydrogen entry as an example, and it is worth reading as a schema rather than as sample data.

{
  "elements": [
    {
      "name": "Hydrogen",
      "appearance": "colorless gas",
      "atomic_mass": 1.008,
      "boil": 20.271,
      "category": "diatomic nonmetal",
      "density": 0.08988,
      "density_unit": "g/L",
      "density_g_cm3": 0.00008988,
      "discovered_by": "Henry Cavendish",
      "melt": 13.99,
      "molar_heat": 28.836,

The top level is an object with a single elements key holding an array. That array shape came in with v2.0.0 in 2017, described in the release notes as Revised JSON, now formatted as an array and has new elements, and it is the right choice for streaming and for a table view.

Beyond the identity fields there is a grid. Hydrogen carries xpos: 1, ypos: 1, wxpos: 1 and wypos: 1, which are the coordinates a periodic table renderer needs to place the element, with the w-prefixed pair being the position in the wide layout used for the lanthanides and actinides. Including layout coordinates in the dataset is what saves a consumer from hardcoding a placement table.

There is also an image object with a title, a url and an attribution string, and the attribution for hydrogen reads User:Jurii, CC BY 3.0 with the licence URL and the originating site. So the data carries its own attribution metadata, which matters if you are rendering these images in a product.

Electron structure, radii and the electron configuration string

The chemistry keys are the part of the dataset with the most structure, and the README explains each convention.

Electron configuration is given as a string with each orbital separated by a space, and electron configuration semantic is given as a string, the short-hand version of the electron configuration. Elements with a semantic electron configuration marked with an asterisk mean that the electron configuration has not yet been confirmed. So the asterisk is a data quality flag, and it is worth honouring in any UI that presents the configuration as fact.

Electron shells are given as an array, the first item being the number of electrons in the first shell, the second the number in the second shell, and so on. Hydrogen's shells array is a single 1.

Ionization energy and first electron affinities are both given as the energy required to detach an electron from the anion, and ionization energies are given as an array for successive ionization energy. That wording is precise and slightly unusual, and it is exactly the kind of thing a README that only listed key names would leave you guessing.

Atomic radii are an object with five keys, empirical, calculated, van_der_waals, covalent_single, covalent_triple and metallic, each holding an array or null. Hydrogen's entry shows empirical [25], calculated [53], van_der_waals [120, 110], covalent_single [32], and covalent_triple and metallic both null.

And the nulls are the point. Information that is missing is represented as null, rather than as zero, an empty string or an absent key. A consumer can therefore distinguish not applicable from not measured, which is the difference between a dataset you can chart and one that quietly plots a wrong zero.

Images, summaries and the source link

Each element carries a few links and a prose blurb, and the README is explicit about where they come from.

A link to a source where the information was from is provided in each element under the key source, and for hydrogen that is the Wikipedia article URL. So every element can be traced back, which is the minimum you should expect from a dataset that mixes measured and predicted values.

There is a link to an image Bohr model of the atom under bohr_model_image, and a link to a 3D-image of the Bohr model under bohr_model_3d, a file obtained from google with the .glb extension, and these 3d models can easily display on web using the google model-viewer script. The hydrogen values point at a storage.googleapis.com path ending in element_001_hydrogen.glb.

Some elements may have an image link to their spectral bands, under the spectral_img key, and hydrogen's points at a Wikipedia file named Hydrogen_Spectra.jpg.

Every element has a three sentence summary from Wikipedia, and the hydrogen one is a good example of the register: it opens with the symbol and atomic number, gives the atomic weight in u, notes that it is the lightest element, and then states that its monatomic form is the most abundant chemical substance in the Universe, constituting roughly 75% of all baryonic mass.

That is encyclopedic text rather than marketing copy, which is the right register for a dataset. It also means the summary will not match a particular nomenclature or naming convention unless you rewrite it, so treat it as a starting description rather than as content you can ship unchanged.

The other two formats, and the schema directory

Besides the original JSON file PeriodicTableJSON.json, the data is provided in additional formats, and the reason for each is different.

The first is a lookup table for easy indexing in periodic-table-lookup.json. For a dataset keyed by name, symbol and atomic number, a lookup file lets a consumer resolve an element with a single map access instead of a linear scan, which matters once you are resolving a user-typed symbol on every keystroke.

The second is a CSV file, one row per element and one column per property, where some subfields are flattened to strings, in periodicTableCSV.csv. Flattening is where the schema shows its cost: the atomic radii object with its five sub-arrays and the shells array do not fit a rectangular grid, so those become string columns that a spreadsheet user can read but a parser has to decode.

These files are generated from the original data via scripts in the scripts directory. That is the workflow that makes the project maintainable: PeriodicTableJSON.json is the source of truth, and the other two are derived artefacts that can be regenerated rather than hand-edited.

The repository layout supports that. There is a schemas directory alongside the data files, which is where a JSON Schema for the dataset would live, and it is the piece to look at first if you are writing a validator or generating typed bindings from it. The scripts directory, the schemas directory and the three data files at the root is a small, legible repository, and there is a .github directory for the workflows.

Editorial conclusion

Periodic-Table-JSON suits a developer building an element browser, a chemistry app or a teaching tool who needs one file with element data already shaped for rendering, since the dataset carries the xpos and ypos grid coordinates, the shell counts and the images that a periodic table view needs. It is the wrong tool for a chemistry calculation package, because it holds reference data and no formulas or reaction logic, and it is the wrong tool when you need a value the README says is a theoretical prediction for the heaviest elements. Before using it, read the units notes, because density is given in g/L for gases and g/cm3 for solids and liquids and there is a separate density_g_cm3 key, and check the LICENSE.md file, because the licence is recorded as a custom one that GitHub cannot classify.

Frequently asked questions

Official sources

1. Bowserinator/Periodic-Table-JSON on GitHub
2. Issues
3. README
4. Releases