EntitySchema Forge

A semi-automatic Wikidata EntitySchema editor built with Vue, Wikimedia Codex, Flask, and the existing shapespresso ShEx parsing and generation code.

The app samples up to 100 direct instances of a Wikidata class, proposes constraints, and lets users add, reject, edit, and undo changes to a draft. It also converts between ShExC and ShExJ. Drafts and undo history live in the browser's memory; starting a new generation or reloading the page clears them.

Source: https://gitlab.wikimedia.org/toolforge-repos/esgen

Repository layout

• backend/app.py: Flask API and static-file serving.
• frontend/: Vue and Wikimedia Codex source, Vite configuration, and npm lockfile.
• backend/static/: committed frontend build output, served by Flask.
• shapespresso/: the Python modules needed by this web app.
• requirements.txt: Python runtime dependencies, including Gunicorn.
• Procfile: Toolforge's web process, importing backend.app:app.
• .python-version: Python 3.11 for the build service.

This directory is a standalone repository. Run Python commands from its root; the application must not rely on the parent research project or its environment. The legacy Gradio app, experiments, and datasets are not needed here.

Install locally

Use Python 3.11, Git, Node.js, and npm. Node.js must satisfy the engine requirements in frontend/package-lock.json. Start in this repository's root.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip check

The two Git-based parser dependencies are pinned to the revisions used by the existing app. Other packages keep the app's existing version pins; Gunicorn is new. The clean Python 3.11 installation and runtime still need verification.

Build the frontend

From the repository root:

npm --prefix frontend ci
npm --prefix frontend run build

Vite replaces backend/static/ with the new build. Commit this directory along with frontend source changes. The initial files in backend/static/ were copied from the existing app; they have not been rebuilt as part of this extraction.

This deployment uses a local frontend build. Toolforge builds the Python image and serves the committed assets; it does not run the frontend build automatically.

Run and verify locally

With the virtual environment activated, run the same command as Procfile:

gunicorn --bind=0.0.0.0:8000 --workers=1 --worker-class=gthread --threads=2 backend.app:app

For development with live frontend updates, use two terminals at the repository root, activating the Python environment in the first:

python -m backend.app

npm --prefix frontend run dev

Open the URL printed by Vite. Its development server proxies /api to port 8000. Stop the previous Gunicorn process before starting Flask on the same port.

SPARQL endpoint and timeouts

Leaving Endpoint URL empty uses https://query.wikidata.org/sparql. Queries are sent by the Flask server. When hosted on Toolforge, an endpoint such as http://localhost:1234/api/endpoint/sparql refers to the Toolforge container, not the visitor's computer. A custom endpoint must be reachable from that server.

Each SPARQL request has a 120-second client timeout. This does not extend WDQS's server-side query limit or set a deadline for the entire generation, which makes multiple requests. Public WDQS queries can still fail or be rate-limited. The threaded Gunicorn worker can remain responsive while queries wait; this does not override upstream proxy timeouts.

License

Original EntitySchema Forge source code is licensed under the BSD 3-Clause License. See LICENSE for the full terms.

Third-party dependencies retain their own copyrights and licenses. In particular, the pinned Wikimedia Codex 2.3.4 dependency is licensed under GPL-2.0-or-later. The BSD license does not replace that license; distribution of the combined frontend must comply with the GPL. Before public distribution, include the required dependency copyright notices and license texts, and provide the complete corresponding source code, including the bundled dependencies and build instructions. This README notice and the npm lockfile do not replace those distribution requirements.

The shapespresso EMNLP paper is licensed separately under CC BY 4.0; its license does not determine the software license.