`urljsf`#

docs	install	build

Build statically-hostable, interactive HTML forms for making web requests

Powered by react-json-schema-form and react-bootstrap.

Visitors to a urljsf-built page see:

one or more interactive HTML forms…
- defined by and validated against a JSON Schema, optionally with…
- deep customizable user interface
- pre-filled data
- custom validation checks

Once the data is validated, the user sees a button which gets a URL, which can be:

downloaded as a file
opened in a new browser window
copy and pasted
submitted to an HTTP endpoint, either by opening a new window, or directly.
open native applications like email

urljsf doesn’t ship a server, so that part is up to you!

Site builders write TOML, JSON, YAML or python, then can use urljsf as:

a drop-in-and-pray script
a standalone CLI tool
a sphinx extension

… to create JavaScript/HTML forms that helps visitors provide good data for:

pull requests
issues
galleries
surveys
on-demand build services
precise test descriptions
linter rules

Install#

From PyPI#

urljsf is distributed on PyPI:

pip install urljsf

# or...
uv install urljsf

# etc.

From conda-forge#

urljsf is also distributed on conda-forge:

pixi add urljsf

# or...
micromamba install -c conda-forge urljsf

# or...
mamba install -c conda-forge urljsf

# or...
conda install -c conda-forge urljsf

Development#

See the contributing guide for a development install.

Usage#

urljsf work with some JSON schema constrained files as a:

(not-recommended) hot-linked script
a standalone site generator for simple sites
a plugin for the sphinx documentation system

JSON Schema#

A urljsf is built from a number of JSON schema-constrained files. Writing these in plain JSON is tedious, so TOML and YAML are also supported inputs for any of the methods below. Learn more on the schema documentation.

JS Script#

A very simple, but limited, usage is an .html file that links to urljsf and bootstrap resources on the internet.

<script type="application/vnd.deathbeds.urljsf.v0+toml">
  [forms.url.schema]
  title = "pick an xkcd"
  description = "this will redirect to `xkcd.com`"
  type = "object"
  required = ["xkcd"]
  properties.xkcd = {type="integer", minimum=1, maximum=2997}

  [forms.url.ui_schema.xkcd."ui:options"]
  widget = "range"

  [templates]
  url = "https://xkcd.com/{{ data.url.xkcd }}"
  submit_button = "see xkcd #{{ data.url.xkcd }}"
</script>
<script
  type="module"
  src="https://deathbeds.github.io/urljsf/_static/index.js"
></script>

This technique has many limitations, and is not recommended.

Some ways to improve:

download a GitHub release and unpack it, serving the files next to it
ensure bootstrap is loaded before the script, with a link tag in a head.
on the script element, use a src to point to a valid urljsf definition
use the CLI or Sphinx extension

Command Line#

The urljsf command line generates a ready-to-serve, standalone site with all required static assets. Written in python, it can reuse the extensive JSON schema support in the python ecosystem, such as msgspec or pydantic.

prsf --help

urljsf requires at least a definition file, but offers many command line options: see the documentation for more.

Sphinx#

After installing, add urljsf.sphinxext to conf.py:

# conf.py
extensions = [
  # ... other extensions
  "urljsf.sphinxext",
]

Then use the urljsf directive in source files:

.. urljsf:  # a relative path to a description as a TOML, YAML, or JSON file or python
  :toml:
  # a form definition in TOML

See the documentation for more about configuring urljsf.sphinxext, the urljsf directive, and more advanced use cases.

Limitations#

react-json-schema-form cannot represent all possible data structures, such as writing a new JSON schema in JSON schema, or many features added after Draft 7
the generated scripts won’t work when served from file:// due to browser CORS headers requirements for type="module" scripts
the sphinx integration is only tested with the html builder

Open Source#

urljsf itself is licensed under the BSD-3-Clause license. You can do whatever you want with it, but if you change it a lot, it’s not the maintainers’ problem.

urljsf distributes third-party JavaScript and CSS in various forms, licensed under the MIT, BSD-3-Clause, and ISC licenses.

urljsf#